DetailedList#
Not supported
Not supported
Usage#
The simplest way to create a DetailedList is to pass a list of dictionaries, with
each dictionary containing three keys: icon
, title
, and subtitle
:
import toga
table = toga.DetailedList(
data=[
{
"icon": toga.Icon("icons/arthur"),
"title": "Arthur Dent",
"subtitle": "Where's the tea?"
},
{
"icon": toga.Icon("icons/ford"),
"title": "Ford Prefect",
"subtitle": "Do you know where my towel is?"
},
{
"icon": toga.Icon("icons/tricia"),
"title": "Tricia McMillan",
"subtitle": "What planet are you from?"
},
]
)
If you want to customize the keys used in the dictionary, you can do this by
providing an accessors
argument to the DetailedList when it is constructed.
accessors
is a tuple containing the attributes that will be used to provide the
icon, title, and subtitle, respectively:
import toga
table = toga.DetailedList(
accessors=("picture", "name", "quote"),
data=[
{
"picture": toga.Icon("icons/arthur"),
"name": "Arthur Dent",
"quote": "Where's the tea?"
},
{
"picture": toga.Icon("icons/ford"),
"name": "Ford Prefect",
"quote": "Do you know where my towel is?"
},
{
"picture": toga.Icon("icons/tricia"),
"name": "Tricia McMillan",
"quote": "What planet are you from?"
},
]
)
If the value provided by the title or subtitle accessor is None
, or the accessor
isn’t defined, the missing_value
will be displayed. Any other value will be
converted into a string.
The icon accessor should return an Icon
. If it returns None
, or the
accessor isn’t defined, then no icon will be displayed, but space for the icon will
remain in the layout.
Items in a DetailedList can respond to a primary and secondary action. On platforms that use swipe interactions, the primary action will be associated with “swipe left”, and the secondary action will be associated with “swipe right”. Other platforms may implement the primary and secondary actions using a different UI interaction (e.g., a right-click context menu). The primary and secondary actions will only be enabled in the DetailedList UI if a handler has been provided.
By default, the primary and secondary action will be labeled as “Delete” and “Action”,
respectively. These names can be overridden by providing a primary_action
and
secondary_action
argument when constructing the DetailedList. Although the primary
action is labeled “Delete” by default, the DetailedList will not perform any data
deletion as part of the UI interaction. It is the responsibility of the application to
implement any data deletion behavior as part of the on_primary_action
handler.
The DetailedList as a whole can also respond to a refresh UI action. This is usually
implemented as a “pull down” action, such as you might see on a social media timeline.
This action will only be enabled in the UI if an on_refresh
handler has been
provided.
Notes#
The iOS Human Interface Guidelines differentiate between “Normal” and “Destructive” actions on a row. Toga will interpret any action with a name of “Delete” or “Remove” as destructive, and will render the action appropriately.
The WinForms implementation currently uses a column layout similar to
Table
, and does not support the primary, secondary or refresh actions.
Reference#
- class toga.DetailedList(id=None, style=None, data=None, accessors=('title', 'subtitle', 'icon'), missing_value='', primary_action='Delete', on_primary_action=None, secondary_action='Action', on_secondary_action=None, on_refresh=None, on_select=None, on_delete=None)#
Bases:
Widget
Create a new DetailedList 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.
data (Any) – Initial
data
to be displayed in the list.accessors (tuple[str, str, str]) – The accessors to use to retrieve the data for each item, in the form (title, subtitle, icon).
missing_value (str) – The text that will be shown when a row doesn’t provide a value for its title or subtitle.
on_select (callable) – Initial
on_select
handler.primary_action (str | None) – The name for the primary action.
on_primary_action (callable) – Initial
on_primary_action
handler.secondary_action (str | None) – The name for the secondary action.
on_secondary_action (callable) – Initial
on_secondary_action
handler.on_refresh (callable) – Initial
on_refresh
handler.on_delete (callable) – DEPRECATED; use
on_primary_action
.
- property data: ListSource#
The data to display in the table.
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. Items are converted as shown here.
- property enabled: bool#
Is the widget currently enabled? i.e., can the user interact with the widget? DetailedList widgets cannot be disabled; this property will always return True; any attempt to modify it will be ignored.
- focus()#
No-op; DetailedList cannot accept input focus
- property missing_value: str#
The text that will be shown when a row doesn’t provide a value for its title or subtitle.
- property on_delete#
DEPRECATED; Use
on_primary_action
- property on_primary_action: callable#
The handler to invoke when the user performs the primary action on a row of the DetailedList.
The primary action is “swipe left” on platforms that use swipe interactions; other platforms may manifest this action in other ways (e.g, a context menu).
If no
on_primary_action
handler is provided, the primary action will be disabled in the UI.
- property on_refresh: callable#
The callback function to invoke when the user performs a refresh action (usually “pull down”) on the DetailedList.
If no
on_refresh
handler is provided, the refresh UI action will be disabled.
- property on_secondary_action: callable#
The handler to invoke when the user performs the secondary action on a row of the DetailedList.
The secondary action is “swipe right” on platforms that use swipe interactions; other platforms may manifest this action in other ways (e.g, a context menu).
If no
on_secondary_action
handler is provided, the secondary action will be disabled in the UI.
- property on_select: callable#
The callback function that is invoked when a row of the DetailedList is selected.
- scroll_to_bottom()#
Scroll the view so that the bottom of the list (last row) is visible.
- scroll_to_row(row)#
Scroll the view so that the specified row index is visible.
- Parameters:
row (int) – The index of the row to make visible. Negative values refer to the nth last row (-1 is the last row, -2 second last, and so on).
- scroll_to_top()#
Scroll the view so that the top of the list (first row) is visible.