Widget

The abstract base class of all widgets.

Availability (Key)

macOS	Linux (GTK)	Linux (Qt)	Windows	iOS	Android	Web	Terminal
●	●	●	●	●	●	○	○

Usage

This class exists only for actual widgets to inherit from; it should not be be instantiated directly.

Every widget has a style object that controls its layout and presentation. By default, this is a Pack style. Style properties can be set in any of these equivalent ways:

import toga
from toga.style import Pack

# Provide a style object.
widget = toga.Label("Hello", style=Pack(margin=10))

# Provide style properties as constructor keyword arguments.
widget = toga.Label("Hello", margin=10)

# Read or write a style property directly on the widget.
widget.margin = 10
assert widget.margin == widget.style.margin

When both a style object and style keyword arguments are provided, the keyword arguments override matching properties from the style object. See the Pack reference for the available default style properties.

Reference

toga.Widget

Widget(id: str | None = None, style: StyleT | None = None, **kwargs)

Create a base Toga widget.

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

Properties provided by the widget's style can also be passed as constructor keyword arguments, or read and written directly on the widget. For example, widget.margin = 10 is equivalent to widget.style.margin = 10. By default, the widget will use Pack, style attributes, but Toga allows for other style representations.

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. These override any matching properties on the style argument. DEFAULT: {}

DEBUG_LAYOUT_ENABLED class-attribute instance-attribute

DEBUG_LAYOUT_ENABLED

Determines whether debug layout mode is enabled.

When enabled, container widgets use distinct background colors to make the layout more visible and help identify issues during development.

See the Debugging Your App guide for more information.

app property writable

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

applicator instance-attribute

applicator

enabled property writable

enabled: bool

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

factory cached property

factory

id property

id: str

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

tab_index property writable

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.

window property writable

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.

__lt__

__lt__(other: Widget) -> bool

__repr__

__repr__() -> str

add

add(*children: Widget) -> None

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() -> None

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() -> None

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: Widget) -> int

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: int, child: Widget) -> None

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() -> None

remove

remove(*children: Widget) -> None

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: Widget, new_child: Widget) -> None

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.