wijjit.terminal.input.InputHandler

class wijjit.terminal.input.InputHandler(enable_mouse=False, mouse_tracking_mode=None, input=None, output=None)

Handles reading and parsing keyboard and mouse input using prompt_toolkit.

This provides cross-platform keyboard input handling with support for special keys, escape sequences, modifiers, and ANSI mouse events.

Parameters:

• enable_mouse (bool, optional) – Whether to enable mouse event tracking (default: False)

• mouse_tracking_mode (MouseTrackingMode, optional) – Mouse tracking mode to use if enabled (default: BUTTON_EVENT)

• input (Any | None)

• output (TextIO | None)

Variables:

• _input (prompt_toolkit.input.Input) – The prompt_toolkit input object

• mouse_enabled (bool) – Whether mouse tracking is currently enabled

• mouse_parser (MouseEventParser or None) – Parser for ANSI mouse event sequences

__init__(enable_mouse=False, mouse_tracking_mode=None, input=None, output=None)

Parameters:

• enable_mouse (bool)

• mouse_tracking_mode (MouseTrackingMode | None)

• input (Any | None)

• output (TextIO | None)

Return type:

None

Methods

__init__([enable_mouse, ...])
cleanup()	Clean up input handler state.
close()	Close the input handler and clean up all resources.
disable_mouse_tracking()	Disable mouse event tracking.
enable_mouse_tracking([mode])	Enable mouse event tracking.
read_input([timeout])	Read a single input event (keyboard or mouse).
read_input_async([timeout])	Read a single input event asynchronously (keyboard or mouse).
read_key()	Read a single key press.
restore_terminal()	Restore terminal output/mode state without stopping the reader thread.

read_input(timeout=None)

Read a single input event (keyboard or mouse).

This method blocks until an input event occurs (or timeout expires) and returns either a Key object (for keyboard input) or a MouseEvent object (for mouse input).

Parameters:

timeout (float or None, optional) – Maximum time to wait for input in seconds. If None, blocks indefinitely. If timeout expires with no input, returns None. Default is None.

Returns:

Input event, or None on timeout/error

Return type:

Key, MouseEvent, or None

Notes

Timeout support is critical for enabling animations (spinners) and time-based UI updates (notification expiry) without requiring user input.

This implementation uses a persistent reader thread with a queue to avoid spawning new threads for every timeout-based read, preventing thread leaks.

async read_input_async(timeout=None)

Read a single input event asynchronously (keyboard or mouse).

This method uses asyncio to handle input reading without blocking the event loop, making it suitable for async applications.

Parameters:

timeout (float or None, optional) – Maximum time to wait for input in seconds. If None, blocks indefinitely. If timeout expires with no input, returns None. Default is None.

Returns:

Input event, or None on timeout/error

Return type:

Key, MouseEvent, or None

Notes

This async version properly integrates with asyncio event loops, allowing other async tasks to run while waiting for input.

This implementation uses a persistent reader thread with a queue to avoid spawning new executor tasks for every timeout-based read, preventing task leaks.

close()

Close the input handler and clean up all resources.

This method should be called when the InputHandler is no longer needed to ensure proper cleanup of background threads, mouse tracking, raw mode, and input resources.

Return type:

None

restore_terminal()

Restore terminal output/mode state without stopping the reader thread.

Disables mouse tracking and exits raw mode - the two terminal-affecting pieces of close() - but does not join the reader thread or close the underlying input. That makes it safe to call from a signal handler or atexit net, where joining a thread (or otherwise blocking) could deadlock. Idempotent: mouse tracking and raw mode are each only touched when currently active.

Order matches suspend/teardown elsewhere: disable mouse before exiting raw mode, so the terminal is not briefly left in raw mode with mouse reporting still on.

Return type:

None

__del__()

Cleanup when InputHandler is garbage collected.

Return type:

None

read_key()

Read a single key press.

This method blocks until a key is pressed and returns a Key object representing the pressed key. Mouse events are ignored.

Returns:

Key object representing the key press, or None on error

Return type:

Key or None

enable_mouse_tracking(mode=None)

Enable mouse event tracking.

Sends ANSI escape sequences to enable mouse tracking in the terminal.

Parameters:

mode (MouseTrackingMode, optional) – Tracking mode to use (default: uses mode from constructor)

Return type:

None

disable_mouse_tracking()

Disable mouse event tracking.

Sends ANSI escape sequences to disable mouse tracking in the terminal.

Return type:

None

cleanup()

Clean up input handler state.

This ensures resources are properly released.

Return type:

None