Widget#

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

Availability (Key)#

macOS

GTK

Windows

iOS

Android

Web

●

●

●

●

●

○

Reference#

class toga.widgets.base.Widget(id=None, style=None)#

Create a base Toga widget.

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

Parameters:

  • id – 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.

Raises ValueError if this widget cannot have children.

Parameters:

children – The widgets to add as children of this widget.

property app#

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

Clear all children from this node.

Raises:

ValueError – If this node is a leaf, and cannot have children.

property enabled#

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

property id#

The unique identifier for the widget.

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.

Raises ValueError if this node cannot have children.

Parameters:

  • index – The position in the list of children where the new widget should be added.

  • child – The child to insert as a child of this node.

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.

refresh_sublayouts()#
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.

Raises ValueError if this widget cannot have children.

Parameters:

children – The child nodes to remove.

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#

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 future.

property window#

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.