wijjit.elements.menu.MenuElement

class wijjit.elements.menu.MenuElement(id=None, classes=None, items=None, width=30, border_style=BorderStyle.SINGLE, centered=False)

Base class for menu elements (dropdown, context menu).

This provides the core menu rendering and interaction logic including keyboard navigation, mouse hover/click, and item selection.

Parameters:

• id (str, optional) – Unique identifier

• items (list of MenuItem, optional) – Menu items to display (default: empty list)

• width (int, optional) – Menu width in characters (default: 30)

• border_style (BorderStyle or {"single", "double", "rounded"}, optional) – Border style (default: BorderStyle.SINGLE)

• centered (bool, optional) – Whether to center the menu (default: False, menus position relative to trigger)

• classes (str | list[str] | set[str] | None)

Variables:

• items (list of MenuItem) – Menu items

• width (int) – Menu width

• border_style (BorderStyle) – Border style for rendering

• highlighted_index (int) – Index of currently highlighted item (-1 if none)

• on_item_select (callable or None) – Callback when item is selected: (action_id: str, item: MenuItem) -> None

• close_callback (callable or None) – Callback to close the menu (set externally by app)

__init__(id=None, classes=None, items=None, width=30, border_style=BorderStyle.SINGLE, centered=False)

Parameters:

• id (str | None)

• classes (str | list[str] | set[str] | None)

• items (list[MenuItem] | None)

• width (int)

• border_style (BorderStyle | str)

• centered (bool)

Return type:

None

Methods

__init__([id, classes, items, width, ...])
add_child(element)	Add a child element.
add_class(class_name)	Add a CSS class to this element.
apply_props(props)	Apply props from a VNode, skipping ephemeral props.
get_ephemeral_state()	Get ephemeral state for reconciliation.
get_focusable_children()	Get all focusable child elements.
get_hardware_cursor_position()	Absolute screen cell where the hardware terminal cursor should park.
get_height_for_width(width)	Return the height this element needs when laid out at width.
get_intrinsic_size()	Get the intrinsic (preferred) size of the element.
handle_key(key)	Handle keyboard input for menu navigation.
handle_mouse(event)	Handle mouse input for menu interaction.
has_class(class_name)	Check if element has a CSS class.
on_blur()	Called when element loses focus.
on_focus()	Called when element gains focus.
on_hover_enter()	Called when mouse enters element.
on_hover_exit()	Called when mouse exits element.
on_mount()	Called when element is first added to the element tree.
on_unmount()	Called when element is removed from the element tree.
on_update(changed_props)	Called when element props are updated during reconciliation.
remove_child(element)	Remove a child element.
remove_class(class_name)	Remove a CSS class from this element.
render_signature()	Hashable/comparable capture of everything render_to() reads.
render_to(ctx)	Render the menu using cell-based rendering (NEW API).
restore_ephemeral_state(state)	Restore ephemeral state after reconciliation.
set_bounds(bounds)	Set the element's screen bounds.
toggle_class(class_name)	Toggle a CSS class on this element.

Attributes

captures_tab	Whether this element wants the Tab key instead of focus movement.
parent_frame	Get the parent Frame if this element is inside a scrollable frame.
supports_dynamic_sizing	Whether this element supports dynamic sizing.

handle_key(key)

Handle keyboard input for menu navigation.

Parameters:

key (Key) – Key press to handle

Returns:

True if key was handled

Return type:

bool

async handle_mouse(event)

Handle mouse input for menu interaction.

Parameters:

event (MouseEvent) – Mouse event to handle

Returns:

True if event was handled

Return type:

bool

get_ephemeral_state()

Get ephemeral state for reconciliation.

Returns:

Highlighted index that should survive re-renders.

Return type:

dict

restore_ephemeral_state(state)

Restore ephemeral state after reconciliation.

Parameters:

state (dict) – State dict from get_ephemeral_state()

Return type:

None

render_to(ctx)

Render the menu using cell-based rendering (NEW API).

Parameters:

ctx (PaintContext) – Paint context with buffer, style resolver, and bounds

Return type:

None

Notes

This method uses cell-based rendering with theme styles for menu items, borders, and states. It properly handles highlights, disabled items, and keyboard shortcuts.

Theme styles:

This element uses the following theme style classes: - menu: Base menu style - menu:focus: Focused menu style - menu.border: Border style - menu.border:focus: Focused border style - menu.item: Menu item style - menu.item:highlighted: Highlighted item style - menu.item:disabled: Disabled item style - menu.divider: Divider line style - menu.shortcut: Keyboard shortcut hint style