Button#

A button that can be pressed or clicked.

../../../_images/button-cocoa.png

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#

class toga.Button(text=None, icon=None, id=None, style=None, on_press=None, enabled=True)#

Bases: Widget

Create a new button widget.

Parameters:

  • text (str | None) – The text to display on the button.

  • icon (IconContent | None) – The icon to display on the button. Can be specified as any valid icon content.

  • id (str | None) – The ID for the widget.

  • style – A style object. If no style is provided, a default style will be applied to the widget.

  • on_press (OnPressHandler | None) – A handler that will be invoked when the button is pressed.

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

property icon: Icon | None#

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.

property on_press: OnPressHandler#

The handler to invoke when the button is pressed.

property text: str#

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.

protocol toga.widgets.button.OnPressHandler#

typing.Protocol.

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

__call__(widget, **kwargs)#

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

Note

**kwargs ensures compatibility with additional arguments introduced in future versions.

Parameters:

  • widget (Button) – The button that was pressed.

  • kwargs (Any) –

Return type:

None