libui.core — C Extension

Low-level bindings to libui-ng. All functions (except queue_main, quit, and is_main_thread) must be called from the main UI thread.

Module functions

class libui.core.Attribute

Bases: object

A text attribute. Created by factory functions, not directly.

color

Color as (r, g, b, a), or None.

family

Font family name, or None.

features

OpenType features, or None.

italic

Italic style (TextItalic), or None.

size

Font size, or None.

stretch

Font stretch (TextStretch), or None.

type

Attribute type (AttributeKind enum).

underline

Underline style (Underline), or None.

underline_color

Underline color as (kind, r, g, b, a), or None.

weight

Font weight (TextWeight), or None.

class libui.core.Control

Bases: object

Base class for all UI controls.

destroy()

Destroy the underlying control.

disable()

Disable the control.

enable()

Enable the control.

enabled

True if the control is enabled.

hide()

Hide the control.

show()

Show the control.

visible

True if the control is visible.

class libui.core.DrawContext

Bases: object

A drawing context. Only valid during an Area draw callback.

clip()

Clip to a path.

fill(brush)

Fill a path with a brush.

restore()

Restore the previously saved graphics state.

save()

Save the current graphics state.

stroke(brush, stroke_params)

Stroke a path.

text(x, y)

Draw a text layout at (x, y).

transform()

Apply a transformation matrix.

class libui.core.HorizontalBox(padded=True)

Bases: Box

A horizontal box container.

class libui.core.VerticalBox(padded=True)

Bases: Box

A vertical box container.

libui.core.background_attribute(r, g, b, a)

Create a background color attribute.

libui.core.color_attribute(r, g, b, a)

Create a text color attribute.

libui.core.family_attribute(family)

Create a font family attribute.

libui.core.features_attribute(features)

Create an OpenType features attribute.

libui.core.init()

Initialize the UI library. Must be called before creating any controls.

libui.core.is_main_thread()

Return True if the current thread is the main UI thread.

libui.core.italic_attribute(italic)

Create a font italic attribute.

libui.core.main()

Run the UI main event loop (blocking).

libui.core.main_step(wait=False)

Process one event iteration. Returns True if an event was processed.

libui.core.main_steps()

Enable non-blocking stepping mode.

libui.core.msg_box(window, title, description)

Show a message box.

libui.core.msg_box_error(window, title, description)

Show an error message box.

libui.core.on_should_quit(callback)

Register a callback for quit requests. Return True to allow.

libui.core.open_file(window)

Show a file open dialog. Returns path or None.

libui.core.open_folder(window)

Show a folder open dialog. Returns path or None.

libui.core.queue_main(callable)

Schedule a callable to run on the main UI thread.

libui.core.quit()

Signal the UI event loop to stop.

libui.core.save_file(window)

Show a file save dialog. Returns path or None.

libui.core.size_attribute(size)

Create a font size attribute.

libui.core.stretch_attribute(stretch)

Create a font stretch attribute.

libui.core.underline_attribute(style)

Create an underline attribute.

libui.core.underline_color_attribute(kind, r, g, b, a)

Create an underline color attribute.

libui.core.uninit()

Shut down the UI library.

libui.core.weight_attribute(weight)

Create a font weight attribute.

Widget types

class libui.core.Window(title, width=640, height=480, *, has_menubar=False, margined=True)

Bases: Control

A top-level window.

borderless

Whether the window is borderless.

fullscreen

Whether the window is fullscreen.

margined

Whether the window has a margin.

on_closing()

Register a callback for when the window is closing.

Return True to allow the close, False to prevent it.

resizeable

Whether the window is resizeable.

set_child()

Set the window’s child control.

title

The window title.

class libui.core.Button(text)

Bases: Control

A clickable button.

on_clicked()

Register a callback for when the button is clicked.

text

The button label text.

class libui.core.Label(text)

Bases: Control

A static text label.

text

The label text.

class libui.core.Box(vertical=True, padded=False)

Bases: Control

A container that stacks children.

append(*, stretchy=False)

Add a child control.

delete()

Remove the child at index.

padded

Whether the box has padding between children.

class libui.core.Entry(type='normal')

Bases: Control

A single-line text entry. Type can be ‘normal’, ‘password’, or ‘search’.

on_changed()

Register a callback for when the text changes.

read_only

Whether the entry is read-only.

text

The entry text.

class libui.core.Checkbox(text)

Bases: Control

A checkbox with a text label.

checked

Whether the checkbox is checked.

on_toggled()

Register a callback for when the checkbox is toggled.

text

The checkbox label text.

class libui.core.Combobox

Bases: Control

A drop-down selection control.

append()

Add an item to the combobox.

on_selected()

Register a callback for when the selection changes.

selected

Index of the selected item, or -1.

class libui.core.EditableCombobox

Bases: Control

A combobox that also allows free-text input.

append()

Add an item.

on_changed()

Register a callback for when the text changes.

text

The current text.

class libui.core.RadioButtons

Bases: Control

A group of mutually exclusive radio buttons.

append()

Add a radio button.

on_selected()

Register a callback for when the selection changes.

selected

Index of the selected button, or -1.

class libui.core.Tab

Bases: Control

A tabbed container.

append(child)

Add a tab page.

delete()

Remove the tab page at index.

insert_at(index, child)

Insert a tab page at index.

margined()

Return whether the page at index has a margin.

num_pages()

Return the number of tab pages.

on_selected()

Register a callback for when the selected tab changes.

selected

Index of the selected tab.

set_margined(margined)

Set margin for the page at index.

class libui.core.Group(title, margined=True)

Bases: Control

A labeled container for grouping controls.

margined

Whether the group has a margin.

set_child()

Set the group’s child control.

title

The group title.

class libui.core.Form(padded=True)

Bases: Control

A two-column label-control form layout.

append(child, *, stretchy=False)

Add a labeled row.

delete()

Remove the row at index.

padded

Whether the form has padding between rows.

class libui.core.Grid(padded=True)

Bases: Control

A grid layout container.

append(left, top, xspan=1, yspan=1, hexpand=False, halign=Align.FILL, vexpand=False, valign=Align.FILL)

Add a child to the grid.

insert_at()

Insert a child relative to an existing one.

padded

Whether the grid has padding between cells.

class libui.core.Spinbox(min=0, max=100)

Bases: Control

A numeric input with up/down buttons.

on_changed()

Register a callback for when the value changes.

value

The current integer value.

class libui.core.Slider(min=0, max=100)

Bases: Control

A horizontal slider control.

has_tooltip

Whether the slider shows a tooltip.

on_changed()

Register a callback for when the value changes.

on_released()

Register a callback for when the slider is released.

set_range(max)

Change the slider range.

value

The current integer value.

class libui.core.ProgressBar

Bases: Control

A progress bar. Set value 0-100, or -1 for indeterminate.

value

The current value (0-100), or -1 for indeterminate.

class libui.core.Separator(vertical=False)

Bases: Control

A visual separator line.

class libui.core.MultilineEntry(wrapping=True)

Bases: Control

A multi-line text entry.

append()

Append text to the entry.

on_changed()

Register a callback for when the text changes.

read_only

Whether the entry is read-only.

text

The entry text.

class libui.core.DateTimePicker(type='datetime')

Bases: Control

A date/time picker. Type can be ‘datetime’, ‘date’, or ‘time’.

on_changed()

Register a callback for when the value changes.

time

The current value as a datetime.datetime object.

class libui.core.ColorButton

Bases: Control

A button that opens a color picker.

color

The selected color as an (r, g, b, a) tuple of floats.

on_changed()

Register a callback for when the color changes.

class libui.core.FontButton

Bases: Control

A button that opens a font picker.

font

The selected font as a dict with ‘family’, ‘size’, ‘weight’, ‘italic’, ‘stretch’.

on_changed()

Register a callback for when the font changes.

class libui.core.Menu(name)

Bases: object

An application menu. Must be created before any Window.

append_about_item()

Add a platform About menu item.

append_check_item()

Add a checkable menu item. Returns the MenuItem.

append_item()

Add a menu item. Returns the MenuItem.

append_preferences_item()

Add a platform Preferences menu item.

append_quit_item()

Add a platform Quit menu item.

append_separator()

Add a separator line.

class libui.core.MenuItem

Bases: object

A menu item. Created by Menu methods, not directly instantiated.

checked

Whether the check item is checked.

disable()

Disable the menu item.

enable()

Enable the menu item.

on_clicked()

Register a callback for when the item is clicked.

Drawing types

class libui.core.DrawPath(fill_mode=FillMode.WINDING)

Bases: object

A 2D drawing path.

add_rectangle(y, width, height)

Add a rectangle to the path.

arc_to(yc, radius, start_angle, sweep, negative=False)

Draw an arc.

bezier_to(c1y, c2x, c2y, end_x, end_y)

Draw a cubic bezier curve.

close_figure()

Close the current figure.

end()

Finalize the path for drawing.

ended

True if the path has been finalized with end().

line_to(y)

Draw a line to (x, y).

new_figure(y)

Start a new figure at (x, y).

new_figure_with_arc(yc, radius, start, sweep, negative=False)

Start a new figure with an arc.

class libui.core.DrawBrush

Bases: object

A brush for filling or stroking paths.

a

Alpha component (0.0-1.0).

b

Blue component (0.0-1.0).

g

Green component (0.0-1.0).

outer_radius

Radial gradient outer radius.

r

Red component (0.0-1.0).

set_stops()

Set gradient stops. Each stop is (pos, r, g, b, a).

type

Brush type (BrushType enum).

x0

Gradient start X.

x1

Gradient end X.

y0

Gradient start Y.

y1

Gradient end Y.

class libui.core.DrawStrokeParams

Bases: object

Parameters for stroking a path.

cap

Line cap style (LineCap enum).

dash_phase

Dash pattern phase offset.

join

Line join style (LineJoin enum).

miter_limit

Miter limit for miter joins.

set_dashes()

Set the dash pattern as a list of floats.

thickness

Line thickness.

class libui.core.DrawMatrix

Bases: object

A 2D transformation matrix, initialized to identity.

invert()

Invert the matrix in place. Returns True on success.

invertible()

Return True if the matrix is invertible.

m11

Matrix element [1,1].

m12

Matrix element [1,2].

m21

Matrix element [2,1].

m22

Matrix element [2,2].

m31

Matrix element [3,1] (X translation).

m32

Matrix element [3,2] (Y translation).

multiply()

Multiply with another matrix in place.

rotate(y, degrees)

Apply a rotation around (x, y).

scale(yc, x, y)

Apply a scale around (xc, yc).

set_identity()

Reset to the identity matrix.

skew(y, x_amount, y_amount)

Apply a skew.

transform_point(y)

Return the transformed (x, y) point.

transform_size(y)

Return the transformed (x, y) size.

translate(y)

Apply a translation.

class libui.core.DrawTextLayout(string, default_font, width, align=TextAlign.LEFT)

Bases: object

A laid-out text for drawing.

extents()

Return the (width, height) of the laid-out text.

class libui.core.AttributedString(text)

Bases: object

A string with formatting attributes.

append()

Append unattributed text.

byte_index_to_grapheme()

Convert byte index to grapheme index.

delete(end)

Delete the byte range [start, end).

for_each_attribute()

Iterate attributes. Callback receives (attr, start, end).

grapheme_to_byte_index()

Convert grapheme index to byte index.

insert_at(pos)

Insert unattributed text at byte position.

length

The byte length of the string.

num_graphemes()

Return the number of grapheme clusters.

set_attribute(start, end)

Apply an attribute to the byte range [start, end).

string

The plain text content.

class libui.core.OpenTypeFeatures

Bases: object

A set of OpenType font feature tags.

add(value)

Set a 4-character OpenType feature tag.

clone()

Return a copy of the features.

get()

Get the value of an OpenType feature tag, or None.

items()

Return a list of (tag, value) tuples.

remove()

Remove an OpenType feature tag.

Area types

class libui.core.Area(on_draw, on_mouse_event=None, on_mouse_crossed=None, on_drag_broken=None, on_key_event=None)

Bases: Control

A canvas for custom drawing.

begin_user_window_move()

Begin a user-initiated window move.

begin_user_window_resize()

Begin a user-initiated window resize.

queue_redraw_all()

Request a full redraw.

scroll_to(y, width, height)

Scroll the area to show the given rectangle.

set_size(height)

Set the scrollable area size.

class libui.core.ScrollingArea

Bases: Area

A scrollable canvas for custom drawing.

Table types

class libui.core.Image(width, height)

Bases: object

An image for use in tables.

append(pixel_width, pixel_height, byte_stride)

Append a pixel representation (RGBA premultiplied, bytes).

class libui.core.TableModel(num_columns, column_type, num_rows, cell_value, set_cell_value=None)

Bases: object

A data model for Table, backed by Python callbacks.

row_changed()

Notify that a row was changed.

row_deleted()

Notify that a row was deleted.

row_inserted()

Notify that a row was inserted.

class libui.core.Table(model, row_background_color_column=-1)

Bases: Control

A data table control.

append_button_column(name, btn_col, clickable_col=-1)

append_checkbox_column(name, checkbox_col, editable_col=-1)

append_checkbox_text_column(name, cb_col, cb_editable_col, text_col, ...)

append_image_column(name, img_col)

append_image_text_column(name, img_col, text_col, ...)

append_progress_bar_column(name, col)

append_text_column(name, text_col, editable_col=-1, color_col=-1)

column_width()

Get a column width.

header_set_sort_indicator(indicator)

Set the sort indicator.

header_sort_indicator()

Get the sort indicator for a column.

header_visible

Whether the header row is visible.

on_header_clicked()

Register a callback for header click. Receives column index.

on_row_clicked()

Register a callback for row click. Receives row index.

on_row_double_clicked()

Register a callback for row double-click.

on_selection_changed()

Register a callback for selection changes.

selection

List of selected row indices.

selection_mode

The selection mode (SelectionMode enum).

set_column_width(width)

Set a column width.