macOS GTK+ Windows iOS Android Django
y y y      

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.



import toga

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

# Append to end of table'Value 1', 'Value 2')

# Insert to row 2, 'Value 1', 'Value 2')


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

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

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


>>> 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’]


Add a node as a child of this one. :param child: A node to add as a child to this node.

Raises:ValueError – If this node is a leaf, and cannot have children.
add_column(heading, accessor=None)

Add a new column to the table

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

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.

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.


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.

The data source of the widget. It accepts table data in the form of list, tuple, or ListSource

Returns:Returns a (ListSource).

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

Returns:The widgets identifier as a str.

Does the table allow multiple rows to be selected?


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

Returns:(callable) The callback function.

The parent of this node.

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

Refresh the layout and appearance of the tree this node is contained in.


Remove a table column.

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

The root of the tree containing this node.

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

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


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 the view so that the top of the list (first row) is visible


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