Switch

A clickable button with two stable states: True (on, checked); and False (off, unchecked). The button has a text label.

Usage

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

class toga.Switch(text, id=None, style=None, on_change=None, value=False, enabled=True)

Bases: Widget

Create a new Switch widget.

Parameters:

  • text (str) – The text to display beside the switch.

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

  • value (bool) – The initial value for the switch.

  • on_change (toga.widgets.switch.OnChangeHandler | None) – A handler that will be invoked when the switch changes value.

  • enabled (bool) – Is the switch enabled (i.e., can it be pressed?). Optional; by default, switches are created in an enabled state.

property on_change: OnChangeHandler

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

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

toggle()

Reverse the current value of the switch.

Return type:

None

property value: bool

The current state of the switch, as a Boolean.

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

protocol toga.widgets.switch.OnChangeHandler

typing.Protocol.

Classes that implement this protocol must have the following methods / attributes:

__call__(widget, /, **kwargs)

A handler to invoke when the value is changed.

Parameters:

  • widget (Switch) – The Switch that was changed.

  • kwargs (Any) – Ensures compatibility with arguments added in future versions.

Return type:

object