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 event.code() directly - or the equivalent event.isKey(KeyCode.UP) - is only right when you specifically want the physical key regardless of the bindings, which is rare. An example is moving a floating panel with the arrow keys (spatial movement, where Shift+Arrow is meaningful and hjkl should not apply); there, event.isKey(KeyCode.UP) is the honest choice.

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 KeyboardProtocol.LEGACY - input falls back to classic VT encoding, which has significant limitations.

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:

  • Ctrl+letter (a-z): Works, but case information is lost. Ctrl+a and Ctrl+Shift+A send the same byte.

  • Ctrl+number: Unreliable. Ctrl+2, Ctrl+@, and Ctrl+Space all send the same byte (0). The original key cannot be determined.

  • Ctrl+Alt+key: Inconsistent across terminals.

Alt key bindings are more reliable in legacy mode because terminals send ESC followed by the actual character:

  • Alt+a sends ESC + 'a' - we know it was lowercase 'a'

  • Alt+A sends ESC + 'A' - we know it was uppercase 'A' (shifted)

  • Alt+2 sends ESC + '2' - we know it was '2'

If you need to support legacy terminals as well, choose custom bindings that degrade gracefully:

Modifier Legacy reliability Notes

Alt+letter

Excellent

Preserves case, works consistently

Alt+number

Excellent

Fully distinguishable

Ctrl+letter

Good

Works but loses shift information in legacy mode

Ctrl+number

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, and KeyEventKind.RELEASE. Existing widgets and KeyTrigger bindings ignore RELEASE events by default to maintain full backward compatibility. You can match release events explicitly using KeyTrigger.withKind(KeyEventKind.RELEASE).

  • Extended Modifiers: In addition to Shift, Ctrl, and Alt, KeyModifiers supports superKey (Command / Windows key), hyper, and meta. Helpers such as event.hasSuper(), KeyTrigger.superKey('k'), and KeyTrigger.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. with event.isKeypad()), lock keys (CAPS_LOCK, NUM_LOCK, SCROLL_LOCK), and media keys.

  • Alternate Keys & Layout Independence: Terminals report event.keyCodePoint(), event.shiftedKeyCodePoint(), and event.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+c makes quit Ctrl+c only, removing the standard q and Q.

  • 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.properties makes 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

MOVE_UP, MOVE_DOWN, MOVE_LEFT, MOVE_RIGHT

Navigation

PAGE_UP, PAGE_DOWN, HOME, END

Page navigation

SELECT, CONFIRM, CANCEL

Selection and confirmation

FOCUS_NEXT, FOCUS_PREVIOUS

Focus navigation (Tab/Shift+Tab)

DELETE_BACKWARD, DELETE_FORWARD

Text editing

MOVE_WORD_LEFT, MOVE_WORD_RIGHT

Word-wise cursor movement (Ctrl+Arrow, or Option+Arrow on macOS)

DELETE_WORD_BACKWARD, DELETE_WORD_FORWARD

Word-wise deletion (Ctrl+Backspace/Ctrl+Delete, or Option+Backspace/Option+Delete on macOS; Ctrl+w everywhere)

QUIT

Application exit

Next Steps