A Guide to Using the Shortcuts Widget in Flutter For Creating Easy Keyboard Shortcuts

Boosting your app's efficiency and user experience can be achieved through various means, and keyboard shortcuts are a powerful tool in your arsenal. Flutter, a popular framework for building mobile and web apps, provides the “Shortcuts” widget to easily implement keyboard shortcuts in your applications. This widget allows you to define specific key combinations that trigger designated actions within your app, improving the user's interaction experience.

The blog will guide you through everything you need to know about using the Shortcuts widget.

Understanding the Shortcuts Widget

The Shortcuts widget acts as a bridge between keyboard input and specific actions within your app. It primarily consists of two key components:

• child: This mandatory parameter represents the widget that receives keyboard focus. When the user presses a key combination, the focus remains on this child widget, ensuring the shortcut triggers the intended action within its context.

• shortcuts: This parameter defines a map that associates keyboard combinations (ShortcutActivator) with corresponding actions (Callback).

  a. ShortcutActivator: This defines the specific key combination that triggers the action. It can represent single keys with modifiers (e.g., Ctrl + Q), single keys alone (e.g., Escape), or even character-based shortcuts.

  b. Callback: This is a function that gets executed when the user presses the associated ShortcutActivator combination. This function defines the specific action you want to perform within your app when the shortcut is triggered.

The concept of Actions comes into play through the Callback function. Essentially, the Callback defines the specific behavior or functionality you want to trigger when a particular keyboard shortcut is pressed. This allows you to link various actions within your app to specific key combinations, creating a customized and efficient user experience.

Creating Keyboard Shortcuts with Shortcuts Widget

The Shortcuts widget allows you to define custom keyboard shortcuts using various options for key combinations and corresponding actions. Here's how to achieve this:

1. Using LogicalKeySet for Basic Key Combinations:

The LogicalKeySet class helps define combinations of logical keys, offering a platform-agnostic way to specify shortcuts. Here's an example:

Copy
1
2
3
4
5
6
7
8
Shortcuts(
  child: MyWidget(), // The widget receiving focus
  shortcuts: {
    LogicalKeySet(LogicalKeyboardKey.ctrl, LogicalKeyboardKey.keyQ): () {
      // Action to be executed when Ctrl + Q is pressed
    },
  },
)

In this example, pressing Ctrl + Q triggers the Callback function, which defines the desired action within your app.

2. Using Other ShortcutActivator Types:

While LogicalKeySet caters to basic combinations, Flutter offers other ShortcutActivator types for specific scenarios:

• SingleActivator: This is used for single keys, potentially with modifiers like Ctrl or Shift.

For instance:

Copy
1
2
3
4
5
6
7
8
Shortcuts(
  child: MyTextField(),
  shortcuts: {
    SingleActivator(LogicalKeyboardKey.keyC, ctrl: true): () {
      // Action for copying text (Ctrl + C)
    },
  },
)

Here, pressing Ctrl + C triggers the action for copying text.

• CharacterActivator: This defines shortcuts based on specific characters typed. Example:

Copy
1
2
3
4
5
6
7
8
Shortcuts(
  child: MySearchField(),
  shortcuts: {
    CharacterActivator('f'): () {
      // Action for focusing search field (typing 'f')
    },
  },
)

In this case, typing the single character f focuses the search field.

3. Implementing the Callback Function:

The Callback function is the heart of the action. It defines what happens when a specific key combination is pressed. This function can contain any logic you desire, such as:

• Updating the UI state of your app.
• Calling other functions to perform specific actions.
• Triggering navigation events within your app.

Make sure the Callback function doesn't return any value, as its primary purpose is to execute the desired action upon shortcut activation.

Implementing Keyboard Shortcuts:

Define Actions:

Here, SelectAllAction is a custom class to identify the action, and selectAll is the function to be called when the shortcut is triggered.

Copy
1
2
3
4
5
6
7
8
Actions actions = Actions(
  children: [
    TypedAction(
      type: const TypeToken<SelectAllAction>(),
      onInvoke: (context) => selectAll(context),
    ),
  ],
);

Create Shortcuts:

This defines a shortcut where Ctrl + A triggers the SelectAllAction.

Copy
1
2
3
4
5
6
7
Shortcuts(
  shortcuts: {
    LogicalKeySet(LogicalKeyboardKey.control, LogicalKeyboardKey.a):
        const TypeToken<SelectAllAction>(),
  },
  child: MyWidget(), // The widget the shortcuts apply to
);

Additional Considerations:

• Customization: You can customize the appearance of the shortcut description using the ShortcutLabel widget.
• Multiple Actions & Fallbacks: The Shortcuts widget can handle multiple Shortcut definitions, allowing different shortcuts to trigger the same action. Additionally, you can define a fallback action using the fallback property for situations where no matching Shortcut is found.
• Context & Focus: The Shortcuts widget uses the context and focus information to determine the appropriate action to invoke. This ensures shortcuts only work in relevant parts of your app.

Putting It All Together:

By combining Actions and Shortcuts, you can create intuitive keyboard shortcuts for various functionalities. Remember to consider your target platform's typical keyboard layouts and conventions when designing shortcuts.

Code Example

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

class MyApp extends StatelessWidget {
  // ... other parts of your app

  @override
  Widget build(BuildContext context) {
    return Actions(
      actions: {
        CopyAction: CallbackAction<CopyAction>(
          onInvoke: (intent) => Clipboard.setData(ClipboardData(text: 'Some text to copy')),
        ),
      },
      child: Shortcuts(
        shortcuts: {
          LogicalKeySet(LogicalKeyboardKey.control, LogicalKeyboardKey.c): const CopyAction(),
        },
        child: MaterialApp(
          // ... your Material app structure
          home: Scaffold(
            body: TextField(
              // ... your text field
            ),
          ),
        )
      ),
    );
  }
}

// Custom Action class 
class CopyAction extends Intent {
  const CopyAction();
}

Explanation

a. Import Necessary Packages:

• flutter/material.dart: Provides core Flutter widgets and framework.
• flutter/services.dart: Gives access to system-level services like the clipboard.

b. Define a Custom Action:

• CopyAction: Represents the intent to copy text. For simplicity, we only need to create a class that extends Intent.

c. Utilize CallbackAction:

• CallbackAction: A convenient way to define an action with a simple callback function.
• onInvoke: The callback executed when the shortcut is triggered. Here, it copies "Some text to copy" to the clipboard.

d. Wrap with Shortcuts Widget:

• Shortcuts: Defines the keyboard shortcuts and their associated actions.
• shortcuts: A map where keys are LogicalKeySets (combinations of keys) and values are Intent instances. Here, Ctrl+C is mapped to our CopyAction.

e. Connect to a Widget: The child of the Shortcuts widget is the part of your app where the shortcuts are active. We are applying it to a TextField within a MaterialApp so that the copy shortcut will work when the TextField has focus.

How does it work?

• When the user presses Ctrl + C while the TextField has focus, the Shortcuts widget detects the key combination.
• It finds a matching shortcut in the shortcuts map linking Ctrl + C to the CopyAction.
• The Actions widget recognizes the CopyAction and executes its associated callback function via the onInvoke handler.
• The provided text is copied to the clipboard.

Important Things to Consider

• Ensure that the widget where you want the shortcuts to be active is a descendant of both the Shortcuts and Actions widgets.
• You can define multiple shortcuts and actions within the Shortcuts and Action widgets.

Benefits of Using Keyboard Shortcuts:

• Increased Efficiency: Users can perform tasks faster and more efficiently with keyboard shortcuts compared to using menus or touch interactions.
• Improved Accessibility: Keyboard shortcuts can be especially valuable for users with accessibility needs who might rely on keyboard navigation.
• Enhanced User Experience: Providing shortcuts demonstrates attention to detail and creates a more polished and user-friendly app.

Conclusion:

The Shortcuts widget in Flutter empowers you to implement powerful and user-friendly keyboard shortcuts, enhancing your app's usability and user experience. By following the steps outlined above and considering the additional tips, you can effectively leverage this feature to create a more efficient and accessible app for your users.