wijjit.elements.display.tabbed_panel.TabbedPanel

class wijjit.elements.display.tabbed_panel.TabbedPanel(id=None, classes=None, tab_index=None, tab_position=TabPosition.TOP, width=60, height=20, border_style='single', active_tab_index=0, bind=True)

Tabbed panel element for displaying multiple frames with tab switching.

This element provides a tab interface for switching between multiple child frames. Tabs can be positioned on any side of the content area and support both keyboard and mouse navigation.

Parameters:

• id (str, optional) – Element identifier

• classes (str or list of str or set of str, optional) – CSS class names for styling

• tab_position (TabPosition, optional) – Position of tabs (default: TabPosition.TOP)

• width (int, optional) – Total panel width (default: 60)

• height (int, optional) – Total panel height (default: 20)

• border_style (str, optional) – Border style: “single”, “double”, “rounded” (default: “single”)

• active_tab_index (int, optional) – Initially active tab index (default: 0)

• tab_index (int | None)

• bind (bool | str)

Variables:

• tabs (list of tuple) – List of (label, frame) tuples representing tabs

• active_tab_index (int) – Index of currently active tab

• tab_position (TabPosition) – Position of tabs

• width (int) – Total panel width

• height (int) – Total panel height

• border_style (BorderStyle) – Border style for panel

• on_tab_change (Callable or None) – Callback when active tab changes: on_tab_change(index, label)

Notes

Navigation: - Horizontal tabs (TOP/BOTTOM): Left/Right arrows switch tabs - Vertical tabs (LEFT/RIGHT): Up/Down arrows switch tabs - Mouse click on tab: Switch to that tab - Enter/Space: Activate highlighted tab

State Persistence: - Active tab index is saved to state[id] or state[active_tab_key] - Tab state is restored on render

__init__(id=None, classes=None, tab_index=None, tab_position=TabPosition.TOP, width=60, height=20, border_style='single', active_tab_index=0, bind=True)

Parameters:

• id (str | None)

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

• tab_index (int | None)

• tab_position (TabPosition)

• width (int)

• height (int)

• border_style (str)

• active_tab_index (int)

• bind (bool | str)

Return type:

None

Methods

__init__([id, classes, tab_index, ...])
add_child(element)	Add a child element.
add_class(class_name)	Add a CSS class to this element.
add_tab(label, content)	Add a tab to the panel.
apply_props(props)	Apply props from a VNode, skipping ephemeral props.
collect_child_elements()	Collect all child elements from the active tab for event routing.
get_ephemeral_state()	Get ephemeral state for reconciliation.
get_focusable_children()	Get focusable children from the active tab's content.
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 tabbed panel.
handle_key(key)	Handle keyboard input for tab navigation and content scrolling.
handle_mouse(event)	Handle mouse input for tab clicking and content scrolling.
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 tabbed panel using cell-based rendering.
restore_ephemeral_state(state)	Restore ephemeral state after reconciliation.
set_bounds(bounds)	Set the element's screen bounds.
switch_to_tab(index)	Switch to a specific tab by index.
toggle_class(class_name)	Toggle a CSS class on this element.

Attributes

active_tab_state_key	Get the state key for active tab index.
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.

property active_tab_state_key: str | None

Get the state key for active tab index.

Returns the explicitly set key if provided, otherwise auto-generates from the element id using the convention “{id}:active_tab”.

Returns:

State key for active tab, or None if no id

Return type:

str or None

add_tab(label, content)

Add a tab to the panel.

Parameters:

• label (str) – Tab label text

• content (Frame or FrameNode) – Content for the tab - can be a Frame object or FrameNode with children

Return type:

None

switch_to_tab(index)

Switch to a specific tab by index.

Parameters:

index (int) – Tab index to switch to

Return type:

None

Notes

If index is out of range, it will be clamped to valid range. Emits on_tab_change callback if tab actually changed. Saves state if state persistence is enabled.

get_focusable_children()

Get focusable children from the active tab’s content.

Returns:

List of focusable elements in the active tab

Return type:

list

collect_child_elements()

Collect all child elements from the active tab for event routing.

Returns:

List of all elements in the active tab’s content

Return type:

list

Notes

This method is called by ElementNode.collect_elements() to include nested elements in the positioned_elements list for focus and mouse event routing.

handle_key(key)

Handle keyboard input for tab navigation and content scrolling.

Parameters:

key (Key) – Key press to handle

Returns:

True if key was handled

Return type:

bool

Notes

Tab switching: - Horizontal (TOP/BOTTOM): Left/Right to switch tabs - Vertical (LEFT/RIGHT): Up/Down to switch tabs

All other keys are delegated to the active frame’s content, allowing natural scrolling (Up/Down/PageUp/PageDown/Home/End) and any other key handling the frame supports.

async handle_mouse(event)

Handle mouse input for tab clicking and content scrolling.

Parameters:

event (MouseEvent) – Mouse event to handle

Returns:

True if event was handled

Return type:

bool

Notes

Handles: - Left clicks on tab labels to switch tabs - Scroll wheel events delegated to active frame for scrolling

get_ephemeral_state()

Get ephemeral state for reconciliation.

Returns:

Active tab 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 tabbed panel using cell-based rendering.

Parameters:

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

Return type:

None

Notes

Renders the tab interface and active tab’s content: 1. Render tab area with labels 2. Highlight active tab 3. Render borders around panel 4. Render active tab’s frame content in content area

Theme styles:

This element uses the following theme style classes: - tabbedpanel: Base panel style - tabbedpanel:focus: When panel has focus - tabbedpanel.tab: Tab label style - tabbedpanel.tab:active: Active tab style - tabbedpanel.border: Border style

get_intrinsic_size()

Get the intrinsic (preferred) size of the tabbed panel.

Returns:

(width, height) in characters/lines

Return type:

tuple of int

Notes

Returns the configured width and height of the panel.