
# 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

```yaml
# 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]
```

```dart
@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);
}
```

```dart
// 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](debug-panel.md) (`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.

```dart
@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:

```dart
@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:

```dart
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`:

```dart
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`.

```dart
@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](debug-panel.md).

## 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.

## See also

- [The debug panel](debug-panel.md)
- [The app widget](app-widget.md)
- [All properties](properties.md)
