Input API

The tuix.core.input module controls the native listener and exposes consuming, non-consuming snapshots, and synthetic key injection. Built-in widgets receive input automatically through core.main_loop().

Method	How to use it	Why it exists
input.tuix_input_start() -> None	Starts background native listener thread.	Captures raw terminal keyboard and mouse events into thread-safe ring buffer.
input.tuix_input_stop() -> None	Stops background native listener thread.	Terminates input listener during application teardown.
input.tuix_input_get_snapshot() -> InputSnapshot	Consumes and returns next input snapshot from the queue.	Advances input queue during frame loop.
input.tuix_input_peek_snapshot() -> InputSnapshot	Inspects latest input snapshot without consuming queued events.	Diagnostic and predictive input checking.
input.tuix_input_inject_key(key: int, ctrl: int = 0, alt: int = 0, shift: int = 0, event_type: int = 1, payload_utf8: bytes = b'') -> None	Injects synthetic keyboard event into native input queue.	Programmatic automation, keybinding dispatch, and unit testing.

Snapshot Shape

InputSnapshot: term_x, term_y, keyboard, mouse, consumed_keyboard, consumed_mouse.
KeyboardKey: btn, code, scancode, modifiers, pressed, repeat, has_event, payload_utf8 (128-byte UTF-8 payload for grapheme clusters and text input).
MouseKey: event, btn, buttons_held, col, row, has_event.

Usage Pattern

input.listen()
try:
    while running:
        core.main_loop()
        latest = input.peek_snapshot()  # optional diagnostics
finally:
    input.stop()