libui.declarative — Declarative API

Declarative UI layer for python-libui-ng.

class libui.declarative.State(initial: T)

Bases: Generic[T]

Reactive container. Notifies subscribers on change.

Usage:

value = State(0)
value.subscribe(lambda: print(value.value))
value.value = 42  # prints 42
subscribers: set[Callable]
property value: T
get() → T
set(new: T) → None
update(fn: Callable[[T], T]) → None

Apply a function to the current value: state.update(lambda x: x + 1).

subscribe(cb: Callable) → Callable

Add a subscriber. Returns an unsubscribe function.

unsubscribe(cb: Callable) → None
map(fn: Callable[[T], U]) → Computed[U]

Create a derived readonly state: greeting = name.map(lambda n: f'Hello {n}').

class libui.declarative.Computed(source: State | Computed, fn: Callable)

Bases: Generic[T]

Readonly derived state. Updates automatically when source changes.

subscribers: set[Callable]
property value: T
get() → T
subscribe(cb: Callable) → Callable
unsubscribe(cb: Callable) → None
map(fn: Callable) → Computed
class libui.declarative.ListState(initial: list[T] | None = None)

Bases: Generic[T]

Observable list for tables. Notifies on insert/delete/change.

data: list[T]
subscribers: set[Callable]
subscribe(cb: Callable) → Callable
unsubscribe(cb: Callable) → None
append(item: T) → None
pop(index: int = -1) → T
class libui.declarative.BuildContext(window=None)

Bases: object

Carries shared state during the build phase.

class libui.declarative.Node(**kwargs)

Bases: object

Base descriptor for a UI element. Lightweight — does not create widgets.

Subclasses override create_widget() and optionally attach_children().

create_widget(ctx: BuildContext) → Any
build(ctx: BuildContext) → Any

Materialise the widget tree rooted at this node.

bind_props(widget: Any) → None

Bind State/Computed props to widget attributes.

attach_callbacks(widget: Any) → None

Register event callbacks on the widget.

attach_children(widget: Any, ctx: BuildContext) → None

Override to add children to the widget.

libui.declarative.stretchy(node: Node) → Node

Mark a node as stretchy in a Box layout.

class libui.declarative.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.declarative.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.declarative.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.declarative.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.declarative.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.declarative.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.declarative.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.declarative.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.declarative.Button(text: str = '', on_clicked: Callable | None = None)

Bases: Node

Clickable button.

create_widget(ctx)
class libui.declarative.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.declarative.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.declarative.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.declarative.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.declarative.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.declarative.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.declarative.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.declarative.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.declarative.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.declarative.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.declarative.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.declarative.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.declarative.Separator(vertical: bool = False)

Bases: Node

Visual separator line.

create_widget(ctx)
class libui.declarative.DrawArea(on_draw: Callable | None = None, 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

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.declarative.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.declarative.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.declarative.TextColumn(name: str, key: str, editable: bool = False, color_col: int = -1, width: int = -1)

Bases: _ColumnDescriptor

class libui.declarative.CheckboxColumn(name: str, key: str, editable: bool = True, width: int = -1)

Bases: _ColumnDescriptor

class libui.declarative.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.declarative.ProgressColumn(name: str, key: str, width: int = -1)

Bases: _ColumnDescriptor

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

Bases: _ColumnDescriptor

class libui.declarative.ImageColumn(name: str, key: str, width: int = -1)

Bases: _ColumnDescriptor

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

Bases: _ColumnDescriptor

class libui.declarative.App(window: Window | None = None, menus: list[MenuDef] | None = None)

Bases: object

Application root. Manages menus and a single window.

build(window: Window | None = None, menus: list[MenuDef] | None = None) → None

Materialise the full widget tree: menus first, then window.

Optional window and menus args override values set in __init__.

show() → None

Show the window.

property window

The underlying core Window widget (available after build).

msg_box(title: str, description: str) → None

Show an informational message box.

msg_box_error(title: str, description: str) → None

Show an error message box.

open_file() → str | None

Show an Open File dialog. Returns path or None.

open_folder() → str | None

Show an Open Folder dialog. Returns path or None.

save_file() → str | None

Show a Save File dialog. Returns path or None.

async open_file_async() → str | None
async open_folder_async() → str | None
async save_file_async() → str | None
async msg_box_async(title: str, description: str) → None
async msg_box_error_async(title: str, description: str) → None
async wait() → None

Wait until quit is signalled.

class libui.declarative.Window(title: str = 'Application', width: int = 800, height: int = 600, child: Node | None = None, has_menubar: bool = False, margined: bool = True, on_closing: Callable | None = None)

Bases: Node

Top-level window descriptor.

create_widget(ctx)
attach_children(widget, ctx)

Override to add children to the widget.

attach_callbacks(widget)

Register event callbacks on the widget.

class libui.declarative.MenuDef(title: str, *items: _MenuEntry)

Bases: object

Definition for a top-level menu.

class libui.declarative.MenuItem(name: str, on_click: Callable | None = None)

Bases: _MenuEntry

A regular clickable menu item.

class libui.declarative.CheckMenuItem(name: str, checked: State[bool] | None = None, on_click: Callable | None = None)

Bases: _MenuEntry

A checkable menu item with optional State binding.

class libui.declarative.MenuSeparator

Bases: _MenuEntry

A separator line in a menu.

class libui.declarative.QuitItem

Bases: _MenuEntry

Platform Quit menu item.

class libui.declarative.PreferencesItem

Bases: _MenuEntry

Platform Preferences menu item.

class libui.declarative.AboutItem

Bases: _MenuEntry

Platform About menu item.

App & Window

App root, Window, and Menu descriptors for the declarative UI layer.

class libui.declarative.app.MenuItem(name: str, on_click: Callable | None = None)

Bases: _MenuEntry

A regular clickable menu item.

class libui.declarative.app.CheckMenuItem(name: str, checked: State[bool] | None = None, on_click: Callable | None = None)

Bases: _MenuEntry

A checkable menu item with optional State binding.

class libui.declarative.app.MenuSeparator

Bases: _MenuEntry

A separator line in a menu.

class libui.declarative.app.QuitItem

Bases: _MenuEntry

Platform Quit menu item.

class libui.declarative.app.PreferencesItem

Bases: _MenuEntry

Platform Preferences menu item.

class libui.declarative.app.AboutItem

Bases: _MenuEntry

Platform About menu item.

class libui.declarative.app.MenuDef(title: str, *items: _MenuEntry)

Bases: object

Definition for a top-level menu.

class libui.declarative.app.Window(title: str = 'Application', width: int = 800, height: int = 600, child: Node | None = None, has_menubar: bool = False, margined: bool = True, on_closing: Callable | None = None)

Bases: Node

Top-level window descriptor.

create_widget(ctx)
attach_children(widget, ctx)

Override to add children to the widget.

attach_callbacks(widget)

Register event callbacks on the widget.

class libui.declarative.app.App(window: Window | None = None, menus: list[MenuDef] | None = None)

Bases: object

Application root. Manages menus and a single window.

build(window: Window | None = None, menus: list[MenuDef] | None = None) → None

Materialise the full widget tree: menus first, then window.

Optional window and menus args override values set in __init__.

show() → None

Show the window.

property window

The underlying core Window widget (available after build).

msg_box(title: str, description: str) → None

Show an informational message box.

msg_box_error(title: str, description: str) → None

Show an error message box.

open_file() → str | None

Show an Open File dialog. Returns path or None.

open_folder() → str | None

Show an Open Folder dialog. Returns path or None.

save_file() → str | None

Show a Save File dialog. Returns path or None.

async open_file_async() → str | None
async open_folder_async() → str | None
async save_file_async() → str | None
async msg_box_async(title: str, description: str) → None
async msg_box_error_async(title: str, description: str) → None
async wait() → None

Wait until quit is signalled.