DetailedList

macOSLinuxWindows ^βAndroidiOSWeb ^❌Textual ^❌

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.
• Using DetailedList on Android requires the AndroidX SwipeRefreshLayout widget in your project's Gradle dependencies. Ensure your app declares a dependency on androidx.swiperefreshlayout:swiperefreshlayout:1.1.0 or later.

Reference

toga.DetailedList

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,
    **kwargs,
)

Bases: Widget

Create a new DetailedList widget.

PARAMETER	DESCRIPTION
id	The ID for the widget. TYPE: str | None DEFAULT: None
style	A style object. If no style is provided, a default style will be applied to the widget. TYPE: StyleT | None DEFAULT: None
data	Initial data to be displayed in the list. TYPE: ListSourceT | Iterable | None DEFAULT: None
accessors	The accessors to use to retrieve the data for each item, in the form (title, subtitle, icon). TYPE: tuple[str, str, str] DEFAULT: ('title', 'subtitle', 'icon')
missing_value	The text that will be shown when a row doesn't provide a value for its title or subtitle. TYPE: str DEFAULT: ''
on_select	Initial on_select handler. TYPE: OnSelectHandler | None DEFAULT: None
primary_action	The name for the primary action. TYPE: str | None DEFAULT: 'Delete'
on_primary_action	Initial on_primary_action handler. TYPE: OnPrimaryActionHandler | None DEFAULT: None
secondary_action	The name for the secondary action. TYPE: str | None DEFAULT: 'Action'
on_secondary_action	Initial on_secondary_action handler. TYPE: OnSecondaryActionHandler | None DEFAULT: None
on_refresh	Initial on_refresh handler. TYPE: OnRefreshHandler | None DEFAULT: None
kwargs	Initial style properties. DEFAULT: {}

accessors property

accessors

The accessors used to populate the list (read-only)

data property writable

data

The data to display in the table.

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. Items are converted as shown here.

enabled property writable

enabled

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.

missing_value property

missing_value

The text that will be shown when a row doesn't provide a value for its title or subtitle.

on_primary_action property writable

on_primary_action

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.

on_refresh property writable

on_refresh

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.

on_secondary_action property writable

on_secondary_action

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.

on_select property writable

on_select

The callback function that is invoked when a row of the DetailedList is selected.

selection property

selection

The current selection of the table.

Returns the selected Row object, or None if no row is currently selected.

focus

focus()

No-op; DetailedList cannot accept input focus.

scroll_to_bottom

scroll_to_bottom()

Scroll the view so that the bottom of the list (last row) is visible.

scroll_to_row

scroll_to_row(row)

Scroll the view so that the specified row index is visible.

PARAMETER	DESCRIPTION
row	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). TYPE: int

scroll_to_top

scroll_to_top()

Scroll the view so that the top of the list (first row) is visible.

toga.widgets.detailedlist.OnPrimaryActionHandler

Bases: Protocol

__call__

__call__(widget, row, **kwargs)

A handler to invoke for the primary action.

PARAMETER	DESCRIPTION
widget	The DetailedList that was invoked. TYPE: DetailedList
row	The current row for the detailed list. TYPE: Any
kwargs	Ensures compatibility with arguments added in future versions. TYPE: Any DEFAULT: {}

toga.widgets.detailedlist.OnSecondaryActionHandler

Bases: Protocol

__call__

__call__(widget, row, **kwargs)

A handler to invoke for the secondary action.

PARAMETER	DESCRIPTION
widget	The DetailedList that was invoked. TYPE: DetailedList
row	The current row for the detailed list. TYPE: Any
kwargs	Ensures compatibility with arguments added in future versions. TYPE: Any DEFAULT: {}

toga.widgets.detailedlist.OnRefreshHandler

Bases: Protocol

__call__

__call__(widget, **kwargs)

A handler to invoke when the detailed list is refreshed.

PARAMETER	DESCRIPTION
widget	The DetailedList that was refreshed. TYPE: DetailedList
kwargs	Ensures compatibility with arguments added in future versions. TYPE: Any DEFAULT: {}

toga.widgets.detailedlist.OnSelectHandler

Bases: Protocol

__call__

__call__(widget, **kwargs)

A handler to invoke when the detailed list is selected.

PARAMETER	DESCRIPTION
widget	The DetailedList that was selected. TYPE: DetailedList
kwargs	Ensures compatibility with arguments added in future versions. TYPE: Any DEFAULT: {}