Column¶

Abstractions of tabular columns.

Usage¶

Columns are abstractions that allow you to specify how the data in a Table or Tree widget should be displayed. Each column object is responsible for taking a row from the data source and providing text, icon and other display elements suitable for the Table and Tree widgets to use.

The protocol, ColumnT, describes what custom Column implementations need to provide so that they can be used by the widget. Toga provides the Column and AccessorColumn as implementations of the ColumnT protocol. The Column class is a base class suitable for custom sub-classing, while the AccessorColumn is used by default in the Table and Tree widgets.

Column objects are usually immutable, and can be shared between widgets freely if desired.

Accessor columns¶

AccessorColumn objects are designed to work with the ListSource and TreeSource objects: each AccessorColumn holds the heading text and an attribute name, or "accessor", that is used to get values from each row of the source to use in the column.

The Table and Tree widgets will automatically create AccessorColumn objects from column headings, but they can also be created manually if desired. Each column object expects a heading and an accessor as arguments, but will automatically generate an accessor from the heading if needed.

table = Table(
    columns=[
        AccessorColumn("Title", "title"),
        AccessorColumn("Year"),
        "Rating",  # equivalent to AccessorColumn("Rating")
    ]
)

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

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.

Custom columns¶

You can define your own subclasses that can override the way that text and icons are computed to provide custom formatting of text. Any object which implements the ColumnT protocol can be used. This protocol requires:

a read-only heading property that is the column heding text or None for no heading text.;
a value method that takes a row object and gives the value for the column in that row.
a text method that takes a row object and an optional default value and gives the text for the column to display in that row, or None if no text is to be displayed.
an icon method that takes a row object and gives the icon for the column to display in that row, or None if no icon is to be displayed.
a widget method that takes a row object and gives the widget for the column to use in that row, or None if no widget is to be used (this is experimental and is only supported on macOS at present).

For example, we could subclass AccessorColumn to make column that takes a value which is a list of strings and formats it as a comma-separated list as follows:

class ListStrColumn(AccessorColumn):

    def text(self, row, default=None):
        value = self.value(row)
        if value is None:
            return default
        else:
            return ", ".join(value)

table = Table(
    columns=[
        "Title",
        ListStrColumn("Genre"),
    ]
)

so a row providing the value ["Drama", "Action"] would be displayed in the table cell as "Drama, Action".

Custom columns can even override the default way of looking up values to allow such things as combining values from multiple attributes, looking up values by index rather than attribute, or using a method or function on the row to get the display values. The Column class provides a convenient minimal base class for implementing custom columns.

class TotalCostColumn(Column):

    def value(self, row):
        return row.item_cost * row.quantity

    def text(self, row, default=None):
        value = self.value(row)
        return f"${value:.2d}"

table = Table(
    columns=[
        "Product",
        "Quantity",
        "Item Cost",
        TotalCostColumn("Total Cost"),
    ]
)

Reference¶

toga.sources.ColumnT ¶

Bases: Protocol, Generic[Value]

Protocol that Column types must adhere to.

heading `abstractmethod` `property` ¶

heading: str

The heading text for this column.

icon `abstractmethod` ¶

icon(row: Any) -> Icon | None

Get the icon to display for the row in this column.

PARAMETER	DESCRIPTION
`row`	A row object from the underlying Source. TYPE: `Any`

RETURNS	DESCRIPTION
`Icon \| None`	The icon to display, or None if no Icon.

text `abstractmethod` ¶

text(row: Any, default: str | None = None) -> str | None

Get the text to display for the row in this column.

PARAMETER	DESCRIPTION
`row`	A row object from the underlying Source. TYPE: `Any`
`default`	A default value if the text cannot be determined. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`str \| None`	The text to display, or None if no Text.

value `abstractmethod` ¶

value(row: Any) -> Value | None

Get a value from the row of a Source.

PARAMETER	DESCRIPTION
`row`	A row object from the underlying Source. TYPE: `Any`

RETURNS	DESCRIPTION
`Value \| None`	The value associated with this column, or None if no value.

widget ¶

widget(row: Row[Value]) -> Widget | None

Get a widget from the Row or Node of a ListSource or TreeSource.

If the value is a widget, it is returned, otherwise None is returned

PARAMETER	DESCRIPTION
`row`	A row object from the underlying Source. TYPE: `Row[Value]`

RETURNS	DESCRIPTION
`Widget \| None`	The Widget to use, or None if no Widget.

toga.sources.Column ¶

Column(heading: str | None)

Bases: ColumnT[Value], Generic[Value]

An implementation the ColumnT protocol for easy subclassing.

This abstract base class provides default implementations of the ColumnT: the value, icon and widget methods all return None, and the text method returns the str() of the value, or the default string if the value is None. The constructor takes the heading text and makes it available as a property.

Unmodified, the column will display the default text value in each cell.

Subclasses should override the value method at a minimum, and other methods as needed.

heading `property` ¶

heading: str

The heading text for this column.

icon ¶

icon(row: Any) -> Icon | None

Get the icon to display for the row in this column.

The default

PARAMETER	DESCRIPTION
`row`	A row object from the underlying Source. TYPE: `Any`

RETURNS	DESCRIPTION
`Icon \| None`	The icon to display, or None if no Icon.

text ¶

text(row: Any, default: str | None = None) -> str | None

Get the text to display for the row in this column.

This returns the str() of the value unless the value is None, in which case it returns the default.

PARAMETER	DESCRIPTION
`row`	A row object from the underlying Source. TYPE: `Any`
`default`	A default value if the text cannot be determined. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`str \| None`	The text to display, or None if no Text.

value ¶

value(row: Any) -> Value | None

Get a value from the row of a Source.

The base implementation always returns None.

PARAMETER	DESCRIPTION
`row`	A row object from the underlying Source. TYPE: `Any`

RETURNS	DESCRIPTION
`Value \| None`	The value associated with this column, or None if no value.

widget ¶

widget(row: Any) -> Widget | None

Get a widget from the Row or Node of a ListSource or TreeSource.

If the value is a widget, it is returned, otherwise None is returned

PARAMETER	DESCRIPTION
`row`	A row object from the underlying Source. TYPE: `Any`

RETURNS	DESCRIPTION
`Widget \| None`	The Widget to use, or None if no Widget.

toga.sources.AccessorColumn ¶

AccessorColumn(heading: str | None = None, accessor: str | None = None)

Bases: Column[Value], Generic[Value]

This is a column which implements accessor semantics.

The value of a cell in an AccessorColumn is found by getting the value of the attribute on the row whose name matches the accessor. This value can be:

This requires at least one of the heading and the accessor to be supplied to the init method. If given just a heading, it generates the accessor from the heading.

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

columns_from_headings_and_accessors `classmethod` ¶

columns_from_headings_and_accessors(
    headings: Iterable[str] | None = None,
    accessors: Iterable[str] | None = None,
) -> list[ColumnT]

Get a list of columns from lists of headings and accessors.

PARAMETER	DESCRIPTION
`headings`	A list of heading titles, or None if no headings. TYPE: `Iterable[str] \| None` DEFAULT: `None`
`accessors`	A list of accessor names, or None if accessors are to be generated from the headings automatically. TYPE: `Iterable[str] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[ColumnT]`	A list of AccessorColumns matching the order of headers and accessors.

RAISES	DESCRIPTION
`ValueError`	If neither headings nor accessor liss are supplied.

icon ¶

icon(row: Row[Value]) -> Icon | None

Get text from the Row or Node of a ListSource or TreeSource.

If the value is a tuple, it must be of length 2, and the first item is assumed to be an Icon. A tuple of any other length will raise a ValueError. Otherwise if the item has an icon attribute, that is assumed to be the icon.

PARAMETER	DESCRIPTION
`row`	A row object from the underlying Source. TYPE: `Row[Value]`

RETURNS	DESCRIPTION
`Icon \| None`	The Icon to associated with this column's accessor, or None if no Icon.

text ¶

text(row: Row[Value], default: str | None = None) -> str | None

Get text from the Row or Node of a ListSource or TreeSource.

If the value is a tuple, it must be of length two; the second item is assumed to be text.

If the value is None, and a default is supplied, the default is returned.

All other values are converted to a string by calling str().

PARAMETER	DESCRIPTION
`row`	A row object from the underlying Source. TYPE: `Row[Value]`
`default`	A default value if the resulting value is otherwise None. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`str \| None`	The text to associated with this column's accessor, or None if no text.

value ¶

value(row: Row[Value]) -> Value | None

Get a value from the Row or Node of a ListSource or TreeSource.

PARAMETER	DESCRIPTION
`row`	A Row object from the underlying Source. TYPE: `Row[Value]`

RETURNS	DESCRIPTION
`Value \| None`	The value associated with this column's accessor, or None if no value.

widget ¶

widget(row: Row[Value]) -> Widget | None

Get a widget from the Row or Node of a ListSource or TreeSource.

If the value is a widget, it is returned, otherwise None is returned

PARAMETER	DESCRIPTION
`row`	A row object from the underlying Source. TYPE: `Row[Value]`

RETURNS	DESCRIPTION
`Widget \| None`	The Widget to associated with this column's accessor, or None if no Widget.

Column¶

Usage¶

Accessor columns¶

Custom columns¶

Reference¶

toga.sources.ColumnT ¶

heading abstractmethod property ¶

icon abstractmethod ¶

text abstractmethod ¶

value abstractmethod ¶

widget ¶

toga.sources.Column ¶

heading property ¶

icon ¶

text ¶

value ¶

widget ¶

toga.sources.AccessorColumn ¶

columns_from_headings_and_accessors classmethod ¶

icon ¶

text ¶

value ¶

widget ¶

heading `abstractmethod` `property` ¶

icon `abstractmethod` ¶

text `abstractmethod` ¶

value `abstractmethod` ¶

heading `property` ¶

columns_from_headings_and_accessors `classmethod` ¶