Selection#

A widget to select a single option from a list of alternatives.

../../../_images/Selection.png
Availability (Key)#

macOS

GTK

Windows

iOS

Android

Web

Terminal

●

●

●

●

●

Usage#

The Selection uses a ListSource to manage the list of options. If items is not specified as a ListSource, it will be converted into a ListSource at runtime.

The simplest instantiation of a Selection is to use a list of strings. If a list of non-string objects are provided, they will be converted into a string for display purposes, but the original data type will be retained when returning the current value.

import toga

selection = toga.Selection(items=["Alice", "Bob", "Charlie"])

# Change the selection to "Charlie"
selection.value = "Charlie"

# Which item is currently selected? This will print "Charlie"
print(f"Currently selected: {selection.value}")

A Selection can also be used to display a list of dictionaries, with the accessor detailing which attribute of the dictionary will be used for display purposes. When the current value of the widget is retrieved, a Row object will be returned; this Row object will have all the original data as attributes on the Row. In the following example, the GUI will only display the names in the list of items, but the age will be available as an attribute on the selected item.

import toga

selection = toga.Selection(
    items=[
        {"name": "Alice", "age": 37},
        {"name": "Bob", "age": 42},
        {"name": "Charlie", "age": 24},
    ],
    accessor="name",
)

# Select Bob explicitly
selection.value = selection.items[1]

# What is the age of the currently selected person? This will print 42
print(f"Age of currently selected person: {selection.value.age}")

# Select Charlie by searching
selection.value = selection.items.find(name="Charlie")

Notes#

  • On macOS and Android, you cannot change the font of a Selection.

  • On macOS, GTK and Android, you cannot change the text color, background color, or alignment of labels in a Selection.

  • On GTK, a Selection widget with flexible sizing will expand its width (to the extent possible possible) to accommodate any changes in content (for example, to accommodate a long label). However, if the content subsequently decreases in width, the Selection widget will not shrink. It will retain the size necessary to accommodate the longest label it has historically contained.

  • On iOS, the size of the Selection widget does not adapt to the size of the currently displayed content, or the potential list of options.

Reference#

class toga.Selection(id=None, style=None, items=None, accessor=None, value=None, on_change=None, enabled=True, on_select=None)#

Bases: Widget

Create a new Selection widget.

Parameters:

  • id – The ID for the widget.

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

  • items (list | ListSource | None) – Initial items to display for selection.

  • accessor (str | None) – The accessor to use to extract display values from the list of items. See items and value for details on how accessor alters the interpretation of data in the Selection.

  • value (None) – Initial value for the selection. If unspecified, the first item in items will be selected.

  • on_change (callable | None) – Initial on_change handler.

  • enabled – Whether the user can interact with the widget.

property items: ListSource#

The items to display in the selection.

When setting this property:

  • A Source will be used as-is. It must either be a ListSource, or a custom class that provides the same methods.

  • A value of None is turned into an empty ListSource.

  • Otherwise, the value must be an iterable, which is copied into a new ListSource using the widget’s accessor, or “value” if no accessor was specified. Items are converted as shown here.

property on_change: callable#

Handler to invoke when the value of the selection is changed, either by the user or programmatically.

property on_select: callable#

Use on_change

Type:

DEPRECATED

property value#

The currently selected item.

Returns None if there are no items in the selection.

If an accessor was specified when the Selection was constructed, the value returned will be Row objects from the ListSource; to change the selection, a Row object from the ListSource must be provided.

If no accessor was specified when the Selection was constructed, the value returned will be the value stored as the value attribute on the Row object. When setting the value, the widget will search for the first Row object whose value attribute matches the provided value. In practice, this means that you can treat the selection as containing a list of literal values, rather than a ListSource containing Row objects.