Button¶

A button that can be pressed or clicked.

Usage¶

A button has a text label, or an icon (but not both). If an icon is specified, it will be resized to a size appropriate for the platform. A handler can be associated with button press events.

import toga

def my_callback(button):
    # handle event
    pass

button = toga.Button("Click me", on_press=my_callback)

icon_button = toga.Button(icon=toga.Icon("resources/my_icon"), on_press=my_callback)

Notes¶

A background color of TRANSPARENT will be treated as a reset of the button to the default system color.
On macOS, the button text color cannot be set directly; any color style directive will be ignored. The text color is automatically selected by the platform to contrast with the background color of the button.

Reference¶

toga.Button ¶

Button(
    text=None,
    icon=None,
    id=None,
    style=None,
    on_press=None,
    enabled=True,
    **kwargs,
)

Bases: Widget

Create a new button widget.

PARAMETER	DESCRIPTION
`text`	The text to display on the button. TYPE: `str \| None` DEFAULT: `None`
`icon`	The icon to display on the button. Can be specified as any valid icon content. TYPE: `IconContentT \| None` DEFAULT: `None`
`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`
`on_press`	A handler that will be invoked when the button is pressed. TYPE: `OnPressHandler \| None` DEFAULT: `None`
`enabled`	Is the button enabled (i.e., can it be pressed?). Optional; by default, buttons are created in an enabled state. TYPE: `bool` DEFAULT: `True`
`kwargs`	Initial style properties. DEFAULT: `{}`

icon `property` `writable` ¶

icon

The icon displayed on the button.

Can be specified as any valid icon content.

If the button is currently displaying text, and an icon is assigned, the text will be replaced by the new icon.

If None is assigned as an icon, the button will become a text button with an empty label.

Returns None if the button is currently displaying text.

on_press `property` `writable` ¶

on_press

The handler to invoke when the button is pressed.

text `property` `writable` ¶

text

The text displayed on the button.

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.

If the button is currently displaying an icon, and text is assigned, the icon will be replaced by the new text.

If the button is currently displaying an icon, the empty string will be returned.

toga.widgets.button.OnPressHandler ¶

Bases: Protocol

call ¶

__call__(widget, **kwargs)

A handler that will be invoked when a button is pressed.

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