Button#

A button that can be pressed or clicked.

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

Usage#

A button has a text label. 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)

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

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

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