Internal API

Styles Internals

_precompute_styles()

Computes and returns the fully resolved style dictionary by applying the active preset and then overlaying any non-None custom_styles values. Returns a deep copy of the result.

# Called internally — returns merged styles dict
resolved = engine.styles._precompute_styles()

_cache_styles()

Calls _precompute_styles() and stores the result in engine.styles.cached_styles. Called automatically after every set_custom_style(), remove_custom_style(), or style change.

RenderEngine Internals

_wrap_and_center(text, max_width)

Wraps text to fit within max_width characters and centers the block horizontally. Handles explicit newlines. Returns a list of padded strings, each exactly max_width characters wide.

_draw_choice(obj, text)

Draws a complete choice component: top border, label text area, button area, bottom border. The text parameter is the pre-wrapped label lines. After rendering, calls engine.input.listen(choices) to start the input loop.

_draw_buttons(*, obj, choices, max_width, max_height)

Renders the interactive button area inside a choice component box. Buttons are centered horizontally, multiple buttons per row separated by 4 spaces. The selected button is highlighted with ANSI color codes from cached styles. Long button names are split using visual_width().

_handle_selection_change(key, choices)

Updates selected_row and selected_index based on the key direction ('up', 'down', 'left', 'right'). Clamps values within valid ranges. Calls _refresh() to redraw.

_refresh(*, selected_row, selected_index)

Updates the RenderEngine's selection state and triggers a full redraw by clearing the screen and calling draw().

LayoutEngine Internals

_compute_all()

Reads terminal dimensions via shutil.get_terminal_size() and computes x, y, margin_top, margin_left, and corner coordinates for every component in the objects dictionary. Called automatically by RenderEngine.draw().

For each component, the computed layout includes:

• x: int(width_modifier * terminal_cols)
• y: int(height_modifier * terminal_rows)
• margin_top: custom → int(modifier * rows), centered → (rows - y) // 2
• margin_left: custom → int(modifier * cols), centered → (cols - x) // 2
• corners.top_left: (margin_left, margin_top)
• corners.bottom_right: (margin_left + x, margin_top + y)

InputHandler Internals

get_key()

Low-level platform-specific key detection. On Windows, uses msvcrt.getch() with two-byte arrow key sequences (0xE0 prefix). On Unix, sets terminal to raw mode via termios, reads with select() timeout of 0.1s, then restores terminal settings.