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
Creates searchable list bindings: navigation + search toggle + conditional text input + prompt.
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.
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 (↑/↓).