KeyBindings class

A composable collection of key bindings.

KeyBindings can be:

  • Combined using + operator or merge()
  • Extended with additional bindings
  • Used to generate hints automatically
  • Treated as immutable value objects (safe to reuse across renders)

Example:

final bindings = KeyBindings.cancel() +
    KeyBindings.confirm() +
    KeyBindings.verticalNavigation(onUp: moveUp, onDown: moveDown);
Available extensions

Constructors

KeyBindings(List<KeyBinding> _bindings)
Creates an immutable binding collection. Prefer using the provided factories (KeyBindings.prompt(), etc.) instead of building the list manually.
const
KeyBindings.empty()
Creates an empty KeyBindings collection.
const
KeyBindings.from(List<KeyBinding> bindings)
Creates KeyBindings from a list of bindings.
factory

Properties

bindings → List<KeyBinding>
All bindings in this collection.
no setter
hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

add(KeyBinding binding) → KeyBindings
Adds a single binding to this collection. Returns a new collection with binding appended to the end.
addAll(List<KeyBinding> bindings) → KeyBindings
Adds multiple bindings to this collection. Returns a new collection with every binding in bindings appended.
handle(KeyEvent event) → KeyActionResult
Processes a key event through all bindings.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toHintEntries() → List<List<String>>
Generates hint entries from all bindings that have hints defined.
toHintsBullets(PromptTheme theme) → String

Available on KeyBindings, provided by the HintKeybindingsExtensions extension

Generates a hints bullets string for display.
toHintsGrid(PromptTheme theme) → String

Available on KeyBindings, provided by the HintKeybindingsExtensions extension

Generates a hints grid string for display.
toString() → String
A string representation of this object.
inherited
waitForKey() → void
Waits for any matching key event using KeyEventReader.
waitForKeyWithResult() → KeyActionResult
Waits for a key and returns whichever KeyActionResult resolves first.
writeHints(RenderOutput out, PromptTheme theme, {int? bulletsPerLine}) → void

Available on KeyBindings, provided by the HintKeybindingsExtensions extension

Writes hints directly to a RenderOutput, handling all hint styles.

Operators

operator +(KeyBindings other) → KeyBindings
Combines this with another KeyBindings collection. Bindings from other are added after this collection's bindings.
operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

anyKeyToContinue({void onContinue()?, String hintLabel = 'any key', String hintDescription = 'continue'}) → KeyBindings
Creates bindings for "press any key to continue" scenarios.
back({void onBack()?, String hintLabel = '← / Esc / Enter', String hintDescription = 'back'}) → KeyBindings
Creates "back" bindings (Left arrow, Esc, Enter) for viewer scenarios.
cancel({void onCancel()?, String hintLabel = 'Esc', String hintDescription = 'cancel'}) → KeyBindings
Creates cancel bindings (Esc and Ctrl+C).
conditionalTextInput({required TextInputBuffer buffer, required bool isEnabled(), void onInput()?}) → KeyBindings
Creates conditional text input bindings (only active when condition is true).
conditionalToggle({required bool isEnabled(), required void onToggle(), String hintLabel = 'Space', String hintDescription = 'select'}) → KeyBindings
Creates conditional toggle binding (Space only when isEnabled is true).
confirm({KeyActionResult onConfirm()?, String hintLabel = 'Enter', String hintDescription = 'confirm'}) → KeyBindings
Creates confirm binding (Enter).
continuePrompt({void onContinue()?, String hintLabel = 'Enter', String hintDescription = 'continue'}) → KeyBindings
Creates bindings that exit on common "continue" keys (Enter, Esc, Space).
ctrlD({KeyActionResult onPress()?, String hintLabel = 'Ctrl+D', String? hintDescription}) → KeyBindings
Creates Ctrl+D binding.
ctrlR({required void onPress(), String hintLabel = 'Ctrl+R', String hintDescription = 'reveal'}) → KeyBindings
Creates Ctrl+R binding (commonly used for reveal/toggle modes).
directionalNavigation({void onUp()?, void onDown()?, void onLeft()?, void onRight()?, String hintLabel = '↑/↓/←/→', String hintDescription = 'navigate'}) → KeyBindings
Creates all-direction navigation bindings (↑/↓/←/→).
exitOn({required Set<KeyEventType> keys, void onExit()?, String? hintLabel, String? hintDescription}) → KeyBindings
Creates bindings that exit on any of the specified keys.
gridNavigation({required void onUp(), required void onDown(), required void onLeft(), required void onRight(), String hintLabel = '↑/↓/←/→', String hintDescription = 'navigate'}) → KeyBindings
Creates 2D grid navigation bindings with custom move functions.
gridSelection({required void onUp(), required void onDown(), required void onLeft(), required void onRight(), void onToggle()?, bool showToggleHint = false, KeyActionResult onConfirm()?, void onCancel()?}) → KeyBindings
Creates 2D grid selection bindings (navigation + optional toggle + confirm + cancel).
horizontalNavigation({required void onLeft(), required void onRight(), String hintLabel = '←/→', String hintDescription = 'adjust'}) → KeyBindings
Creates horizontal navigation bindings (←/→).
letter({required String char, required void onPress(), String? hintLabel, String? hintDescription}) → KeyBindings
Creates letter key binding for a specific character (case-insensitive).
list({required void onUp(), required void onDown(), KeyActionResult onConfirm()?, void onCancel()?}) → KeyBindings
Standard list bindings: navigation + confirm + cancel.
merge(List<KeyBindings> collections) → KeyBindings
Merges multiple KeyBindings collections.
numbers({required void onNumber(int number), int max = 9, bool includeZero = false, String? hintLabel, String? hintDescription}) → KeyBindings
Creates number key bindings (default 1-9, optionally 0).
prompt({KeyActionResult onConfirm()?, void onCancel()?}) → KeyBindings
Standard prompt bindings: confirm (Enter) + cancel (Esc/Ctrl+C).
rowToggle({required void onToggle(), String hintLabel = '←/→ / Space', String hintDescription = 'toggle'}) → KeyBindings
Creates row toggle binding (←/→ or Space to toggle current row).
searchableList({required void onUp(), required void onDown(), required void onSearchToggle(), required TextInputBuffer searchBuffer, required bool isSearchEnabled(), void onSearchInput()?, void onToggle()?, bool hasMultiSelect = false, KeyActionResult onConfirm()?, void onCancel()?}) → KeyBindings
Search/list focus bindings. isSearchEnabled reports text focus; onSearchToggle switches focus without clearing the query or filter. Slash focuses search from results; Ctrl+F switches either direction. onSearchInput runs only when query text changes.
searchToggle({required void onToggle(), String hintLabel = '/', String hintDescription = 'search'}) → KeyBindings
Creates search toggle binding (/).
selection({required void onUp(), required void onDown(), required void onToggle(), KeyActionResult onConfirm()?, void onCancel()?}) → KeyBindings
Standard selection bindings: navigation + toggle + confirm + cancel.
slider({required void onLeft(), required void onRight(), KeyActionResult onConfirm()?, void onCancel()?}) → KeyBindings
Standard slider bindings: horizontal navigation + confirm + cancel.
tab({required void onTab(), String hintLabel = 'Tab', String hintDescription = 'switch'}) → KeyBindings
Creates tab binding.
tabSwitch({required void onTab(), String hintLabel = 'Tab', String hintDescription = 'switch'}) → KeyBindings
Creates Tab binding for switching between items/modes.
textInput({required TextInputBuffer buffer(), bool isEnabled()?, void onInput()?, void onTextChanged()?}) → KeyBindings
Text editing bindings for a fixed or dynamically focused buffer. Recognized editing keys are consumed even when nothing changes (for example, backspace at the start or typing at maxLength). onInput runs only when text or cursor state changes; onTextChanged runs only for text changes. Disabled bindings ignore events.
toggle({required void onToggle(), String hintLabel = 'Space', String hintDescription = 'toggle'}) → KeyBindings
Creates toggle binding (Space).
toggleGroup({required void onUp(), required void onDown(), required void onToggle(), required void onToggleAll(), KeyActionResult onConfirm()?, void onCancel()?}) → KeyBindings
Creates toggle group bindings: vertical nav + row toggle + 'A' for all + prompt.
togglePrompt({required void onToggle(), KeyActionResult onConfirm()?, void onCancel()?, String toggleHint = 'toggle'}) → KeyBindings
Standard toggle bindings: arrows toggle + space toggle + confirm + cancel.
verticalNavigation({required void onUp(), required void onDown(), String hintLabel = '↑/↓', String hintDescription = 'navigate'}) → KeyBindings
Creates vertical navigation bindings (↑/↓).