Widget¶
The abstract base class of all widgets. This class should not be be instantiated directly.
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
- 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:
- 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:
- 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.
- 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.
- 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 writewidget.color
.