Table#

The table widget is a widget for displaying tabular data. It can be instantiated with the list of headings and then data rows can be added.

Usage#

import toga

table = toga.Table(['Heading 1', 'Heading 2'])

# Append to end of table
table.data.append('Value 1', 'Value 2')

# Insert to row 2
table.data.insert(2, 'Value 1', 'Value 2')

Reference#

class toga.widgets.table.Table(headings, id=None, style=None, data=None, accessors=None, multiple_select=False, on_select=None, on_double_click=None, missing_value=None, factory=None)#

A Table Widget allows the display of data in the form of columns and rows.

Parameters:

headings (list of str) – The list of headings for the table.
id (str) – An identifier for this widget.
data (list of tuple) – The data to be displayed on the table.
accessors – A list of methods, same length as headings, that describes how to extract the data value for each column from the row. (Optional)
style (Style) – An optional style object. If no style is provided` then a new one will be created for the widget.
on_select (callable) – A function to be invoked on selecting a row of the table.
on_double_click (callable) – A function to be invoked on double clicking a row of the table.
missing_value (str or None) – value for replacing a missing value in the data source. (Default: None). When ‘None’, a warning message will be shown.

Examples

>>> headings = ['Head 1', 'Head 2', 'Head 3']
>>> data = []
>>> table = Table(headings, data=data)

Data can be in several forms. A list of dictionaries, where the keys match the heading names:

>>> data = [{'head_1': 'value 1', 'head_2': 'value 2', 'head_3': 'value3'}),
>>>         {'head_1': 'value 1', 'head_2': 'value 2', 'head_3': 'value3'}]

A list of lists. These will be mapped to the headings in order:

>>> data = [('value 1', 'value 2', 'value3'),
>>>         ('value 1', 'value 2', 'value3')]

A list of values. This is only accepted if there is a single heading.

>>> data = ['item 1', 'item 2', 'item 3']

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.

add_column(heading, accessor=None)#

Add a new column to the table.

Parameters:

heading (string) – title of the column
accessor – accessor of this new column

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 table data in the form of list, tuple, 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 missing_value#

property multiple_select#: Does the table allow multiple rows to be selected?

property on_double_click#

The callback function that is invoked when a row of the table is double clicked. The provided callback function has to accept two arguments table (Table) and row (Row or None).

The value of a column of row can be accessed with row.accessor_name

Returns:: (callable) The callback function.

property on_select#

The callback function that is invoked when a row of the table is selected. The provided callback function has to accept two arguments table (Table) and row (Row or None).

The value of a column of row can be accessed with row.accessor_name

Returns:: (callable) The callback function.

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.

remove_column(column)#

Remove a table column.

Parameters:: column (int) – accessor or position (>0)

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 of the table.

A value of None indicates no selection. If the table allows multiple selection, returns a list of selected data nodes. Otherwise, returns a single data node.

The value of a column of the selection can be accessed with selection.accessor_name (for single selection) and with selection[x].accessor_name (for multiple 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.