TamboUI separates physical input (keys, mouse clicks) from semantic actions. Instead of checking for specific keys everywhere, you define bindings that map inputs to actions like "moveUp" or "delete".
Predefined Binding Sets
Several binding presets are available:
Bindings standard = BindingSets.standard(); // Arrow keys, Enter, Escape
Bindings vim = BindingSets.vim(); // hjkl navigation, Ctrl+u/d
Bindings emacs = BindingSets.emacs(); // Ctrl+n/p/f/b navigation
The named sets (standard(), vim(), emacs(), …) are literal and cross-platform, so they are predictable and testable. Only the effective default, BindingSets.defaults() (what a TuiConfig uses unless you pick a set), resolves the host platform: on macOS it replaces the word-editing actions with their Option (Alt) equivalents to match the system text layer, so Option+Left/Option+Right jump by word and Option+Backspace/Option+Delete delete a word. Ctrl+Left/Ctrl+Right is Mission Control on macOS, so it is deliberately not a word key there; Ctrl+w (a universal readline control byte) still deletes a word on every platform. Off macOS, defaults() is standard() unchanged, with word editing on Ctrl+Left/Ctrl+Right and Ctrl+Backspace/Ctrl+Delete (which need a terminal that reports them, e.g. via the Kitty keyboard protocol).
Matching Actions in Events
Events carry binding information. Use semantic checks instead of hardcoding keys:
// Semantic - works with any binding set
if (event.isUp()) { }
if (event.isSelect()) { }
if (event.matches("delete")) { }
// Low-level - when you need specific keys
if (event.isChar('x')) { }
if (event.isKey(KeyCode.F1)) { }
The is*() methods delegate to the current bindings.
With vim bindings, isUp() matches Up arrow, k, or Ctrl+p.
With standard bindings, it only matches the Up arrow.
Prefer Semantic Predicates
Reach for the semantic predicates on KeyEvent instead of comparing event.code() to a KeyCode.
// Prefer this:
if (event.isUp()) { ... }
if (event.isConfirm()) { ... }
if (event.isDeleteBackward()) { ... }
// Over this:
if (event.code() == KeyCode.UP) { ... }
if (event.code() == KeyCode.ENTER) { ... }
if (event.code() == KeyCode.BACKSPACE) { ... }
A raw event.code() == KeyCode.UP check has three problems the predicates avoid:
-
It matches any modifier combination (Ctrl+Up, Alt+Up), which is usually not what you want.
-
It ignores the bindings, so it never picks up keypad variants, vim keys (
k), emacs chords (Ctrl+p), or a user’s custom binding set. -
It does not filter release events; the predicates do (via
KeyTrigger), so a key is not acted on twice.
The available predicates, each matching its action in the current bindings:
isUp(), isDown(), isLeft(), isRight(), isPageUp(), isPageDown(), isHome(), isEnd(),
isSelect(), isConfirm(), isCancel(), isQuit(), isFocusNext(), isFocusPrevious(),
isDeleteBackward() and isDeleteForward().
For text fields, use isTyping() to decide whether to insert a character: it is true for a typed
character (including keypad digits, IME and emoji text, and AltGr combinations) and false for
shortcuts and control keys, so you never insert the letter of a Ctrl chord. The
dev.tamboui.tui.event.TextEditing helper applies all of this (typing, editing and paste) to a
TextInputState or TextAreaState for you.
|
Comparing |
For applications calling EventParser.readEvent(…) directly, a read timeout returns null, while terminal EOF throws the JDK’s EOFException (a subclass of IOException). Once a bracketed paste starts, its content is read until the end marker even across read timeouts; a partial paste is never emitted just because input pauses. EOF during a paste discards its content. If an end marker never arrives, input waits in paste mode until EOF or application shutdown rather than interpreting a late pasted Enter as a key. Paste content is buffered as a single string with no fixed size limit, so memory use grows with the paste until it completes. TuiRunner and InlineTuiRunner stop their input reader on EOF.
Key Triggers
KeyTrigger defines what input triggers an action:
KeyTrigger.key(KeyCode.UP); // Arrow key
KeyTrigger.ch('j'); // Character
KeyTrigger.chIgnoreCase('j'); // j or J
KeyTrigger.ctrl('u'); // Ctrl+U
KeyTrigger.alt('x'); // Alt+X
KeyTrigger.superKey('k'); // Super/Command+K
Keyboard Protocol and Terminal Compatibility
TamboUI enables the Kitty Keyboard Protocol (CSI u / progressive keyboard enhancement) by default, in AUTO mode.
On terminals that implement it (Kitty, Ghostty, foot, WezTerm, recent Alacritty, and tmux 3.x passthrough, among others) keys are reported unambiguously:
-
Ctrl+letter keeps its case - Ctrl+a and Ctrl+Shift+A are distinct.
-
Tab vs Ctrl+I, Enter vs Ctrl+M, and Escape vs Alt combinations are disambiguated.
-
Shortcuts match across keyboard layouts (Cyrillic, AZERTY, Dvorak, …) via base-layout key reporting.
For these terminals the historical control-key limitations below do not apply, and you can bind Ctrl+key combinations freely.
Protocol Modes
The mode is configured on TuiConfig or InlineTuiConfig via KeyboardProtocol (AUTO, FULL, or LEGACY).
See API Levels → Keyboard Protocol for the full mode/flags reference and how the protocol stack is pushed and popped.
Legacy Terminal Fallback
|
On terminals that do not implement the Kitty protocol - or when you explicitly select When you press a key combination like Ctrl+A, a legacy terminal does not send "Ctrl" + "A" separately. Instead, it sends a single ASCII control character (byte value 1 for Ctrl+A). This encoding dates back to the 1970s and causes several problems:
Alt key bindings are more reliable in legacy mode because terminals send ESC followed by the actual character:
|
If you need to support legacy terminals as well, choose custom bindings that degrade gracefully:
| Modifier | Legacy reliability | Notes |
|---|---|---|
|
Excellent |
Preserves case, works consistently |
|
Excellent |
Fully distinguishable |
|
Good |
Works but loses shift information in legacy mode |
|
Poor |
Avoid - ambiguous with other combinations in legacy mode |
With the Kitty protocol active (the default), all of these combinations are fully distinguishable.
For the widest reach, prefer Alt+key bindings for custom actions and reserve bare Ctrl+key for well-established conventions (Ctrl+C, Ctrl+S, Ctrl+Z, etc.).
Rich Event Model
With Kitty protocol support enabled, key events provide rich metadata:
-
Event Kinds:
KeyEventKind.PRESS,KeyEventKind.REPEAT, andKeyEventKind.RELEASE. Existing widgets andKeyTriggerbindings ignoreRELEASEevents by default to maintain full backward compatibility. You can match release events explicitly usingKeyTrigger.withKind(KeyEventKind.RELEASE). -
Extended Modifiers: In addition to Shift, Ctrl, and Alt,
KeyModifierssupportssuperKey(Command / Windows key),hyper, andmeta. Helpers such asevent.hasSuper(),KeyTrigger.superKey('k'), andKeyTrigger.withSuper()are provided. -
Special, Keypad, and Media Keys: First-class support for
F13–F35, numeric keypad keys (KP_0–KP_9,KP_ENTER,KP_ADD, etc. withevent.isKeypad()), lock keys (CAPS_LOCK,NUM_LOCK,SCROLL_LOCK), and media keys. -
Alternate Keys & Layout Independence: Terminals report
event.keyCodePoint(),event.shiftedKeyCodePoint(), andevent.baseLayoutKeyCodePoint()(standard PC-101 layout), allowing shortcuts to match regardless of international keyboard layouts (like Cyrillic, AZERTY, or Dvorak). -
Associated Text:
event.text()conveys the exact Unicode text generated by the key event (including combining characters and IME input).
Mouse Triggers
MouseTrigger.click(); // Left click
MouseTrigger.rightClick(); // Right click
MouseTrigger.ctrlClick(); // Ctrl+click
MouseTrigger.scrollUp(); // Scroll wheel
MouseTrigger.drag(MouseButton.LEFT); // Dragging
Custom Bindings
Start from a preset and customize:
Bindings custom = BindingSets.standard()
.toBuilder()
.bind(KeyTrigger.ch('d'), "delete")
.bind(KeyTrigger.key(KeyCode.DELETE), "delete")
.bind(KeyTrigger.ctrl('s'), "save")
.bind(MouseTrigger.rightClick(), "contextMenu")
.build();
ActionHandler
For centralized action handling, use ActionHandler:
ActionHandler actions = new ActionHandler(BindingSets.vim())
.on(Actions.QUIT, e -> runner.quit())
.on("save", e -> save())
.on("delete", e -> deleteSelected());
// In your event handler:
boolean handleEvent(Event event, TuiRunner runner) {
ActionHandler actions = new ActionHandler(BindingSets.vim());
if (actions.dispatch(event)) {
return true; // Action was handled
}
// Handle other events...
return false;
}
Handlers can optionally receive the action name that triggered them:
// Handler with action name (useful when same handler serves multiple actions)
ActionHandler actions = new ActionHandler(bindings)
.on("red", (event, action) -> setColor(action))
.on("blue", (event, action) -> setColor(action))
.on("green", (event, action) -> setColor(action));
@OnAction Annotation
The @OnAction annotation works with Toolkit Components.
For TuiRunner or immediate mode, use ActionHandler instead (see above).
|
In Toolkit components, annotate methods to handle actions:
public class EditorComponent extends Component<EditorComponent> {
private List<String> lines = new ArrayList<>();
private int cursor = 0;
@OnAction(Actions.MOVE_UP)
void moveCursorUp(Event event) {
if (cursor > 0) cursor--;
}
@OnAction(Actions.MOVE_DOWN)
void moveCursorDown(Event event) {
if (cursor < lines.size() - 1) cursor++;
}
@OnAction("delete")
void deleteLine(Event event) {
if (!lines.isEmpty()) {
lines.remove(cursor);
}
}
@Override
protected Element render() {
return text("Editor");
}
}
The component framework discovers these methods and dispatches events automatically.
A method can take Event or a subtype such as KeyEvent or MouseEvent; a method that takes a subtype is only called for events of that type.
Annotation Processing
By default, @OnAction methods are discovered at runtime using reflection.
For better startup performance and GraalVM native image compatibility, use the annotation processor to generate action handler registrations at compile time.
Gradle (Kotlin DSL)
dependencies {
implementation("dev.tamboui:tamboui-toolkit:0.8.0-SNAPSHOT")
annotationProcessor("dev.tamboui:tamboui-processor:0.8.0-SNAPSHOT")
}
Gradle (Groovy DSL)
dependencies {
implementation 'dev.tamboui:tamboui-toolkit:0.8.0-SNAPSHOT'
annotationProcessor 'dev.tamboui:tamboui-processor:0.8.0-SNAPSHOT'
}
Maven
<dependencies>
<dependency>
<groupId>dev.tamboui</groupId>
<artifactId>tamboui-toolkit</artifactId>
<version>0.8.0-SNAPSHOT</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.13.0</version>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>dev.tamboui</groupId>
<artifactId>tamboui-processor</artifactId>
<version>0.8.0-SNAPSHOT</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
</plugins>
</build>
The processor generates a _ActionHandlerRegistrar class for each component with @OnAction methods.
These registrars are discovered via ServiceLoader and register action handlers without reflection.
Loading Bindings from Files
Bindings can be externalized to properties files:
// From classpath
Bindings bindings = BindingSets.loadResource("/my-bindings.properties");
// From filesystem
Bindings bindingsFromFile = BindingSets.load(Paths.get("~/.config/myapp/bindings.properties"));
Property file format:
# Navigation
moveUp = Up, k
moveDown = Down, j
pageUp = PageUp, Ctrl+u
pageDown = PageDown, Ctrl+d
# Actions
select = Enter, Space
cancel = Escape
delete = d, Delete
# Mouse
click = Mouse.Left.Press
contextMenu = Mouse.Right.Press
Multiple triggers for the same action are comma-separated.
Modifiers use Ctrl+, Alt+, Shift+ prefixes.
Two independent rules govern how a set is assembled: how a file composes onto the one below it, and which files are loaded.
Per-action overwrite (how a file layers)
Every properties source is layered on top of a base (a built-in set, or the standard bindings for a user file), and layering is per action, replace — not additive:
-
An action the file lists gets exactly the triggers listed for it, replacing the base triggers of that action. So
quit = Ctrl+cmakes quitCtrl+conly, removing the standardqandQ. -
An action the file does not list keeps its base triggers unchanged.
An action can still have several triggers — list them comma-separated. Replace is per action, not
per key: quit = Ctrl+c, q, Q keeps all three, and moveUp = Up, k binds both. To keep a base key
and add one, name them together (quit = Ctrl+c, q), since a listed action no longer inherits its
base triggers.
This is why the named sets differ as they do: emacs.properties lists quit = Ctrl+c, so emacs quits
only on Ctrl+C, while a set that never mentions quit inherits the standard q, Q, Ctrl+c. The
same rule applies to your own files and to the OS overlays below — a listed action always replaces,
never adds.
Per-OS overlay (which files are loaded)
Orthogonally, BindingSets.defaults() also looks up an OS-specific overlay by the convention
<set>-<os>.properties, where <os> is macos, windows or linux, and layers it on top of the
set (using the same per-action replace rule) when the file exists:
-
On macOS,
standard-macos.propertiesmakes word navigation use Option (Alt), replacing the Ctrl word keys that the system reserves. -
On an OS with no matching overlay file, the set is used as-is.
The two rules are independent: the per-action overwrite decides how any one file merges; the per-OS
lookup decides whether an extra, platform-specific file is merged at all. The named accessors
(standard(), vim(), …) stay literal and cross-platform; only defaults() resolves the host OS.
Standard Actions
The Actions class defines common action names:
| Action | Description |
|---|---|
|
Navigation |
|
Page navigation |
|
Selection and confirmation |
|
Focus navigation (Tab/Shift+Tab) |
|
Text editing |
|
Word-wise cursor movement ( |
|
Word-wise deletion ( |
|
Application exit |
Next Steps
-
API Levels - choosing between immediate mode, TuiRunner, and Toolkit
-
Application Structure - patterns for larger applications