API Reference¶

Module structure¶

libui
├── core            # C extension — low-level bindings to libui-ng
├── loop            # Threading model — run(), invoke_on_main(), etc.
├── state           # Reactive state — State, Computed, ListState
├── node            # Node base class, BuildContext, stretchy
├── declarative     # High-level API — re-exports everything below
│   └── app         # App, Window, MenuDef, MenuItem, etc.
└── widgets         # Individual widget node implementations
    ├── containers  # VBox, HBox, Group, Form, Tab, Grid, GridCell
    ├── button      # Button
    ├── label       # Label
    ├── entry       # Entry, MultilineEntry
    ├── checkbox    # Checkbox
    ├── slider      # Slider
    ├── spinbox     # Spinbox
    ├── progressbar # ProgressBar
    ├── combobox    # Combobox, EditableCombobox
    ├── radiobuttons # RadioButtons
    ├── pickers     # ColorButton, FontButton, DateTimePicker
    ├── separator   # Separator
    ├── draw        # DrawArea, ScrollingDrawArea
    └── table       # DataTable, column descriptors

`libui` (top-level)¶

The top-level libui module re-exports thread-safe proxy classes for the imperative API:

import libui

window = libui.Window("Title", 400, 300)
button = libui.Button("Click")
label = libui.Label("Hello")
# ... etc

These are proxy wrappers around libui.core objects that automatically dispatch mutations to the main thread.

Functions¶

libui.loop.run() — Start the two-thread architecture and run your async function
libui.loop.quit() — Stop the UI event loop (thread-safe)

`libui.declarative`¶

The declarative module provides all building blocks for the recommended API:

from libui.declarative import App, Window, VBox, Label, Button, State

See the Widget Reference for complete widget documentation.

Exports¶

App & Window: App, Window

Containers: VBox, HBox, Group, Form, Tab, Grid, GridCell

Controls: Label, Button, Entry, MultilineEntry, Checkbox, Slider, Spinbox, ProgressBar, Combobox, EditableCombobox, RadioButtons, ColorButton, FontButton, DateTimePicker, Separator

Drawing: DrawArea, ScrollingDrawArea

Tables: DataTable, ListState, TextColumn, CheckboxColumn, CheckboxTextColumn, ProgressColumn, ButtonColumn, ImageColumn, ImageTextColumn

Menus: MenuDef, MenuItem, CheckMenuItem, MenuSeparator, QuitItem, PreferencesItem, AboutItem

State: State, Computed, ListState

Helpers: stretchy()

`libui.state`¶

`State`¶

Method	Description
`get()`	Get current value
`set()`	Set value and notify
`update()`	Apply `fn(current) -> new` and notify
`subscribe()`	Add subscriber, returns unsubscribe function
`unsubscribe()`	Remove subscriber
`map()`	Create `Computed` derived value

`Computed`¶

Method	Description
`get()`	Get current computed value
`subscribe()`	Add subscriber
`unsubscribe()`	Remove subscriber
`map()`	Chain another derived value

`ListState`¶

Method	Description
`append()`	Add item, notify with `event="inserted"`
`pop()`	Remove item, notify with `event="deleted"`
`subscribe()`	Add subscriber for change events

`libui.loop`¶

Function	Description
`run()`	Start UI + asyncio event loops
`quit()`	Stop the event loop
`invoke_on_main()`	Run `fn` on main thread, block for result
`invoke_on_main_async()`	Run `fn` on main thread, return awaitable

`libui.core`¶

The C extension module. Provides direct access to libui-ng widgets without thread-safety wrappers. All functions (except queue_main and quit) must be called from the main thread.

Functions¶

Function	Thread-safe	Description
`init()`	No	Initialize libui
`uninit()`	No	Clean up libui
`main()`	No	Run the main event loop (blocking)
`main_steps()`	No	Enable stepping mode
`main_step()`	No	Process one event (requires `main_steps()` first)
`quit()`	Yes	Stop the event loop
`queue_main()`	Yes	Enqueue function for main thread
`is_main_thread()`	Yes	Check if on main thread
`on_should_quit()`	No	Register quit handler

Dialogs¶

Function	Description
`open_file()`	Show file open dialog, returns path or `None`
`open_folder()`	Show folder open dialog, returns path or `None`
`save_file()`	Show file save dialog, returns path or `None`
`msg_box()`	Show info message box
`msg_box_error()`	Show error message box

Text attributes¶

Function	Description
`family_attribute()`	Font family attribute
`size_attribute()`	Font size attribute
`weight_attribute()`	Font weight attribute
`italic_attribute()`	Italic style attribute
`stretch_attribute()`	Font stretch attribute
`color_attribute()`	Text color attribute
`background_attribute()`	Background color attribute
`underline_attribute()`	Underline style attribute
`underline_color_attribute()`	Underline color attribute
`features_attribute()`	OpenType features attribute

Types¶

Type	Description
`Window`	Top-level window
`Button`	Clickable button
`Label`	Text label
`Box`	Vertical/horizontal container
`Entry`	Text input
`Checkbox`	Toggle checkbox
`Combobox`	Dropdown selector
`EditableCombobox`	Editable dropdown
`RadioButtons`	Radio button group
`Tab`	Tabbed container
`Group`	Titled container
`Form`	Label + control pairs
`Grid`	Grid layout
`Spinbox`	Numeric spinner
`Slider`	Range slider
`ProgressBar`	Progress indicator
`Separator`	Visual divider
`MultilineEntry`	Multi-line text editor
`DateTimePicker`	Date/time picker
`ColorButton`	Color picker
`FontButton`	Font picker
`Menu`	Menu bar entry
`MenuItem`	Menu item
`DrawPath`	Geometry path
`DrawBrush`	Fill/stroke brush
`DrawStrokeParams`	Stroke parameters
`DrawMatrix`	Affine transform
`DrawTextLayout`	Formatted text layout
`AttributedString`	Rich text with attributes
`OpenTypeFeatures`	OpenType feature set
`Image`	Image for tables
`TableModel`	Table data model
`Table`	Data table widget
`Area`	Custom drawing surface
`ScrollingArea`	Scrollable drawing surface

API Reference¶

Module structure¶

libui (top-level)¶

Functions¶

libui.declarative¶

Exports¶

libui.state¶

State¶

Computed¶

ListState¶

libui.loop¶

libui.core¶

Functions¶

Dialogs¶

Text attributes¶

Types¶

Full API docs¶

`libui` (top-level)¶

`libui.declarative`¶

`libui.state`¶

`State`¶

`Computed`¶

`ListState`¶

`libui.loop`¶

`libui.core`¶