wijjit.elements.display.list.ListView

class wijjit.elements.display.list.ListView(id=None, classes=None, items=None, width=40, height=10, bullet='bullet', show_dividers=False, show_scrollbar=True, border_style='single', title=None, indent_details=2, dim_details=True, tab_index=None, bind=True)

ListView element for displaying lists with bullets, numbers, or details.

This element provides a display for lists with support for: - Multiple bullet styles (bullets, dashes, numbers, or custom characters) - Plain lists without bullets - Details mode for definition-style lists with dimmed, indented details - Optional horizontal dividers between items - Scrolling for long lists - Borders with optional titles - Mouse and keyboard interaction for scrolling

Parameters:

• id (str, optional) – Element identifier

• items (list, optional) – List items (strings, 2-tuples, or dicts) (default: [])

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

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

• bullet (str, optional) – Bullet style: “bullet”, “dash”, “number”, custom character, or None for no bullets (default: “bullet”)

• show_dividers (bool, optional) – Whether to show horizontal lines between items (default: False)

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

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

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

• indent_details (int, optional) – Number of spaces to indent details text (default: 2)

• dim_details (bool, optional) – Whether to dim details text color (default: True)

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

• tab_index (int | None)

• bind (bool | str)

Variables:

• items (list) – Normalized list items

• width (int) – Display width

• height (int) – Display height

• bullet (str or None) – Bullet style or character

• show_dividers (bool) – Whether dividers are shown

• show_scrollbar (bool) – Whether scrollbar is visible

• border_style (str) – Border style

• title (str or None) – Border title

• indent_details (int) – Details indentation

• dim_details (bool) – Whether details are dimmed

• scroll_manager (ScrollManager) – Manages scrolling of content

• rendered_lines (list of str) – Cached rendered content lines

Notes

List items can be specified as: - Strings: [“Item 1”, “Item 2”] - 2-tuples: [(“Label”, “Details”), …] - Dicts: [{“label”: “Label”, “details”: “Details”}, …]

Details can be multi-line (separated by newlines) and will be indented and optionally dimmed.

Examples

Simple bulleted list: >>> listview = ListView(items=[“Apple”, “Banana”, “Cherry”])

Numbered list: >>> listview = ListView(items=[“First”, “Second”, “Third”], bullet=”number”)

Definition list with details: >>> items = [ … (“Python”, “A high-level programming language”), … (“JavaScript”, “A dynamic scripting language”) … ] >>> listview = ListView(items=items, bullet=”dash”)

__init__(id=None, classes=None, items=None, width=40, height=10, bullet='bullet', show_dividers=False, show_scrollbar=True, border_style='single', title=None, indent_details=2, dim_details=True, 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

• items (list[Any] | None)

• width (int)

• height (int)

• bullet (str | None)

• show_dividers (bool)

• show_scrollbar (bool)

• border_style (str)

• title (str | None)

• indent_details (int)

• dim_details (bool)

• bind (bool | str)

Return type:

None

Methods

__init__([id, classes, items, width, ...])	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.
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 scrolling.
handle_mouse(event)	Handle mouse input for 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_class(class_name)	Remove a CSS class from this element.
render_signature()	Hashable/comparable capture of everything render_to() reads.
render_to(ctx)	Render list view using cell-based rendering (NEW API).
restore_ephemeral_state(state)	Restore ephemeral state after reconciliation.
restore_scroll_position(position)	Restore scroll position from saved state.
set_bounds(bounds)	Set the element's screen bounds.
set_items(items)	Update list items and re-render.
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.
items	Get the normalized items list.
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.
supports_dynamic_sizing	Whether this element supports dynamic sizing.

property items: list[dict[str, Any]]

Get the normalized items list.

Returns:

Normalized items with ‘label’ and ‘details’ keys

Return type:

list of dict

set_items(items)

Update list items and re-render.

Parameters:

items (list) – New list items (strings, tuples, or dicts)

Return type:

None

restore_scroll_position(position)

Restore scroll position from saved state.

Parameters:

position (int) – Scroll position to restore

Return type:

None

property scroll_position: int

Get the current scroll position.

Returns:

Current scroll offset (0-based)

Return type:

int

get_ephemeral_state()

Get ephemeral state for reconciliation.

Returns:

Scroll position to preserve across re-renders

Return type:

dict

restore_ephemeral_state(state)

Restore ephemeral state after reconciliation.

Parameters:

state (dict) – State from get_ephemeral_state()

Return type:

None

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

handle_key(key)

Handle keyboard input for scrolling.

Parameters:

key (Key) – Key press to handle

Returns:

True if key was handled

Return type:

bool

async handle_mouse(event)

Handle mouse input for scrolling.

Parameters:

event (MouseEvent) – Mouse event to handle

Returns:

True if event was handled

Return type:

bool

render_to(ctx)

Render list view 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 list views, supporting: - Multiple bullet styles (bullet, dash, number, custom) - Labels and details with indentation - Optional dividers between items - Scrolling with scrollbar - Borders with titles - Theme-based styling

Theme styles:

This element uses the following theme style classes: - listview: Base listview style - listview:focus: When listview has focus - listview.label: For item labels - listview.details: For item details (dimmed) - listview.divider: For horizontal dividers - listview.border: For border characters - listview.border:focus: For border when focused