Input Handling

TUIX captures keyboard and mouse events on a native listener thread and exposes them as snapshots. The frame loop routes snapshots to the focused, captured, modal, or hitmap-picked widget.

Starting And Stopping

from tuix.core import input, core

# Start native background input listener thread
input.tuix_input_start()

# Run the main loop
while running:
    core.tuix_core_loop_run()

# Stop listener thread on exit
input.tuix_input_stop()

Snapshots

Function	Behavior
input.tuix_input_get_snapshot()	Returns and consumes the next snapshot from the queue.
input.tuix_input_peek_snapshot()	Returns the latest snapshot without consuming queued events.
input.tuix_input_inject_key(key, ctrl=0, alt=0, shift=0, event_type=1, payload_utf8=b'')	Injects a synthetic key event directly into the native input queue.

Snapshot Shape

InputSnapshot exposes term_x, term_y, keyboard, mouse, consumed_keyboard, and consumed_mouse.
Keyboard events expose fields such as btn, code, scancode, modifiers, pressed, repeat, has_event, and payload_utf8 (128-byte UTF-8 string buffer for grapheme clusters and IME text).
Mouse events expose event, btn, buttons_held, col, row, and has_event.

Routing Order

v0.6 routing accounts for modal state, mouse capture, viewport ownership, hitmap picking, focus, and generic mouse handling. This matters for drag-heavy widgets and scrollable containers, where the visible content target can differ from the original buffer position.

Mouse Capture

from tuix.core import core

# Start mouse capture for drag operations
core.tuix_mouse_capture_start(uid)
active_uid = core.tuix_mouse_capture_get_uid()

# Release mouse capture when drag finishes
core.tuix_mouse_capture_stop(uid)