Interactive Interface Management

Interactive interface state management.

This module provides state management and business logic for interactive terminal interfaces.

class simulchip.interactive.KeyAction

Bases: Enum

Standard key actions for interactive interfaces.

UP = 'up'

DOWN = 'down'

PAGE_UP = 'page_up'

PAGE_DOWN = 'page_down'

TOP = 'top'

BOTTOM = 'bottom'

SELECT = 'select'

TOGGLE = 'toggle'

INCREMENT = 'increment'

DECREMENT = 'decrement'

SET_VALUE = 'set_value'

RESET = 'reset'

FILTER_ADD_CHAR = 'filter_add_char'

FILTER_BACKSPACE = 'filter_backspace'

FILTER_CLEAR = 'filter_clear'

SAVE_AND_EXIT = 'save_and_exit'

CANCEL = 'cancel'

TOGGLE_MODE = 'toggle_mode'

HELP = 'help'

UNKNOWN = 'unknown'

class simulchip.interactive.InteractiveState

Bases: object

State for interactive interfaces.

selected_index: int = 0

filter_text: str = ''

mode_flags: Optional[Dict[str, bool]] = None

viewport_start: int = 0

viewport_end: int = 0

total_items: int = 0

__post_init__()

Initialize mode flags if not provided.

Return type:

None

reset_selection()

Reset selection to beginning.

Return type:

None

update_viewport(start, end)

Update viewport boundaries.

Return type:

None

Parameters:

• start (int)

• end (int)

set_filter(text, reset_selection=True)

Set filter text and optionally reset selection.

Return type:

None

Parameters:

• text (str)

• reset_selection (bool)

toggle_mode(mode_name)

Toggle a mode flag and return new state.

Return type:

bool

Parameters:

mode_name (str)

__init__(selected_index=0, filter_text='', mode_flags=None, viewport_start=0, viewport_end=0, total_items=0)

Parameters:

• selected_index (int)

• filter_text (str)

• mode_flags (Dict[str, bool] | None)

• viewport_start (int)

• viewport_end (int)

• total_items (int)

Return type:

None

class simulchip.interactive.KeyMapper

Bases: object

Maps keyboard input to actions.

ESCAPE_SEQUENCES = {'\x1b[5~': KeyAction.PAGE_UP, '\x1b[6~': KeyAction.PAGE_DOWN, '\x1b[A': KeyAction.UP, '\x1b[B': KeyAction.DOWN, '\x1b[C': KeyAction.INCREMENT, '\x1b[D': KeyAction.DECREMENT}

SINGLE_CHARS = {'\x03': KeyAction.SAVE_AND_EXIT, '\x04': KeyAction.PAGE_DOWN, '\x08': KeyAction.FILTER_BACKSPACE, '\n': KeyAction.SELECT, '\r': KeyAction.SELECT, '\x15': KeyAction.PAGE_UP, '\x1b': KeyAction.SAVE_AND_EXIT, ' ': KeyAction.TOGGLE, '0': KeyAction.RESET, '1': KeyAction.SET_VALUE, '2': KeyAction.SET_VALUE, '3': KeyAction.SET_VALUE, '4': KeyAction.SET_VALUE, '5': KeyAction.SET_VALUE, '6': KeyAction.SET_VALUE, '7': KeyAction.SET_VALUE, '8': KeyAction.SET_VALUE, '9': KeyAction.SET_VALUE, '?': KeyAction.HELP, 'E': KeyAction.TOGGLE_MODE, 'G': KeyAction.BOTTOM, 'e': KeyAction.TOGGLE_MODE, 'g': KeyAction.TOP, 'h': KeyAction.HELP, 'j': KeyAction.UP, 'k': KeyAction.DOWN, 'q': KeyAction.SAVE_AND_EXIT, '\x7f': KeyAction.FILTER_BACKSPACE}

__init__(custom_mappings=None)

Initialize with optional custom key mappings.

Parameters:

custom_mappings (Dict[str, KeyAction] | None)

map_key(key)

Map a key to an action and optional value.

Parameters:

key (str) – The key character(s) to map

Return type:

Tuple[KeyAction, Optional[str]]

Returns:

Tuple of (action, value) where value is used for SET_VALUE actions

simulchip.interactive.process_navigation_action(state, action, total_items, page_size=10)

Process navigation actions and update state.

Parameters:

• state (InteractiveState) – Current interactive state

• action (KeyAction) – Navigation action to process

• total_items (int) – Total number of items

• page_size (int) – Number of items per page

Return type:

bool

Returns:

True if state was modified

simulchip.interactive.process_filter_action(state, action, value=None, reset_selection_on_change=True)

Process filter actions and update state.

Parameters:

• state (InteractiveState) – Current interactive state

• action (KeyAction) – Filter action to process

• value (Optional[str]) – Value for FILTER_ADD_CHAR actions

• reset_selection_on_change (bool) – Whether to reset selection when filter changes

Return type:

bool

Returns:

True if state was modified

class simulchip.interactive.InteractiveController

Bases: object

Controller for interactive interfaces.

__init__(key_mapper=None, page_size=10, reset_selection_on_filter_change=True)

Initialize controller with configuration.

Parameters:

• key_mapper (KeyMapper | None)

• page_size (int)

• reset_selection_on_filter_change (bool)

process_key(key, total_items, custom_handlers=None)

Process a key press and update state.

Parameters:

• key (str) – The key that was pressed

• total_items (int) – Total number of items in the interface

• custom_handlers (Optional[Dict[KeyAction, Callable]]) – Optional custom action handlers

Return type:

Tuple[KeyAction, bool]

Returns:

Tuple of (action, state_changed)