Switch¶

A labeled on/off button.

Usage¶

A Switch's button has a text label, and two states: True (on, checked); and False (off, unchecked).

import toga

switch = toga.Switch()

# What is the current state of the switch?
print(f"The switch is {switch.value}")

Notes¶

The button and the label are considered a single widget for layout purposes.
The visual appearance of a Switch is not guaranteed. On some platforms, it will render as a checkbox. On others, it will render as a physical "switch" whose position (and color) indicates if the switch is active. When rendered as a checkbox, the label will appear to the right of the checkbox. When rendered as a switch, the label will be left-aligned, and the switch will be right-aligned.
You should avoid setting a height style property on Switch widgets. The rendered height of the Switch widget will be whatever the platform style guide considers appropriate; explicitly setting a height for the widget can lead to widgets that have a distorted appearance.
On macOS, the text color of the label cannot be set directly; any color style directive will be ignored.

Reference¶

toga.Switch ¶

Switch(
    text: str,
    id: str | None = None,
    style: StyleT | None = None,
    on_change: OnChangeHandler | None = None,
    value: bool = False,
    enabled: bool = True,
    **kwargs,
)

Bases: Widget

Create a new Switch widget.

PARAMETER	DESCRIPTION
`text`	The text to display beside the switch. TYPE: `str`
`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`
`value`	The initial value for the switch. TYPE: `bool` DEFAULT: `False`
`on_change`	A handler that will be invoked when the switch changes value. TYPE: `OnChangeHandler \| None` DEFAULT: `None`
`enabled`	Is the switch enabled (i.e., can it be pressed?). Optional; by default, switches are created in an enabled state. TYPE: `bool` DEFAULT: `True`
`kwargs`	Initial style properties. DEFAULT: `{}`

on_change `property` `writable` ¶

on_change: OnChangeHandler

The handler to invoke when the value of the switch changes.

text `property` `writable` ¶

text: str

The text label for the Switch.

None, and the Unicode codepoint U+200B (ZERO WIDTH SPACE), will be interpreted and returned as an empty string. Any other object will be converted to a string using str().

Only one line of text can be displayed. Any content after the first newline will be ignored.

value `property` `writable` ¶

value: bool

The current state of the switch, as a Boolean.

Any non-Boolean value will be converted to a Boolean.

toggle ¶

toggle() -> None

Reverse the current value of the switch.

toga.widgets.switch.OnChangeHandler ¶

Bases: Protocol

call ¶

__call__(widget: Switch, **kwargs: Any) -> None

A handler to invoke when the value is changed.

PARAMETER	DESCRIPTION
`widget`	The Switch that was changed. TYPE: `Switch`
`kwargs`	Ensures compatibility with arguments added in future versions. TYPE: `Any` DEFAULT: `{}`