`libui.widgets` — Widget Nodes¶

Declarative widget nodes — split by category.

class libui.widgets.VBox(*children: Node, padded: bool = True)¶

Bases: Node

Vertical box container.

create_widget(ctx)¶

attach_children(widget, ctx)¶: Override to add children to the widget.

class libui.widgets.HBox(*children: Node, padded: bool = True)¶

Bases: Node

Horizontal box container.

create_widget(ctx)¶

attach_children(widget, ctx)¶: Override to add children to the widget.

class libui.widgets.Group(title: str | State[str], child: Node, margined: bool = True)¶

Bases: Node

Labeled group container with a single child.

create_widget(ctx)¶

attach_children(widget, ctx)¶: Override to add children to the widget.

bind_props(widget)¶: Bind State/Computed props to widget attributes.

class libui.widgets.Form(*rows: tuple, padded: bool = True)¶

Bases: Node

Two-column label-control form.

Children are (label, node) tuples or (label, node, stretchy) triples.

create_widget(ctx)¶

attach_children(widget, ctx)¶: Override to add children to the widget.

class libui.widgets.Tab(*pages: tuple[str, Node], margined: bool = True)¶

Bases: Node

Tabbed container. Children are ("Page Name", node) tuples.

create_widget(ctx)¶

attach_children(widget, ctx)¶: Override to add children to the widget.

class libui.widgets.Grid(*cells: GridCell, padded: bool = True)¶

Bases: Node

Grid layout container.

create_widget(ctx)¶

attach_children(widget, ctx)¶: Override to add children to the widget.

class libui.widgets.GridCell(child: Node, left: int, top: int, xspan: int = 1, yspan: int = 1, hexpand: bool = False, halign=Align.FILL, vexpand: bool = False, valign=Align.FILL)¶

Bases: object

Placement descriptor for a child in a Grid.

class libui.widgets.Label(text: str | State[str] | Computed[str] = '')¶

Bases: Node

Static text label.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

class libui.widgets.Button(text: str = '', on_clicked: Callable | None = None)¶

Bases: Node

Clickable button.

create_widget(ctx)¶

class libui.widgets.Entry(text: State[str] | str | None = None, type: str = 'normal', read_only: State[bool] | bool = False, on_changed: Callable | None = None)¶

Bases: Node

Single-line text entry with optional two-way binding.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

attach_callbacks(widget)¶: Register event callbacks on the widget.

class libui.widgets.Checkbox(text: str = '', checked: State[bool] | bool = False, on_toggled: Callable | None = None)¶

Bases: Node

Checkbox with optional two-way binding for checked.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

attach_callbacks(widget)¶: Register event callbacks on the widget.

class libui.widgets.Slider(min: int = 0, max: int = 100, value: State[int] | int = 0, has_tooltip: bool = True, on_changed: Callable | None = None)¶

Bases: Node

Horizontal slider with optional two-way value binding.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

attach_callbacks(widget)¶: Register event callbacks on the widget.

class libui.widgets.Spinbox(min: int = 0, max: int = 100, value: State[int] | int = 0, on_changed: Callable | None = None)¶

Bases: Node

Numeric spinbox with optional two-way value binding.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

attach_callbacks(widget)¶: Register event callbacks on the widget.

class libui.widgets.ProgressBar(value: State[int] | Computed[int] | int = 0)¶

Bases: Node

Progress bar (one-way binding only).

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

class libui.widgets.Combobox(items: Sequence[str] = (), selected: State[int] | int = 0, on_selected: Callable | None = None)¶

Bases: Node

Drop-down combobox with optional two-way selected binding.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

attach_callbacks(widget)¶: Register event callbacks on the widget.

class libui.widgets.RadioButtons(items: Sequence[str] = (), selected: State[int] | int = -1, on_selected: Callable | None = None)¶

Bases: Node

Radio button group with optional two-way selected binding.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

attach_callbacks(widget)¶: Register event callbacks on the widget.

class libui.widgets.EditableCombobox(items: Sequence[str] = (), text: State[str] | str = '', on_changed: Callable | None = None)¶

Bases: Node

Editable combobox with optional two-way text binding.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

attach_callbacks(widget)¶: Register event callbacks on the widget.

class libui.widgets.MultilineEntry(text: State[str] | str = '', wrapping: bool = True, read_only: State[bool] | bool = False, on_changed: Callable | None = None)¶

Bases: Node

Multi-line text entry with optional two-way text binding.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

attach_callbacks(widget)¶: Register event callbacks on the widget.

class libui.widgets.ColorButton(on_changed: Callable | None = None)¶

Bases: Node

Color picker button.

create_widget(ctx)¶

attach_callbacks(widget)¶: Register event callbacks on the widget.

class libui.widgets.FontButton(on_changed: Callable | None = None)¶

Bases: Node

Font picker button.

create_widget(ctx)¶

attach_callbacks(widget)¶: Register event callbacks on the widget.

class libui.widgets.DateTimePicker(type: str = 'datetime', on_changed: Callable | None = None)¶

Bases: Node

Date/time picker.

create_widget(ctx)¶

attach_callbacks(widget)¶: Register event callbacks on the widget.

class libui.widgets.Separator(vertical: bool = False)¶

Bases: Node

Visual separator line.

create_widget(ctx)¶

Bases: Node

Custom drawing area with optional event callbacks.

Callbacks:

on_draw(ctx, area_w, area_h, clip_x, clip_y, clip_w, clip_h):: Called to paint the area. Must be synchronous.
on_mouse_event(event_dict):: Mouse button/move. Keys: x, y, area_width, area_height, down, up, count, modifiers, held. May be async.
on_mouse_crossed(left: bool):: Mouse entered (False) or left (True) the area. May be async.
on_drag_broken():: OS interrupted a drag. May be async.
on_key_event(event_dict) -> bool:: Key press/release. Keys: key, ext_key, modifier, modifiers, up. Return True to consume. Must be synchronous.

create_widget(ctx)¶

class libui.widgets.ScrollingDrawArea(on_draw: Callable | None = None, width: int = 1000, height: int = 1000, on_mouse_event: Callable | None = None, on_mouse_crossed: Callable | None = None, on_drag_broken: Callable | None = None, on_key_event: Callable | None = None)¶

Bases: Node

Scrollable custom drawing area with a fixed content size.

Same callbacks as DrawArea, plus width/height for the scrollable region.

create_widget(ctx)¶

class libui.widgets.DataTable(data: ListState, *columns: _ColumnDescriptor, on_row_clicked: Callable | None = None, on_row_double_clicked: Callable | None = None, on_header_clicked: Callable | None = None, on_selection_changed: Callable | None = None)¶

Bases: Node

Declarative table backed by a ListState.

Each row in the ListState is a dict. Column descriptors define which keys to display and how.

create_widget(ctx)¶

class libui.widgets.TextColumn(name: str, key: str, editable: bool = False, color_col: int = -1, width: int = -1)¶: Bases: _ColumnDescriptor

class libui.widgets.CheckboxColumn(name: str, key: str, editable: bool = True, width: int = -1)¶: Bases: _ColumnDescriptor

class libui.widgets.CheckboxTextColumn(name: str, checkbox_key: str, text_key: str, checkbox_editable: bool = True, text_editable: bool = False, text_color_col: int = -1, width: int = -1)¶: Bases: _ColumnDescriptor

class libui.widgets.ProgressColumn(name: str, key: str, width: int = -1)¶: Bases: _ColumnDescriptor

class libui.widgets.ButtonColumn(name: str, text_key: str, on_click: Callable | None = None, clickable: bool = True, width: int = -1)¶: Bases: _ColumnDescriptor

class libui.widgets.ImageColumn(name: str, key: str, width: int = -1)¶: Bases: _ColumnDescriptor

class libui.widgets.ImageTextColumn(name: str, image_key: str, text_key: str, editable: bool = False, color_col: int = -1, width: int = -1)¶: Bases: _ColumnDescriptor

Containers¶

Container widget nodes: VBox, HBox, Group, Form, Tab, Grid.

class libui.widgets.containers.VBox(*children: Node, padded: bool = True)¶

Bases: Node

Vertical box container.

create_widget(ctx)¶

attach_children(widget, ctx)¶: Override to add children to the widget.

class libui.widgets.containers.HBox(*children: Node, padded: bool = True)¶

Bases: Node

Horizontal box container.

create_widget(ctx)¶

attach_children(widget, ctx)¶: Override to add children to the widget.

class libui.widgets.containers.Group(title: str | State[str], child: Node, margined: bool = True)¶

Bases: Node

Labeled group container with a single child.

create_widget(ctx)¶

attach_children(widget, ctx)¶: Override to add children to the widget.

bind_props(widget)¶: Bind State/Computed props to widget attributes.

class libui.widgets.containers.Form(*rows: tuple, padded: bool = True)¶

Bases: Node

Two-column label-control form.

Children are (label, node) tuples or (label, node, stretchy) triples.

create_widget(ctx)¶

attach_children(widget, ctx)¶: Override to add children to the widget.

class libui.widgets.containers.Tab(*pages: tuple[str, Node], margined: bool = True)¶

Bases: Node

Tabbed container. Children are ("Page Name", node) tuples.

create_widget(ctx)¶

attach_children(widget, ctx)¶: Override to add children to the widget.

class libui.widgets.containers.GridCell(child: Node, left: int, top: int, xspan: int = 1, yspan: int = 1, hexpand: bool = False, halign=Align.FILL, vexpand: bool = False, valign=Align.FILL)¶

Bases: object

Placement descriptor for a child in a Grid.

class libui.widgets.containers.Grid(*cells: GridCell, padded: bool = True)¶

Bases: Node

Grid layout container.

create_widget(ctx)¶

attach_children(widget, ctx)¶: Override to add children to the widget.

Button¶

Button widget node.

class libui.widgets.button.Button(text: str = '', on_clicked: Callable | None = None)¶

Bases: Node

Clickable button.

create_widget(ctx)¶

Label¶

Label widget node.

class libui.widgets.label.Label(text: str | State[str] | Computed[str] = '')¶

Bases: Node

Static text label.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

Entry¶

Entry and MultilineEntry widget nodes.

class libui.widgets.entry.Entry(text: State[str] | str | None = None, type: str = 'normal', read_only: State[bool] | bool = False, on_changed: Callable | None = None)¶

Bases: Node

Single-line text entry with optional two-way binding.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

attach_callbacks(widget)¶: Register event callbacks on the widget.

class libui.widgets.entry.MultilineEntry(text: State[str] | str = '', wrapping: bool = True, read_only: State[bool] | bool = False, on_changed: Callable | None = None)¶

Bases: Node

Multi-line text entry with optional two-way text binding.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

attach_callbacks(widget)¶: Register event callbacks on the widget.

Checkbox¶

Checkbox widget node.

class libui.widgets.checkbox.Checkbox(text: str = '', checked: State[bool] | bool = False, on_toggled: Callable | None = None)¶

Bases: Node

Checkbox with optional two-way binding for checked.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

attach_callbacks(widget)¶: Register event callbacks on the widget.

Slider¶

Slider widget node.

class libui.widgets.slider.Slider(min: int = 0, max: int = 100, value: State[int] | int = 0, has_tooltip: bool = True, on_changed: Callable | None = None)¶

Bases: Node

Horizontal slider with optional two-way value binding.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

attach_callbacks(widget)¶: Register event callbacks on the widget.

Spinbox¶

Spinbox widget node.

class libui.widgets.spinbox.Spinbox(min: int = 0, max: int = 100, value: State[int] | int = 0, on_changed: Callable | None = None)¶

Bases: Node

Numeric spinbox with optional two-way value binding.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

attach_callbacks(widget)¶: Register event callbacks on the widget.

ProgressBar¶

ProgressBar widget node.

class libui.widgets.progressbar.ProgressBar(value: State[int] | Computed[int] | int = 0)¶

Bases: Node

Progress bar (one-way binding only).

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

Combobox¶

Combobox and EditableCombobox widget nodes.

class libui.widgets.combobox.Combobox(items: Sequence[str] = (), selected: State[int] | int = 0, on_selected: Callable | None = None)¶

Bases: Node

Drop-down combobox with optional two-way selected binding.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

attach_callbacks(widget)¶: Register event callbacks on the widget.

class libui.widgets.combobox.EditableCombobox(items: Sequence[str] = (), text: State[str] | str = '', on_changed: Callable | None = None)¶

Bases: Node

Editable combobox with optional two-way text binding.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

attach_callbacks(widget)¶: Register event callbacks on the widget.

RadioButtons¶

RadioButtons widget node.

class libui.widgets.radiobuttons.RadioButtons(items: Sequence[str] = (), selected: State[int] | int = -1, on_selected: Callable | None = None)¶

Bases: Node

Radio button group with optional two-way selected binding.

create_widget(ctx)¶

bind_props(widget)¶: Bind State/Computed props to widget attributes.

attach_callbacks(widget)¶: Register event callbacks on the widget.

Pickers¶

Picker widget nodes: ColorButton, FontButton, DateTimePicker.

class libui.widgets.pickers.ColorButton(on_changed: Callable | None = None)¶

Bases: Node

Color picker button.

create_widget(ctx)¶

attach_callbacks(widget)¶: Register event callbacks on the widget.

class libui.widgets.pickers.FontButton(on_changed: Callable | None = None)¶

Bases: Node

Font picker button.

create_widget(ctx)¶

attach_callbacks(widget)¶: Register event callbacks on the widget.

class libui.widgets.pickers.DateTimePicker(type: str = 'datetime', on_changed: Callable | None = None)¶

Bases: Node

Date/time picker.

create_widget(ctx)¶

attach_callbacks(widget)¶: Register event callbacks on the widget.

Separator¶

Separator widget node.

class libui.widgets.separator.Separator(vertical: bool = False)¶

Bases: Node

Visual separator line.

create_widget(ctx)¶

Drawing¶

Drawing area widget nodes.

Bases: Node

Custom drawing area with optional event callbacks.

Callbacks:

on_draw(ctx, area_w, area_h, clip_x, clip_y, clip_w, clip_h):: Called to paint the area. Must be synchronous.
on_mouse_event(event_dict):: Mouse button/move. Keys: x, y, area_width, area_height, down, up, count, modifiers, held. May be async.
on_mouse_crossed(left: bool):: Mouse entered (False) or left (True) the area. May be async.
on_drag_broken():: OS interrupted a drag. May be async.
on_key_event(event_dict) -> bool:: Key press/release. Keys: key, ext_key, modifier, modifiers, up. Return True to consume. Must be synchronous.

create_widget(ctx)¶

class libui.widgets.draw.ScrollingDrawArea(on_draw: Callable | None = None, width: int = 1000, height: int = 1000, on_mouse_event: Callable | None = None, on_mouse_crossed: Callable | None = None, on_drag_broken: Callable | None = None, on_key_event: Callable | None = None)¶

Bases: Node

Scrollable custom drawing area with a fixed content size.

Same callbacks as DrawArea, plus width/height for the scrollable region.

create_widget(ctx)¶

Table¶

DataTable widget node and column descriptors.

class libui.widgets.table.TextColumn(name: str, key: str, editable: bool = False, color_col: int = -1, width: int = -1)¶: Bases: _ColumnDescriptor

class libui.widgets.table.CheckboxColumn(name: str, key: str, editable: bool = True, width: int = -1)¶: Bases: _ColumnDescriptor

class libui.widgets.table.CheckboxTextColumn(name: str, checkbox_key: str, text_key: str, checkbox_editable: bool = True, text_editable: bool = False, text_color_col: int = -1, width: int = -1)¶: Bases: _ColumnDescriptor

class libui.widgets.table.ProgressColumn(name: str, key: str, width: int = -1)¶: Bases: _ColumnDescriptor

class libui.widgets.table.ButtonColumn(name: str, text_key: str, on_click: Callable | None = None, clickable: bool = True, width: int = -1)¶: Bases: _ColumnDescriptor

class libui.widgets.table.ImageColumn(name: str, key: str, width: int = -1)¶: Bases: _ColumnDescriptor

class libui.widgets.table.ImageTextColumn(name: str, image_key: str, text_key: str, editable: bool = False, color_col: int = -1, width: int = -1)¶: Bases: _ColumnDescriptor

class libui.widgets.table.DataTable(data: ListState, *columns: _ColumnDescriptor, on_row_clicked: Callable | None = None, on_row_double_clicked: Callable | None = None, on_header_clicked: Callable | None = None, on_selection_changed: Callable | None = None)¶

Bases: Node

Declarative table backed by a ListState.

Each row in the ListState is a dict. Column descriptors define which keys to display and how.

create_widget(ctx)¶

libui.widgets — Widget Nodes¶

Containers¶

Button¶

Label¶

Entry¶

Checkbox¶

Slider¶

Spinbox¶

ProgressBar¶

Combobox¶

RadioButtons¶

Pickers¶

Separator¶

Drawing¶

Table¶

`libui.widgets` — Widget Nodes¶