Table¶

Displays columns of tabular data.

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(
    columns=["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(
    columns=["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 strings for the headings are translated into AccessorColumn objects which tell the Table how to get the values to display in the column by looking up attributes on the rows.

The accessors are created automatically from the headings, by:

Converting the heading to lower case
Removing any character that can't be used in a Python identifier
Replacing all whitespace with _
Prepending _ if the first character is a digit

If you want to use attributes which don't match the headings, you can override them by providing your own AccessorColumn objects. 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(
    columns=[
        AccessorColumn("Name", "character"),
        "Age",
    ],
    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. A tuple of any other length will raise an error.
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.

So for example:

import toga

green_icon = toga.Icon("icons/green")

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

will display the green icon in the first column of the first row and no other icons.

The AccessorColumn class is the only column class provided in core Toga, but you can define your own custom columns that implement the ColumnT protocol and there is a Column abstract base class that serves as a useful starting point. These columns can do things like giving you better control over getting icons and text, formatting in a particular way, combining multiple attributes to produce the value to display, or even accessing data via indexes rather than attribute lookup.

Sometimes when supplying rows using lists or other sequences, the order of the columns may not match the order of the data in the rows. In this case, the easiest approach is to create a [ListSource][toga.sources.ListSource] that maps the rows to the column accessors:

import toga

table = toga.Table(
    columns=["Age", "Name"],
    data=toga.sources.ListSource(
        accessors=["name", "planet", "age"],
        [
            ("Arthur Dent", "Earth", 42),
            ("Ford Prefect", "Betelgeuse Five", 37),
            ("Tricia McMillan", "Earth", 38),
        ],
    )
)

For more complex data you can define your own custom data sources.

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.
Icons in tables are not supported on Android, and the implementation is not scalable beyond about 1,000 cells.

Reference¶

toga.Table ¶

Table(
    columns: Iterable[str | ColumnT[Value]] | None = None,
    id: str | None = None,
    style: StyleT | None = None,
    data: ListSourceT | Iterable | None = None,
    accessors: Iterable[str] | None = None,
    multiple_select: bool = False,
    on_select: OnSelectHandler | None = None,
    on_activate: OnActivateHandler | None = None,
    missing_value: str = "",
    *,
    show_headings: bool | None = None,
    headings: Iterable[str] | None = None,
    **kwargs,
)

Bases: Widget, Generic[Value]

Create a new Table widget.

PARAMETER	DESCRIPTION
`columns`	The column objects or heading strings for the table. Column objects must implement the `ColumnT` protocol. Heading strings will be converted to `AccessorColumn` instances automatically. Heading strings can only contain one line; any text after a newline will be ignored. DEPRECATED: A value of `None` will produce a table without headings. Rather than specifying a value of `None` for `columns`, you should use `show_headings=False`. However, if you do specify `None` for columns, you must provide a list of accessors. TYPE: `Iterable[str \| ColumnT[Value]] \| None` DEFAULT: `None`
`id`	The ID for the widget. TYPE: `str \| None` DEFAULT: `None`
`style`	A style object. If no style is provided, a default style will be applied to the widget. TYPE: `StyleT \| None` DEFAULT: `None`
`data`	Initial `data` to be displayed in the table. This can be an object which implements the `ListSourceT` protocol, an Iterable object, or `None`. An Iterable object will be automatically converted to a `ListSource`. TYPE: `ListSourceT \| Iterable \| None` DEFAULT: `None`
`accessors`	DEPRECATED To specify a non-default accessor name for a column, specify columns using 'AccessorColumn' instances. To specify the ordering of items in table data, specify `data` using a `ListSource` with an `accessors` argument. When table data is provided as an iterable, the `ListSource` created by the Table will try to derive its accessors from the column definitions. However, when the table data has entries that will not be displayed in the table, or when the autogenerated attribute for a column doesn't produce the required value, it may be necessary to override the list of accessors used to populate the table. The `accessors` argument must be either: A list, at least as long as `columns`, specifying the accessors for each column plus any additional accessors. When the column is given by a heading string then the heading and accessor will be used to create an `AccessorColumn`; or A dictionary mapping heading strings to accessors. When the column is given by a heading string then the heading and accessor will be used to create an `AccessorColumn`. Any missing headings will fall back to the default generated accessor. The default value of `None` results in accessors being derived from the columns. If no columns or heading strings were provided, an 'AccessorColumn' instance will be created for each accessor and a table with no headings will be created. The accessors are also passed to any `ListSource` created by the Table to tell the source how to map lists and tuples to accessor values. This ordering does not change even when columns are added or removed. TYPE: `Iterable[str] \| None` DEFAULT: `None`
`multiple_select`	Does the table allow multiple selection? TYPE: `bool` DEFAULT: `False`
`on_select`	Initial `on_select` handler. TYPE: `OnSelectHandler \| None` DEFAULT: `None`
`on_activate`	Initial `on_activate` handler. TYPE: `OnActivateHandler \| None` DEFAULT: `None`
`missing_value`	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. TYPE: `str` DEFAULT: `''`
`show_headings`	Whether or not to show headings at the top of the table. For backwards compatibility, this is set to False if no columns or headings are provided. TYPE: `bool \| None` DEFAULT: `None`
`headings`	DEPRECATED A list of heading strings for columns. TYPE: `Iterable[str] \| None` DEFAULT: `None`
`kwargs`	Initial style properties. DEFAULT: `{}`

accessors `property` ¶

accessors: list[str | None]

The list of column accessors (read-only) [Deprecated]

columns `property` ¶

columns: list[ColumnT[Value]]

The columns for the table (read-only)

data `property` `writable` ¶

data: ListSourceT | 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.

In the last two cases, when creating a new or empty ListSource, the accessors of the old source are copied to the new one or, if that is impossible, the accessors of the columns are used.

enabled `property` `writable` ¶

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.

headings `property` ¶

headings: list[str] | None

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

missing_value `property` ¶

missing_value: str

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

multiple_select `property` ¶

multiple_select: bool

Does the table allow multiple rows to be selected?

on_activate `property` `writable` ¶

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.

on_select `property` `writable` ¶

on_select: OnSelectHandler

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

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

show_headings `property` ¶

show_headings: bool

Whether or not the table shows a header at the top (read-only)

append_column ¶

append_column(
    column: ColumnT[Value] | str | None = None,
    accessor: str | None = None,
    *,
    heading: str | None = None,
) -> None

Append a column to the end of the table.

PARAMETER DESCRIPTION

column

The new column, or a heading string for the new column.

TYPE: ColumnT[Value] | str | None DEFAULT: None

accessor

DEPRECATED To specify a non-default accessor for a column, use an AccessorColumn. To specify the ordering of accessors use a ListSource with an accessors argument for the data.

An accessor to use if a heading string is supplied rather than a column object. If not specified, an accessor will be derived from the heading. An accessor must be specified if the column is None.

TYPE: str | None DEFAULT: None

insert_column ¶

insert_column(
    index: int | ColumnT[Value] | str,
    column: ColumnT[Value] | str | None = None,
    accessor: str | None = None,
    *,
    heading: str | None = None,
) -> None

Insert an additional column into the table.

PARAMETER	DESCRIPTION
`index`	The index at which to insert the column, or the column (or its accessor DEPRECATED) before which the new column should be inserted. TYPE: `int \| ColumnT[Value] \| str`
`column`	The new column, or a heading string for the new column. TYPE: `ColumnT[Value] \| str \| None` DEFAULT: `None`
`accessor`	DEPRECATED To specify a non-default accessor for a column, use an `AccessorColumn`. To specify the ordering of accessors use a `ListSource` with an `accessors` argument for the data. An accessor to use if a heading string is supplied rather than a column object. If not specified, an accessor will be derived from the heading. An accessor must be specified if the column is None. TYPE: `str \| None` DEFAULT: `None`

remove_column ¶

remove_column(column: int | ColumnT[Value] | str) -> None

Remove a table column.

PARAMETER	DESCRIPTION
`column`	The index of the column to remove, or the column (or its accessor [Deprecated]) to remove. TYPE: `int \| ColumnT[Value] \| str`

scroll_to_bottom ¶

scroll_to_bottom() -> None

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

scroll_to_row ¶

scroll_to_row(row: int) -> None

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

PARAMETER	DESCRIPTION
`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). TYPE: `int`

scroll_to_top ¶

scroll_to_top() -> None

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

toga.widgets.table.OnSelectHandler ¶

Bases: Protocol

call ¶

__call__(widget: Table, **kwargs: Any) -> None

A handler to invoke when the table is selected.

PARAMETER	DESCRIPTION
`widget`	The Table that was selected. TYPE: `Table`
`kwargs`	Ensures compatibility with arguments added in future versions. TYPE: `Any` DEFAULT: `{}`

toga.widgets.table.OnActivateHandler ¶

Bases: Protocol

call ¶

__call__(widget: Table, row: Any, **kwargs: Any) -> None

A handler to invoke when the table is activated.

PARAMETER	DESCRIPTION
`widget`	The Table that was activated. TYPE: `Table`
`row`	The Table Row that was activated. TYPE: `Any`
`kwargs`	Ensures compatibility with arguments added in future versions. TYPE: `Any` DEFAULT: `{}`

Table¶

Usage¶

Notes¶

Reference¶

toga.Table ¶

accessors property ¶

columns property ¶

data property writable ¶

enabled property writable ¶

headings property ¶

missing_value property ¶

multiple_select property ¶

on_activate property writable ¶

on_select property writable ¶

selection property ¶

show_headings property ¶

append_column ¶

insert_column ¶

remove_column ¶

scroll_to_bottom ¶

scroll_to_row ¶

scroll_to_top ¶

toga.widgets.table.OnSelectHandler ¶

__call__ ¶

toga.widgets.table.OnActivateHandler ¶

__call__ ¶

accessors `property` ¶

columns `property` ¶

data `property` `writable` ¶

enabled `property` `writable` ¶

headings `property` ¶

missing_value `property` ¶

multiple_select `property` ¶

on_activate `property` `writable` ¶

on_select `property` `writable` ¶

selection `property` ¶

show_headings `property` ¶

call ¶

call ¶