Widget Reference

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

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

Widget classes can also be imported directly for subclassing — see Subclassing Widgets for details.

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