Widget¶

The abstract base class of all widgets. This class should not be be instantiated directly.

Availability (Key)¶
macOS	GTK	Windows	iOS	Android	Web	Terminal
●	●	●	●	●	○	○

Reference¶

class toga.Widget(id=None, style=None, **kwargs)¶

Bases: Node, PackMixin

Create a base Toga widget.

This is an abstract base class; it cannot be instantiated.

Parameters:

id (str | None) – The ID for the widget.
style (StyleT | None) – A style object. If no style is provided, a default style will be applied to the widget.
kwargs – Initial style properties.

add(*children)¶

Add the provided widgets as children of this widget.

If a child widget already has a parent, it will be re-parented as a child of this widget. If the child widget is already a child of this widget, there is no change.

Parameters:: children (Widget) – The widgets to add as children of this widget.
Raises:: ValueError – If this widget cannot have children.
Return type:: None

property app: App | None¶

The App to which this widget belongs.

When setting the app for a widget, all children of this widget will be recursively assigned to the same app.

Raises:: ValueError – If this widget is already associated with another app.

property applicator¶

This node’s applicator, which handles applying the style.

Assigning an applicator triggers an application of the node’s style.

property can_have_children¶

Determine if the node can have children.

This does not resolve whether there actually are any children; it only confirms whether children are theoretically allowed.

property children¶

The children of this node. This always returns a list, even if the node is a leaf and cannot have children.

Returns:: A list of the children for this widget.

clear()¶

Remove all child widgets of this node.

Refreshes the widget after removal if any children were removed.

Raises:: ValueError – If this widget cannot have children.
Return type:: None

property enabled: bool¶: Is the widget currently enabled? i.e., can the user interact with the widget?

focus()¶

Give this widget the input focus.

This method is a no-op if the widget can’t accept focus. The ability of a widget to accept focus is platform-dependent. In general, on desktop platforms you can focus any widget that can accept user input, while on mobile platforms focus is limited to widgets that accept text input (i.e., widgets that cause the virtual keyboard to appear).

Return type:: None

property id: str¶: A unique identifier for the widget (read-only).

index(child)¶

Get the index of a widget in the list of children of this widget.

Parameters:: child (Widget) – The child widget of interest.
Raises:: ValueError – If the specified child widget is not found in the list of children.
Returns:: Index of specified child widget in children list.
Return type:: int

insert(index, child)¶

Insert a widget as a child of this widget.

If a child widget already has a parent, it will be re-parented as a child of this widget. If the child widget is already a child of this widget, there is no change.

Parameters:

index (int) – The position in the list of children where the new widget should be added.
child (Widget) – The child to insert as a child of this node.

Raises:

ValueError – If this widget cannot have children.

Return type:

None

property parent¶

The parent of this node.

Returns:: The parent of this node. Returns None if this node is the root node.

refresh()¶

Refresh the layout and appearance of the tree this node is contained in.

Return type:: None

remove(*children)¶

Remove the provided widgets as children of this node.

Any nominated child widget that is not a child of this widget will not have any change in parentage.

Refreshes the widget after removal if any children were removed.

Parameters:: children (Widget) – The child nodes to remove.
Raises:: ValueError – If this widget cannot have children.
Return type:: None

replace(old_child, new_child)¶

Replace an existing child widget with a new child widget.

Parameters:

old_child (Widget) – The existing child widget to be replaced.
new_child (Widget) – The new child widget to be included.

Return type:

None

property root¶

The root of the tree containing this node.

Returns:: The root node. Returns self if this node is the root node.

property style¶

The node’s style.

Assigning a style triggers an application of that style if an applicator has already been assigned.

property tab_index: int | None¶: The position of the widget in the focus chain for the window.

Note

This is a beta feature. The tab_index API may change in the future.

property window: Window | None¶

The window to which this widget belongs.

When setting the window for a widget, all children of this widget will be recursively assigned to the same window.

If the widget has a value for window, it must also have a value for app.

class toga.widgets.base.PackMixin¶: Allows accessing the Pack style properties directly on the widget. For example, instead of widget.style.color, you can simply write widget.color.