DetailedList#

Usage#

Reference#

class toga.widgets.detailedlist.DetailedList(id=None, data=None, on_delete=None, on_refresh=None, on_select=None, style=None, factory=None)#

A widget to hold data in a list form. Rows are selectable and can be deleted. A updated function can be invoked by pulling the list down.

Parameters:

id (str) – An identifier for this widget.
data (list of dict) – List of dictionaries with required ‘icon’, ‘title’, and ‘subtitle’ keys as well as optional custom keys to store additional info like ‘pk’ for a database primary key (think django ORM)
on_delete (callable) – Function that is invoked on row deletion.
on_refresh (callable) – Function that is invoked on user initialised refresh.
on_select (callable) – Function that is invoked on row selection.
style (Style) – An optional style object. If no style is provided then a new one will be created for the widget.

Examples

>>> import toga
>>> def selection_handler(widget, row):
>>>     print('Row {} of widget {} was selected.'.format(row, widget))
>>>
>>> dlist = toga.DetailedList(
...     data=[
...         {
...             'icon': '',
...             'title': 'John Doe',
...             'subtitle': 'Employee of the Month',
...             'pk': 100
...          }
...      ],
...      on_select=selection_handler
... )

MIN_HEIGHT = 100#

MIN_WIDTH = 100#

add(*children)#

Add the provided widgets as children of this widget.

If a node already has a different parent, it will be moved over. This does nothing if a node already is a child of this node.

Raises ValueError if this widget cannot have children.

Parameters:: children – The widgets to add as children of this widget.

property app#

The App to which this widget belongs.

When setting the app for a widget, all children of this widget will be recursively assigned to the same app.

Raises ValueError if the widget is already associated with another app.

property can_have_children#

Determine if the node can have children.

This does not resolve whether there actually are any children; it only confirms whether children are theoretically allowed.

property children#

The children of this node. This always returns a list, even if the node is a leaf and cannot have children.

Returns:: A list of the children for this widget.

property data#

The data source of the widget. It accepts data in the form of list of dict or ListSource

Returns:: Returns a (ListSource).

property enabled#: Is the widget currently enabled? i.e., can the user interact with the widget?

focus()#: Set this widget to have the current input focus.

property id#: The node identifier. This id can be used to target styling directives.

insert(index, child)#

Insert a widget as a child of this widget.

If the node already has a parent, ownership of the widget will be transferred.

Raises ValueError if this node cannot have children.

Parameters:

index – The position in the list of children where the new widget should be added.
child – The child to insert as a child of this node.

property on_delete#

The function invoked on row deletion. The delete handler must accept two arguments. The first is a ref. to the widget and the second the row that is about to be deleted.

Examples

>>> def delete_handler(widget, row):
>>>     print('row ', row, 'is going to be deleted from widget', widget)

Returns:: The function that is invoked when deleting a row.

property on_refresh#: Returns: The function to be invoked on user initialised refresh.

property on_select#

The handler function must accept two arguments, widget and row.

Returns:: The function to be invoked on selecting a row.

property parent#

The parent of this node.

Returns:: The parent of this node. Returns None if this node is the root node.

refresh()#: Refresh the layout and appearance of the tree this node is contained in.

refresh_sublayouts()#

remove(*children)#

Remove the provided widgets as children of this node.

This does nothing if a given node is not a child of this node.

Raises ValueError if this node is a leaf, and cannot have children.

Parameters:: children – The child nodes to remove.

property root#

The root of the tree containing this node.

Returns:: The root node. Returns self if this node is the root node.

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

property selection#

The current selection.

A value of None indicates no selection.

property tab_index#: The position of the widget in the focus chain for the window.

property window#

The window to which this widget belongs.

When setting the window for a widget, all children of this widget will be recursively assigned to the same window.