Keyboard shortcuts and taps
An action's keys are configuration, its handler is a bean method. You write search.open: primary+k in application.yml and mark a method @Shortcut('search.open'). primary is ⌘ on Apple's platforms and Ctrl elsewhere, so one line serves every platform. An action can also be bound to a pattern of taps on the screen, such as four quick taps and a fifth held three seconds, on phones as on desktops.
Why
Keys written in widget code are fixed per build and hard to find. In the configuration they change per platform or per profile without touching code (application-macos.yml), a screen can still take over an action while it is shown, and a label shows the keys the platform's way from the same place.
Example
# lib/resources/application.yml
spring:
flutter:
shortcuts:
search.open: [primary+k, slash] # ⌘K or / on macOS, Ctrl+K or / elsewhere
navigation.back: [alt+left, primary+bracket-left]
help.show: char:? # the character, whatever keys type it
debug.open: [primary+shift+d, taps:5+hold:2s]
@Component()
class SearchActions {
// keys: used when the configuration names none for this action.
@Shortcut('search.open', keys: ['primary+k'])
void open(BuildContext context) => SearchDialog.show(context);
}
// Shows "⌘K" on a Mac and "Ctrl+K" elsewhere, from the same configuration.
const ShortcutLabel('search.open')
Writing keys
| Form | Meaning |
|---|---|
primary+shift+k |
Modifiers and one key, joined by + |
char:? |
The character typed, on any keyboard layout |
taps:4+hold:3s |
Taps on the screen, not keys (below) |
| a list | Any of them: [primary+k, slash, taps:3] |
Modifiers: primary (⌘ on Apple's platforms, Ctrl elsewhere), shift, alt (or option), control (or ctrl), meta (or cmd).
Keys: letters, digits, f1 to f12, enter, escape, space, tab, backspace, delete, home, end, page-up, page-down, up, down, left, right, slash, backslash, comma, period, semicolon, quote, minus, equal, bracket-left, bracket-right, backquote.
A value no notation reads stops the start, naming the property (spring.flutter.shortcuts.search.open: 'moon' is no key ...). The same keys given to two actions log a warning.
Tap patterns
taps:<n> is quick taps anywhere on the screen, from 1 to 10. With +hold:<time> (ms or s), the last press is held that long; without it, the last tap is the shortcut (taps:3). It works on every platform, with a finger, a pen or a mouse.
- It only listens: every touch still reaches the app.
- A tap lasts at most 300 ms, and two taps are at most 400 ms apart.
- A finger that moves more than 18 points is a scroll, and the pattern starts again.
Use it for hidden actions on a phone that has no keyboard, such as the debug panel (taps:4+hold:3s by default).
Handlers
An action's handlers are asked in order, lower first (@Shortcut(order:), or Ordered), until one handles the press.
A @Shortcut method on a bean takes nothing, a BuildContext (the focused widget's, below the navigator, so it can show a dialog) or a ShortcutInvocation (the action and the context). It returns nothing (handled) or a bool: false passes the press on. Another signature stops the start.
@Component()
class EditorActions {
EditorActions(this.drafts);
final Drafts drafts;
// Saves only when there is something to save; otherwise the press goes on.
@Shortcut('editor.save', keys: ['primary+s'], order: 10)
bool save() {
if (!drafts.hasChanges) return false;
drafts.save();
return true;
}
}
A ShortcutHandler bean handles its action; with Ordered it takes its place among the others. A KeyedShortcutHandler also names its action's default keys, as @Shortcut(keys:) does:
@Component()
class HelpHandler implements KeyedShortcutHandler {
@override
String get action => 'help.show';
@override
List<String> get keys => const ['f1', 'char:?'];
@override
bool handle(ShortcutInvocation invocation) {
final context = invocation.context;
if (context == null) return false;
HelpSheet.show(context);
return true;
}
}
A screen's own handlers sit in the widget tree and are asked first while the focus is below them. An action they do not have, or a handler that returns false, goes on to the handlers above and then to the beans:
ShortcutHandlers(
handlers: {
'editor.save': (_) => draft.save(),
'search.open': (_) => searchInThisBook(), // instead of the app's search
},
child: EditorPage(draft),
)
Plain keys (slash, char:?) are ignored while a text field has the focus, so they still type. Keys with Ctrl, ⌘ or Alt work there too.
Showing the keys
ShortcutLabel('search.open') writes the action's first keys the platform's way (⌘K, Ctrl+K), from the same configuration. ShortcutLabel.of(context, action) gives the text, for a tooltip or a menu.
Where they are installed
The starter installs the shortcuts around the app's navigator (KeyboardShortcutsScope, through a FlutterAppCustomizer), so the handlers get a context below the navigator. An app with its own MaterialApp puts the scope in its builder:
MaterialApp(
builder: (context, child) => KeyboardShortcutsScope(
shortcuts: context.bean<KeyboardShortcuts>(),
child: child!,
),
home: const BookListPage(),
)
Notations of your own
To read keys written another way (numpad:5, a chord), declare a ShortcutNotation bean. The notations form a chain of responsibility: the app's own are asked first (by @Order), then CharacterNotation, TouchPatternNotation and KeyCombinationNotation.
@Component()
class NumpadNotation implements ShortcutNotation {
@override
bool supports(String text) => text.startsWith('numpad:');
@override
ShortcutKeys parse(String text, TargetPlatform platform) => ...;
}
The property
| Key | Type | Default | Meaning |
|---|---|---|---|
spring.flutter.shortcuts.<action> |
a key, a tap pattern, or a list of them | none; the @Shortcut(keys:) or KeyedShortcutHandler.keys of the action |
The keys or taps that run the action's handlers. The action name is the rest of the key (spring.flutter.shortcuts.search.open) |
Actions the starter knows: debug.open (primary+shift+d, taps:4+hold:3s), which opens the debug panel.
In Spring (Java)
Spring has no UI, so there is no counterpart. The model is the one of Spring's handler mappings: a name in the configuration, a bean method that handles it, an order among several.