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

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
andvalue
for details on howaccessor
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 aListSource
, 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 thevalue
attribute on the Row object. When setting the value, the widget will search for the first Row object whosevalue
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.