Widget

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

Availability (Key)

macOS	GTK	Windows	iOS	Android	Web	Terminal
●	●	●	●	●	○	○

Reference

toga.Widget

Widget(id=None, style=None, **kwargs)

Bases: Node, PackMixin

Create a base Toga widget.

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

PARAMETER	DESCRIPTION
id	The ID for the widget. TYPE: str | None DEFAULT: None
style	A style object. If no style is provided, a default style will be applied to the widget. TYPE: StyleT | None DEFAULT: None
kwargs	Initial style properties. DEFAULT: {}

DEBUG_LAYOUT_ENABLED class-attribute instance-attribute

DEBUG_LAYOUT_ENABLED

app property writable

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	DESCRIPTION
ValueError	If this widget is already associated with another app.

applicator instance-attribute

applicator

enabled property writable

enabled

Is the widget currently enabled? i.e., can the user interact with the widget?

factory instance-attribute

factory

id property

id

A unique identifier for the widget (read-only).

tab_index property writable

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

window property writable

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.

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

__lt__

__lt__(other)

__repr__

__repr__()

add

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.

PARAMETER	DESCRIPTION
children	The widgets to add as children of this widget. TYPE: Widget DEFAULT: ()

RAISES	DESCRIPTION
ValueError	If this widget cannot have children.

clear

clear()

Remove all child widgets of this node.

Refreshes the widget after removal if any children were removed.

RAISES	DESCRIPTION
ValueError	If this widget cannot have children.

focus

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

index

index(child)

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

PARAMETER	DESCRIPTION
child	The child widget of interest. TYPE: Widget

RETURNS	DESCRIPTION
int	Index of specified child widget in children list.

RAISES	DESCRIPTION
ValueError	If the specified child widget is not found in the list of children.

insert

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.

PARAMETER	DESCRIPTION
index	The position in the list of children where the new widget should be added. TYPE: int
child	The child to insert as a child of this node. TYPE: Widget

RAISES	DESCRIPTION
ValueError	If this widget cannot have children.

refresh

refresh()

remove

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.

PARAMETER	DESCRIPTION
children	The child nodes to remove. TYPE: Widget DEFAULT: ()

RAISES	DESCRIPTION
ValueError	If this widget cannot have children.

replace

replace(old_child, new_child)

Replace an existing child widget with a new child widget.

PARAMETER	DESCRIPTION
old_child	The existing child widget to be replaced. TYPE: Widget
new_child	The new child widget to be included. TYPE: Widget

toga.widgets.base.StyleT module-attribute

StyleT

A type describing a style object. By default, this will be Pack, but Toga allows for other style representations.