KeyDetector

Low-level key handling inside a widget: sees each key that reaches its subtree and consumes only the ones it handles.

See also: KeyBindings for declared, labeled shortcuts.

Learn more: Key handling

Import: package:fleury/fleury.dart, or package:fleury/fleury_core.dart in browser code.

Usage

KeyDetector(
  onKey: (event) {
    if (event.code == KeyCode.arrowDown && cursor < rows.length - 1) {
      setState(() => cursor++);
      event.consume(); // handled inside the pane
    }
    // At the last row the arrow is not consumed, so it reaches the
    // ancestors' key bindings.
  },
  child: Focus(child: pane),
)

Details

Keys propagate unless consumed — the reverse of a key binding, which consumes the key it matches. A detector observes by default, so a key it forgets to consume does visible double duty while you test it, instead of silently starving an ancestor’s shortcut.

Prefer KeyBindings for app shortcuts. Bindings are data the framework can read: the hint bar, which-key, and devtools list them, and none of them can read a closure. Use a detector when the handling belongs inside a reusable control, such as a scroll region or a terminal pane that forwards raw keys.

A detector is active while focus is within its subtree and is matched deepest-first, like a binding scope. It is not a focus node: adding one never changes traversal, so wrap the focusable part in Focus yourself. It sees key presses and repeats, never releases.

Constructors

KeyDetector()

Parameter	Type	Default	Description
onKey:	void Function(KeyEvent event)	required	Called for each key event routed through this subtree. Consume with KeyEvent.consume; do nothing to let it continue.
child:	Widget	required	The subtree whose keys onKey sees. The detector only fires while this subtree holds focus — it is scoped, not ambient.

Source

KeyDetector is defined in packages/fleury/lib/src/widgets/keyboard.dart.

Category: Input handling & focus · All widgets

Live demo

key_detector.dart

Restart Run Expand

Example · editable Revert Format

class _KeyDetectorTourState extends State<_KeyDetectorTour> {
  static const _count = 3;
  int _cursor = 0;
  int _paneHandled = 0;
  int _appHandled = 0;
  String _lastKey = '—';
  String _paneResult = 'waiting';
  String _appResult = 'waiting';
  bool _lastBubbled = false;

  void _handleAtApp(String key) {
    setState(() {
      _lastKey = key;
      _paneResult = 'PASSED · at edge';
      _appResult = 'HANDLED';
      _appHandled++;
      _lastBubbled = true;
    });
  }

  void _handleInPane(KeyEvent event, String key, int nextCursor) {
    setState(() {
      _cursor = nextCursor;
      _lastKey = key;
      _paneResult = 'HANDLED · moved';
      _appResult = '— not reached';
      _paneHandled++;
      _lastBubbled = false;
    });
    event.consume();
  }

  @override
  Widget build(BuildContext context) {
    final theme = Theme.of(context);
    return KeyBindings(
      // The ancestor. It only ever hears an arrow the pane declined to
      // consume — i.e. one that fell off the pane's edge.
      bindings: [
        KeyBinding(
          KeyCode.arrowDown,
          label: 'App ↓',
          onTrigger: (_) => _handleAtApp('↓'),
        ),
        KeyBinding(
          KeyCode.arrowUp,
          label: 'App ↑',
          onTrigger: (_) => _handleAtApp('↑'),
        ),
      ],
      child: KeyDetector(
        onKey: (e) {
          if (e.code == KeyCode.arrowDown && _cursor < _count - 1) {
            _handleInPane(e, '↓', _cursor + 1);
          } else if (e.code == KeyCode.arrowUp && _cursor > 0) {
            _handleInPane(e, '↑', _cursor - 1);
          }
          // At an edge: do nothing → the arrow continues to the ancestor.
        },
        child: Focus(
          autofocus: true,
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.stretch,
            children: [
              const Padding(
                padding: EdgeInsets.symmetric(horizontal: 1),
                child: Text('CLICK · THEN ↓ ↓ ↓', style: CellStyle(bold: true)),
              ),
              const Padding(
                padding: EdgeInsets.symmetric(horizontal: 1),
                child: Text(
                  'first 2 move; #3 bubbles',
                  style: CellStyle(dim: true),
                ),
              ),
              const SizedBox(height: 1),
              Padding(
                padding: const EdgeInsets.symmetric(horizontal: 1),
                child: Text('last key  $_lastKey'),
              ),
              Padding(
                padding: const EdgeInsets.symmetric(horizontal: 1),
                child: Text(
                  'PANE  $_paneResult',
                  style: CellStyle(
                    bold: _paneResult != 'waiting',
                    foreground: _lastBubbled
                        ? theme.colorScheme.warning
                        : _paneResult == 'waiting'
                        ? null
                        : theme.colorScheme.primary,
                  ),
                ),
              ),
              Padding(
                padding: const EdgeInsets.symmetric(horizontal: 1),
                child: Text(
                  'APP   $_appResult',
                  style: CellStyle(
                    bold: _lastBubbled,
                    dim: !_lastBubbled,
                    foreground: _lastBubbled ? theme.colorScheme.warning : null,
                  ),
                ),
              ),
              Padding(
                padding: const EdgeInsets.symmetric(horizontal: 1),
                child: Text(
                  'pane $_paneHandled · app $_appHandled',
                  style: const CellStyle(dim: true),
                ),
              ),
              const Padding(
                padding: EdgeInsets.symmetric(horizontal: 1),
                child: Text('── inner pane ──'),
              ),
              for (var i = 0; i < _count; i++)
                Padding(
                  padding: const EdgeInsets.symmetric(horizontal: 1),
                  child: Text(
                    '${i == _cursor ? '▸' : ' '} line ${i + 1}',
                    style: i == _cursor
                        ? CellStyle(
                            foreground: theme.colorScheme.primary,
                            bold: true,
                          )
                        : const CellStyle(),
                  ),
                ),
            ],
          ),
        ),
      ),
    );
  }
}

Live preview

Live · interactive

click & type to interact ⓘ how this demo runs ⛶ Expand