Widget Reference

All widgets are created through the factory namespace returned by session.get_widgets():

Widgets = session.get_widgets()
btn = Widgets.Button("Click me")           # sync
btn = await Widgets.Button("Click me")     # async

Every widget inherits common base methods (see Base Methods below), plus its own methods listed in each section.

Base Methods

All widgets (except Timer and FileDialog) have these methods:

Method

Description

resize(width, height)

Set widget size in pixels.

get_size()

Return [width, height].

show()

Make the widget visible.

hide()

Hide the widget.

is_visible()

Return visibility state.

set_enabled(tf)

Enable or disable the widget.

get_enabled()

Return enabled state.

set_tooltip(msg)

Set tooltip text.

set_padding(padding)

Set padding in pixels.

set_border_width(width)

Set border width.

set_border_color(color)

Set border color.

set_font(font, size, weight, style)

Set font properties. Pass None to keep defaults.

set_focus()

Give focus to this widget.

set_cursor(name)

Set the mouse cursor.

add_cursor(name, url, hotspot_x, hotspot_y, size)

Register a custom cursor from an image URL or file path.

destroy()

Remove the widget from the browser and Python registry.

Container widgets also have get_children().

Callback Registration

All widgets support two callback registration methods:

# on() -- handler receives callback args only
btn.on("activated", lambda: print("clicked"))

# add_callback() -- handler receives (widget, *callback_args)
btn.add_callback("activated", lambda w: print(f"{w} clicked"))

See Callback System for details.

Layout Containers

VBox

Vertical box layout.

  • Options: (none)

  • Methods: add_widget(child, stretch), set_spacing(gap)

  • Callbacks: (none)

vbox = Widgets.VBox(spacing=8, padding=10)
vbox.add_widget(btn, 0)     # stretch=0 means natural size
vbox.add_widget(label, 1)   # stretch=1 means expand to fill

HBox

Horizontal box layout. Same interface as VBox.

  • Methods: add_widget(child, stretch), set_spacing(gap)

ButtonBox

Box layout for buttons. Like HBox/VBox with an orientation option.

  • Options: orientation

  • Methods: add_widget(child, stretch), set_spacing(gap)

GridBox

Grid layout.

  • Options: rows, columns

  • Methods: add_widget(child, row, col), set_spacing(px), set_row_spacing(px), set_column_spacing(px), get_row_column_count(), get_widget_at_cell(row, col), insert_row(index, widgets), append_row(widgets), delete_row(index), insert_column(index, widgets), append_column(widgets), delete_column(index)

Splitter

Resizable split pane.

  • Options: orientation

  • Methods: add_widget(child), set_sizes(sizes), get_sizes(), set_minimum_size(child, min_px)

  • Callbacks: sizing

Frame

Titled frame (group box).

  • Options: title

  • Methods: set_widget(child), set_title(text)

Expander

Collapsible section.

  • Options: title, collapsible, shadow

  • Methods: set_widget(child), toggleContent()

ScrollArea

Scrollable container.

  • Options: hscrollbar, vscrollbar

  • Methods: set_widget(child)

TabWidget

Tabbed container.

  • Options: closable, reorderable, tab_position

  • Methods: add_widget(child, options), show_widget(child), close_widget(child), set_index(index), get_index(), get_tab_id(child), get_child(tab_id), index_of(child), highlight_tab(child, bgcolor), set_tab_position(tabpos)

  • Callbacks: page-switch, page-close

tabs = Widgets.TabWidget(closable=True, tab_position="top")
tabs.add_widget(panel1, {"title": "Tab 1"})
tabs.add_widget(panel2, {"title": "Tab 2"})

StackWidget

Stacked pages (like tabs without the tab bar).

  • Methods: add_widget(child, options), show_widget(child), set_index(index), get_index()

  • Callbacks: page-switch

MDIWidget

Multiple-document interface container.

  • Methods: add_widget(child, options), cascade_windows(), tile_windows(), get_subwin(child), close_child(child), set_resistance(value)

  • Callbacks: page-switch, page-close

Windows

TopLevel

A floating window (the primary container for an application).

  • Options: resizable, title, moveable, closeable

  • Methods: set_widget(child), set_title(title), set_position(x, y), set_moveable(tf)

  • Callbacks: move, close

top = Widgets.TopLevel(title="My App", resizable=True)
top.resize(800, 600)
top.set_widget(vbox)
top.show()

Page

A page-level container (fills the browser viewport).

  • Methods: set_widget(child)

Dialog

Modal or non-modal dialog with buttons.

  • Args: title, buttons

  • Options: autoclose, resizable, moveable, modal

  • Methods: get_content_area()

  • Callbacks: activated – fires with the button label clicked.

dlg = Widgets.Dialog("Confirm", ["OK", "Cancel"], modal=True)
content = dlg.get_content_area()
# content is a widget you can add children to
dlg.on("activated", lambda btn_text: print(f"Clicked: {btn_text}"))
dlg.show()

ColorDialog

Color picker dialog.

  • Options: color, title, modal, moveable

  • Methods: get_color(), set_color(hex_string)

  • Callbacks: activated, pick

Buttons and Controls

Button

  • Args: text

  • Methods: set_text(text), set_icon(url, size), set_color(bg, fg)

  • Callbacks: activated

btn = Widgets.Button("Click me")
btn.on("activated", lambda: print("clicked"))

CheckBox

  • Args: text

  • Methods: set_state(tf), get_state()

  • Callbacks: activated – fires with the new boolean state.

RadioButton

  • Args: text

  • Options: group

  • Methods: set_text(text), set_state(value), get_state()

  • Callbacks: activated

ToggleButton

  • Args: text

  • Options: group

  • Methods: set_text(text), set_state(value), get_state()

  • Callbacks: activated

Text

Label

  • Args: text

  • Options: halign

  • Methods: set_text(text), get_text(), set_color(bg, fg), set_halign(align)

TextEntry

Single-line text input.

  • Options: text, editable, linehistory, password

  • Methods: set_text(text), get_text(), clear(), set_length(numchars)

  • Callbacks: activated – fires with the entered text.

entry = Widgets.TextEntry(text="Type here", linehistory=5)
entry.on("activated", lambda text: print(f"Entered: {text}"))

TextEntrySet

Text entry with a button.

  • Options: text, value, editable, linehistory

  • Methods: set_button_text(text), set_text(text), get_text(), clear(), set_length(numchars)

  • Callbacks: activated

TextArea

Multi-line text.

  • Args: text

  • Options: wrap, editable

  • Methods: set_text(text), get_text(), append_text(text), clear(), set_editable(tf), set_wrap(tf), set_limit(numlines)

TextSource

Source code editor with line numbers, syntax tags, and gutter icons.

  • Args: text

  • Options: wrap, line_numbers, icon_gutter, editable, font_family, font_size

  • Methods: set_text(text), get_text(), get_length(), insert_text(offset, text, tags), delete_range(start, end), clear(), set_editable(tf), set_wrap(mode), set_line_numbers(tf), set_icon_gutter(tf), set_icon(line, icon_url), get_cursor(), set_cursor(offset), get_selection(), set_selection(start, end), create_tag(name, attrs), remove_tag_def(name), apply_tag(name, start, end), remove_tag(name, start, end), get_tags_at(offset), create_ref(offset, gravity), remove_ref(ref), undo(), redo(), can_undo(), can_redo(), find(query, opts), find_all(query, opts), replace(query, replacement, opts), scroll_to(ref_or_offset), scroll_to_cursor()

  • Callbacks: changed, cursor_moved, line_clicked, icon_clicked

Selectors

ComboBox

Drop-down selector.

  • Options: editable, dropdown_limit

  • Methods: append_text(text), insert_alpha(text), delete_alpha(text), set_text(text), get_text(), set_index(idx), get_index(), get_alpha(idx), clear(), set_length(numchars)

  • Callbacks: activated

SpinBox

Numeric spinner.

  • Options: dtype, min, max, step, value, decimals

  • Methods: set_value(val), get_value(), set_limits(minval, maxval, incrval), set_decimals(num)

  • Callbacks: activated

Slider

  • Options: orientation, track, dtype, min, max, step, value, show_value

  • Methods: set_value(num), get_value(), set_limits(minval, maxval, incrval), set_tracking(track)

  • Callbacks: activated

slider = Widgets.Slider(min=0, max=100, value=50, track=True)
slider.on("activated", lambda val: print(f"Value: {val}"))

Dial

Rotary dial control.

  • Options: track, dtype, min, max, step, value

  • Methods: set_value(num), get_value(), set_limits(minval, maxval, incrval), set_tracking(track), set_knob_diameter(len_px), set_icon(url, size)

  • Callbacks: activated

ScrollBar

  • Options: orientation, thickness

  • Methods: set_scroll_percent(pct), get_scroll_percent(), set_thumb_width(pct)

  • Callbacks: activated

ProgressBar

  • Methods: set_value(value), get_value()

Color

ColorWidget

Inline color picker.

  • Options: color

  • Methods: get_color(), set_color(hex_string)

  • Callbacks: pick

Data Display

Image

Displays an image. Can be interactive for drawing and input events.

  • Options: url, interactive, use_animation_frame

  • Methods: set_image(url), get_draw_context(), update()

  • Callbacks: pointer-down, pointer-up, pointer-move, enter, leave, click, dblclick, scroll, key-down, key-up, key-press, focus-in, focus-out, drop-start, drop-end, drag-over, drop-progress, contextmenu

Canvas

HTML5 canvas for custom drawing.

  • Options: use_animation_frame, interactive

  • Methods: draw_image(imgInfo), get_draw_context(), update()

  • Callbacks: Same interactive callbacks as Image, plus activated.

TreeView

Hierarchical tree/list display.

  • Options: columns, show_header, selection_mode, alternate_row_colors, show_grid, show_row_numbers

  • Methods: set_columns(columns), set_tree(data), set_data(data), add_item(parent, values), remove_item(node), update_tree(items), remove_items(paths), clear(), expand_all(), collapse_all(), get_expanded(), get_collapsed(), expand_item(node), collapse_item(node), get_selected(), set_selected(items), select_path(path, state), select_paths(paths, state), select_all(state), set_column_width(col_index, width), set_optimal_column_widths(), sort_by_column(col_index, ascending), scroll_to_path(path), scroll_to_end(), get_column_count(), get_row_count(), set_show_grid(tf), set_show_row_numbers(tf), set_column_editable(col_index, tf), set_cell(row, col_index, value), insert_column(index, column), append_column(column), delete_column(index), insert_row(index, values), append_row(values), delete_row(index)

  • Callbacks: activated, selected, expanded, collapsed, cell_edited

TableView

Flat table display. Same column/selection interface as TreeView but without tree hierarchy.

  • Options: columns, show_header, selection_mode, alternate_row_colors, show_grid, show_row_numbers

  • Methods: set_columns(columns), set_rows(rows), set_data(data), clear(), get_selected(), set_selected(items), select_path(path, state), select_paths(paths, state), select_all(state), set_column_width(col_index, width), set_optimal_column_widths(), sort_by_column(col_index, ascending), scroll_to_path(path), scroll_to_end(), get_column_count(), get_row_count(), set_show_grid(tf), set_show_row_numbers(tf), set_column_editable(col_index, tf), set_cell(row, col_index, value), insert_column(index, column), append_column(column), delete_column(index), insert_row(index, values), append_row(values), delete_row(index)

  • Callbacks: activated, selected, cell_edited

Non-Visual

Timer

Non-visual timer. Created via session.make_timer() or the widget factory.

  • Options: duration

  • Methods: start(duration), stop(), cancel(), is_set(), elapsed_time(), time_left(), set_duration(duration), get_duration()

  • Callbacks: expired, cancelled

timer = session.make_timer(duration=5000)  # 5 seconds
timer.on("expired", lambda: print("Timer fired!"))
timer.start()

FileDialog

Browser file open/save dialog.

  • Options: mode, accept

  • Methods: open(), save(filename, data, mime_type), set_mode(mode), get_mode(), set_accept(accept), get_accept()

  • Callbacks: activated, progress