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.
factory (module) – A python module that is capable to return a implementation of this class with the same name. (optional & normally not needed)

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 nodes as children of this one. 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.

Parameters: children – Nodes to add as children of this node.
Raises: ValueError – If this node is a leaf, and cannot have children.

property app¶

The App to which this widget belongs. On setting the app we also iterate over all children of this widget and set them to the same app.

Returns: The toga.App to which this widget belongs.
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¶

focus()¶

property id¶

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

Returns: The widgets identifier as a str.

insert(index, child)¶

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

Parameters

index – Position of child node.
child – A node to insert as a child of this node.

Raises

ValueError – If this node is a leaf, and cannot have children.

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 child nodes of this node. This does nothing if a given node is not a child of this node.

Parameters: children – Child nodes to remove.
Raises: ValueError – If this node is a leaf, and cannot have children.

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 window¶

The Window to which this widget belongs. On setting the window, we automatically update all children of this widget to belong to the same window.

Returns: The toga.Window to which the widget belongs.