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)#

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 – A style object. If no style is provided, a default style will be applied to the widget.

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 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#

The DOM identifier for the widget.

This id can be used to target CSS directives.

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

property root#

The root of the tree containing this node.

Returns:

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

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.