wijjit.elements.display.tree.Tree

class wijjit.elements.display.tree.Tree(id=None, classes=None, data=None, multiple=False, selected_ids=None, width=40, height=15, show_scrollbar=True, show_root=True, indent_size=2, indicator_style=TreeIndicatorStyle.TRIANGLES_LARGE, border_style='single', title=None, action=None, tab_index=None, bind=True)

Tree element for displaying hierarchical data with expand/collapse.

This element provides a tree view display with support for: - Hierarchical data visualization with tree drawing characters - Expand/collapse functionality for nodes with children - Node selection with visual indicators (single or multiple) - Scrolling for large trees - Mouse and keyboard interaction

Parameters:

• id (str, optional) – Element identifier

• data (dict or list, optional) – Tree data as nested dict or flat list

• multiple (bool, optional) – Enable multiple selection mode (default: False)

• width (int, optional) – Display width in columns (default: 40)

• height (int, optional) – Display height in rows (default: 15)

• show_scrollbar (bool, optional) – Whether to show vertical scrollbar (default: True)

• show_root (bool, optional) – Whether to show root node (default: True)

• indent_size (int, optional) – Number of spaces per indentation level (default: 2)

• indicator_style (TreeIndicatorStyle, optional) – Style for expand/collapse indicators (default: TRIANGLES_LARGE)

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

• title (str, optional) – Title to display in top border (default: None)

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

• selected_ids (list[str] | None)

• action (str | None)

• tab_index (int | None)

• bind (bool | str)

Variables:

• data (dict or list) – Original tree data

• nodes (list of dict) – Flattened tree nodes for rendering

• multiple (bool) – Whether multiple selection is enabled

• width (int) – Display width

• height (int) – Display height

• show_scrollbar (bool) – Whether scrollbar is visible

• show_root (bool) – Whether root node is shown

• indent_size (int) – Indentation per level

• indicator_style (TreeIndicatorStyle) – Style for expand/collapse indicators

• border_style (str) – Border style

• title (str or None) – Border title

• expanded_nodes (set) – Set of expanded node IDs

• selected_node_id (str or None) – ID of currently selected node (single-select mode)

• selected_node_ids (set) – Set of selected node IDs (multi-select mode)

• highlighted_index (int) – Index of highlighted node in visible list

• scroll_manager (ScrollManager) – Manages scrolling of tree nodes

Notes

Tree data can be specified as: - Nested dict: {“label”: “Root”, “value”: “1”, “children”: […]} - Flat list: [{“id”: “1”, “label”: “Root”, “parent_id”: None}, …]

Navigation: - Up/Down: Navigate nodes - Left: Collapse node or move to parent - Right: Expand node or move to first child - Enter/Space: Toggle expand/collapse (single) or toggle selection (multiple) - Home/End: Jump to first/last node - PageUp/PageDown: Scroll by page

__init__(id=None, classes=None, data=None, multiple=False, selected_ids=None, width=40, height=15, show_scrollbar=True, show_root=True, indent_size=2, indicator_style=TreeIndicatorStyle.TRIANGLES_LARGE, border_style='single', title=None, action=None, tab_index=None, bind=True)

Initialize scrollable element.

Parameters:

• id (str, optional) – Element identifier

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

• tab_index (int, optional) – Tab order for focus navigation

• data (dict[str, Any] | list | None)

• multiple (bool)

• selected_ids (list[str] | None)

• width (int)

• height (int)

• show_scrollbar (bool)

• show_root (bool)

• indent_size (int)

• indicator_style (TreeIndicatorStyle)

• border_style (str)

• title (str | None)

• action (str | None)

• bind (bool | str)

Return type:

None

Methods

__init__([id, classes, data, multiple, ...])	Initialize scrollable element.
add_class(class_name)	Add a CSS class to this element.
apply_props(props)	Apply props from a VNode, skipping ephemeral props.
can_scroll(direction)	Check if the element can scroll in the given direction.
collapse_node(node_id)	Collapse a node.
expand_node(node_id)	Expand a node.
get_ephemeral_state()	Get ephemeral state for reconciliation.
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 tree navigation.
handle_mouse(event)	Handle mouse input.
has_class(class_name)	Check if element has a CSS class.
is_selected(node_id)	Check if a node is selected.
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_class(class_name)	Remove a CSS class from this element.
render_signature()	Hashable/comparable capture of everything render_to() reads.
render_to(ctx)	Render tree using cell-based rendering (NEW API).
restore_ephemeral_state(state)	Restore ephemeral state after reconciliation.
select_node(node_id)	Select a node (single-select mode).
set_bounds(bounds)	Set bounds and resize the tree to the space it was allocated.
set_data(data)	Update tree data and refresh display.
toggle_class(class_name)	Toggle a CSS class on this element.
toggle_node(node_id)	Toggle expand/collapse state of a node.
toggle_selection(node_id)	Toggle selection of a node (multi-select mode).

Attributes

captures_tab	Whether this element wants the Tab key instead of focus movement.
data	Get the normalized tree data.
expand_state_key	Get the state key for expanded nodes.
highlight_state_key	Get the state key for highlighted index.
parent_frame	Get the parent Frame if this element is inside a scrollable frame.
scroll_position	Get the current scroll position.
scroll_state_key	Get the state key for vertical scroll position.
scroll_state_key_x	Get the state key for horizontal scroll position.
selected_ids	Get list of selected node IDs.
selected_state_key	Get the state key for selected node.
supports_dynamic_sizing	Whether this element supports dynamic sizing.

property expand_state_key: str | None

Get the state key for expanded nodes.

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

Returns:

State key for expanded nodes, or None if no id

Return type:

str or None

property highlight_state_key: str | None

Get the state key for highlighted index.

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

Returns:

State key for highlight, or None if no id

Return type:

str or None

property selected_state_key: str | None

Get the state key for selected node.

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

Returns:

State key for selection, or None if no id

Return type:

str or None

property data: dict

Get the normalized tree data.

Returns:

Normalized tree data with ‘id’, ‘label’, ‘value’, ‘children’ keys

Return type:

dict

set_data(data)

Update tree data and refresh display.

Parameters:

data (dict or list) – New tree data

Return type:

None

property scroll_position: int

Get the current scroll position.

Returns:

Current scroll offset (0-based)

Return type:

int

can_scroll(direction)

Check if the element can scroll in the given direction.

Parameters:

direction (int) – Scroll direction: negative for up, positive for down

Returns:

True if scrolling in the given direction is possible

Return type:

bool

toggle_node(node_id)

Toggle expand/collapse state of a node.

Parameters:

node_id (str) – ID of node to toggle

Return type:

None

expand_node(node_id)

Expand a node.

Parameters:

node_id (str) – ID of node to expand

Return type:

None

collapse_node(node_id)

Collapse a node.

Parameters:

node_id (str) – ID of node to collapse

Return type:

None

select_node(node_id)

Select a node (single-select mode).

In multi-select mode, use toggle_selection() instead.

Parameters:

node_id (str) – ID of node to select

Return type:

None

toggle_selection(node_id)

Toggle selection of a node (multi-select mode).

Parameters:

node_id (str) – ID of node to toggle

Return type:

None

is_selected(node_id)

Check if a node is selected.

Parameters:

node_id (str) – ID of node to check

Returns:

True if node is selected

Return type:

bool

property selected_ids: list[str]

Get list of selected node IDs.

In single-select mode, returns a list with one element (or empty). In multi-select mode, returns all selected node IDs.

Returns:

List of selected node IDs

Return type:

list of str

handle_key(key)

Handle keyboard input for tree navigation.

Parameters:

key (Key) – Key press to handle

Returns:

True if key was handled

Return type:

bool

async handle_mouse(event)

Handle mouse input.

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:

Highlight, selection, expansion, and scroll state 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

set_bounds(bounds)

Set bounds and resize the tree to the space it was allocated.

self.width/self.height are the tree’s outer dimensions - the border row and column are drawn from them - so they have to track the bounds the layout engine hands out. Without this the tree keeps drawing at its template-declared size and its right border falls outside the parent’s clip when auto-fit shrinks the row (see wijjit.layout.engine.shrink_to_fit).

Parameters:

bounds (Bounds) – New bounds for the element.

Return type:

None

render_to(ctx)

Render tree using cell-based rendering (NEW API).

Parameters:

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

Return type:

None

Notes

This method implements cell-based rendering for tree views with: - Tree drawing characters (├─, └─, │) for hierarchy visualization - Expand/collapse indicators ([+], [-]) - Node selection markers (“>”) - Highlight styling for focused nodes - Theme-based styling for all states - Scrollbar integration

Theme styles:

This element uses the following theme style classes: - tree: Base tree style - tree:focus: When tree has focus - tree.node: Default node style - tree.node:highlight: Highlighted node (keyboard focus) - tree.node:selected: Selected node with marker - tree.indicator: Expand/collapse indicators - tree.border: Border characters - tree.border:focus: Border when focused