Table

A widget for displaying columns of tabular data. Scroll bars will be provided if necessary.

../../../_images/table-cocoa.png

Usage

The simplest way to create a Table is to pass a list of tuples containing the items to display, and a list of column headings. The values in the tuples will then be mapped sequentially to the columns.

In this example, we will display a table of 2 columns, with 3 initial rows of data:

import toga

table = toga.Table(
    headings=["Name", "Age"],
    data=[
        ("Arthur Dent", 42),
        ("Ford Prefect", 37),
        ("Tricia McMillan", 38),
    ]
)

# Get the details of the first item in the data:
print(f"{table.data[0].name} is age {table.data[0].age}")

# Append new data to the table
table.data.append(("Zaphod Beeblebrox", 47))

You can also specify data for a Table using a list of dictionaries. This allows you to store data in the data source that won’t be displayed in the table. It also allows you to control the display order of columns independent of the storage of that data.

import toga

table = toga.Table(
    headings=["Name", "Age"],
    data=[
        {"name": "Arthur Dent", "age": 42, "planet": "Earth"},
        {"name": "Ford Prefect", "age": 37, "planet": "Betelgeuse Five"},
        {"name": "Tricia McMillan", "age": 38, "planet": "Earth"},
    ]
)

# Get the details of the first item in the data:
row = table.data[0]
print(f"{row.name}, who is age {row.age}, is from {row.planet}")

The attribute names used on each row (called “accessors”) are created automatically from the headings, by:

  1. Converting the heading to lower case

  2. Removing any character that can’t be used in a Python identifier

  3. Replacing all whitespace with _

  4. Prepending _ if the first character is a digit

If you want to use different attributes, you can override them by providing an accessors argument. In this example, the table will use “Name” as the visible header, but internally, the attribute “character” will be used:

import toga

table = toga.Table(
    headings=["Name", "Age"],
    accessors={"Name", 'character'},
    data=[
        {"character": "Arthur Dent", "age": 42, "planet": "Earth"},
        {"character": "Ford Prefect", "age": 37, "planet": "Betelgeuse Five"},
        {"name": "Tricia McMillan", "age": 38, "planet": "Earth"},
    ]
)

# Get the details of the first item in the data:
row = table.data[0]
print(f"{row.character}, who is age {row.age}, is from {row.planet}")

The value provided by an accessor is interpreted as follows:

  • If the value is a Widget, that widget will be displayed in the cell. Note that this is currently a beta API: see the Notes section.

  • If the value is a tuple, it must have two elements: an icon, and a second element which will be interpreted as one of the options below.

  • If the value is None, then missing_value will be displayed.

  • Any other value will be converted into a string. If an icon has not already been provided in a tuple, it can also be provided using the value’s icon attribute.

Icon values must either be an Icon, which will be displayed on the left of the cell, or None to display no icon.

Notes

  • Widgets in cells is a beta API which may change in future, and is currently only supported on macOS.

  • macOS does not support changing the font used to render table content.

  • On Winforms, icons are only supported in the first column. On Android, icons are not supported at all.

  • The Android implementation is not scalable beyond about 1,000 cells.

Reference

class toga.Table(headings=None, id=None, style=None, data=None, accessors=None, multiple_select=False, on_select=None, on_activate=None, missing_value='', on_double_click=None)

Bases: Widget

Create a new Table widget.

Parameters:
  • headings (Iterable[str] | None) –

    The column headings for the table. Headings can only contain one line; any text after a newline will be ignored.

    A value of None will produce a table without headings. However, if you do this, you must give a list of accessors.

  • id (str | None) – The ID for the widget.

  • style (StyleT | None) – A style object. If no style is provided, a default style will be applied to the widget.

  • data (SourceT | Iterable | None) – Initial data to be displayed in the table.

  • accessors (Iterable[str] | None) –

    Defines the attributes of the data source that will be used to populate each column. Must be either:

    • None to derive accessors from the headings, as described above; or

    • A list of the same size as headings, specifying the accessors for each heading. A value of None will fall back to the default generated accessor; or

    • A dictionary mapping headings to accessors. Any missing headings will fall back to the default generated accessor.

  • multiple_select (bool) – Does the table allow multiple selection?

  • on_select (toga.widgets.table.OnSelectHandler | None) – Initial on_select handler.

  • on_activate (toga.widgets.table.OnActivateHandler | None) – Initial on_activate handler.

  • missing_value (str) – The string that will be used to populate a cell when the value provided by its accessor is None, or the accessor isn’t defined.

  • on_double_click (None) – DEPRECATED; use on_activate.

property accessors: list[str]

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

add_column(heading, accessor=None)

DEPRECATED: use append_column()

Parameters:
  • heading (str)

  • accessor (str | None)

Return type:

None

append_column(heading, accessor=None)

Append a column to the end of the table.

Parameters:
  • heading (str) – The heading for the new column.

  • accessor (str | None) – The accessor to use on the data source when populating the table. If not specified, an accessor will be derived from the heading.

Return type:

None

property data: SourceT | ListSource

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.

property enabled: Literal[True]

Is the widget currently enabled? i.e., can the user interact with the widget? Table widgets cannot be disabled; this property will always return True; any attempt to modify it will be ignored.

focus()

No-op; Table cannot accept input focus.

Return type:

None

property headings: list[str] | None

The column headings for the table, or None if there are no headings (read-only)

insert_column(index, heading, accessor=None)

Insert an additional column into the table.

Parameters:
  • index (int | str) – The index at which to insert the column, or the accessor of the column before which the column should be inserted.

  • heading (str) – The heading for the new column. If the table doesn’t have headings, the value will be ignored.

  • accessor (str | None) – The accessor to use on the data source when populating the table. If not specified, an accessor will be derived from the heading. An accessor must be specified if the table doesn’t have headings.

Return type:

None

property missing_value: str

The value that will be used when a data row doesn’t provide a value for an attribute.

property multiple_select: bool

Does the table allow multiple rows to be selected?

property on_activate: OnActivateHandler

The callback function that is invoked when a row of the table is activated, usually with a double click or similar action.

property on_double_click: OnActivateHandler

DEPRECATED: Use on_activate

property on_select: OnSelectHandler

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

remove_column(column)

Remove a table column.

Parameters:

column (int | str) – The index of the column to remove, or the accessor of the column to remove.

Return type:

None

scroll_to_bottom()

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

Return type:

None

scroll_to_row(row)

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

Parameters:

row (int) – 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).

Return type:

None

scroll_to_top()

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

Return type:

None

property selection: list[Row] | Row | None

The current selection of the table.

If multiple selection is enabled, returns a list of Row objects from the data source matching the current selection. An empty list is returned if no rows are selected.

If multiple selection is not enabled, returns the selected Row object, or None if no row is currently selected.

protocol toga.widgets.table.OnSelectHandler

typing.Protocol.

Classes that implement this protocol must have the following methods / attributes:

__call__(widget, /, **kwargs)

A handler to invoke when the table is selected.

Parameters:
  • widget (Table) – The Table that was selected.

  • kwargs (Any) – Ensures compatibility with arguments added in future versions.

Return type:

object

protocol toga.widgets.table.OnActivateHandler

typing.Protocol.

Classes that implement this protocol must have the following methods / attributes:

__call__(widget, /, row, **kwargs)

A handler to invoke when the table is activated.

Parameters:
  • widget (Table) – The Table that was activated.

  • row (Any) – The Table Row that was activated.

  • kwargs (Any) – Ensures compatibility with arguments added in future versions.

Return type:

object