Tree

Usage

The simplest way to create a Tree is to pass a dictionary and a list of column headings. Each key in the dictionary can be either a tuple, whose contents will be mapped sequentially to the columns of a node, or a single object, which will be mapped to the first column. And each value in the dictionary can be either another dictionary containing the children of that node, or None if there are no children.

In this example, we will display a tree with 2 columns. The tree will have 2 root nodes; the first root node will have 1 child node; the second root node will have 2 children. The root nodes will only populate the "name" column; the other column will be blank:

import toga

tree = toga.Tree(
    columns=["Name", "Age"],
    data={
        "Earth": {
           ("Arthur Dent", 42): None,
        },
        "Betelgeuse Five": {
           ("Ford Prefect", 37): None,
           ("Zaphod Beeblebrox", 47): None,
        },
    }
)

# Get the details of the first child of the second root node:
print(f"{tree.data[1][0].name} is age {tree.data[1][0].age}")

# Append new data to the first root node in the tree
tree.data[0].append(("Tricia McMillan", 38))

You can also specify data for a Tree using a list of 2-tuples, with dictionaries providing data values. This allows you to store data in the data source that won't be displayed in the tree. It also allows you to control the display order of columns independent of the storage of that data.

import toga

tree = toga.Tree(
    columns=["Name", "Age"],
    data=[
        (
            {"name": "Earth"},
            [({"name": "Arthur Dent", "age": 42, "status": "Anxious"}, None)]
        ),
        (
            {"name": "Betelgeuse Five"},
            [
                ({"name": "Ford Prefect", "age": 37, "status": "Hoopy"}, None),
                ({"name": "Zaphod Beeblebrox", "age": 47, "status": "Oblivious"}, None),
            ]
        ),
    ]
)

# Get the details of the first child of the second root node:
node = tree.data[1][0]
print(f"{node.name}, who is age {node.age}, is {node.status}")

The strings for the headings are translated into AccessorColumn objects which tell the Tree how to get the values to display in the column by looking up attributes on the nodes.

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

tree = toga.Tree(
    columns=[AccessorColumn("Name", 'character'), "Age"],
    data=[
        (
            {"character": "Earth"},
            [({"character": "Arthur Dent", "age": 42, "status": "Anxious"}, None)]
        ),
        (
            {"character": "Betelgeuse Five"},
            [
                ({"character": "Ford Prefect", "age": 37, "status": "Hoopy"}, None),
                ({"character": "Zaphod Beeblebrox", "age": 47, "status": "Oblivious"}, None),
            ]
        ),
    ]
)

# Get the details of the first child of the second root node:
node = tree.data[1][0]
print(f"{node.character}, who is age {node.age}, is {node.status}")

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")

tree = toga.Tree(
    columns=["Name", "Age"],
    data=[
        (
            {"name": (green_icon, "Earth")},
            [({"name": "Arthur Dent", "age": 42, "status": "Anxious"}, None)]
        ),
        (
            {"name": (None, "Betelgeuse Five")},
            [
                ({"name": "Ford Prefect", "age": 37, "status": "Hoopy"}, None),
                ({"name": "Zaphod Beeblebrox", "age": 47, "status": "Oblivious"}, None),
            ]
        ),
    ]
)

will display a green icon next to "Earth", and nothing next to "Betelgeuse Five".

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 [TreeSource][toga.sources.TreeSource] that maps the rows to the column accessors:

import toga

tree = toga.Tree(
    columns=["Age", "Name"],
    data=TreeSource(
        accessors=["name", "status", "age"]
        data={
            "Earth": {
                ("Arthur Dent", "Anxious", 42): None,
            },
            "Betelgeuse Five": {
                ("Ford Prefect", "Hoopy", 37): None,
                ("Zaphod Beeblebrox", "Oblivious", 47): None,
            },
        }
    )
)

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.
• On macOS, you cannot change the font used in a Tree.

Reference

Bases: Widget

Source code in core/src/toga/widgets/tree.py

class Tree(Widget):
    def __init__(
        self,
        columns: Iterable[str | ColumnT[Value]] | None = None,
        id: str | None = None,
        style: Pack | None = None,
        data: TreeSourceT | object | None = None,
        accessors: Iterable[str] | None = None,
        multiple_select: bool = False,
        on_select: toga.widgets.tree.OnSelectHandler | None = None,
        on_activate: toga.widgets.tree.OnActivateHandler | None = None,
        missing_value: str = "",
        *,
        show_headings: bool | None = None,
        headings: Iterable[str] | None = None,
        **kwargs,
    ):
        """Create a new Tree widget.

        :param columns: The column objects or heading strings for the tree. Column
            objects must implement the ['ColumnT'][toga.sources.ColumnT] protocol.
            Heading strings will be converted to
            ['AccessorColumn'][toga.sources.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.
        :param id: The ID for the widget.
        :param style: A style object. If no style is provided, a default style will be
            applied to the widget.
        :param data: Initial [`data`][toga.Tree.data] to be displayed in the tree. This
            can be an object which implements the `TreeSourceT` protocol, an Iterable
            object, or [`None`][]. An Iterable object will be automatically converted to
            a [`TreeSource`][toga.sources.TreeSource].
        :param accessors: **DEPRECATED** To specify a non-default accessor name for a
            column, specify columns using
            ['AccessorColumn'][toga.sources.AccessorColumn] instances. To specify the
            ordering of items in table data, specify `data` using a
            [`ListSource`][toga.sources.ListSource] with an `accessors` argument.

            When tree data is provided as an iterable, the
            [`TreeSource`][toga.sources.TreeSource] created by the Tree will try to
            derive its accessors from the column definitions. However, when the tree
            data has entries that will not be displayed in the tree, 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 and any additional accessors needed.  When the column is given by a
              heading string then the heading and accessor will be used to create an
              [`AccessorColumn`][toga.sources.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`][toga.sources.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'][toga.sources.AccessorColumn] instance will be created for
            each accessor and a tree with no headings will be created.

            The accessors are also passed to any [`TreeSource`][toga.sources.TreeSource]
            created by the Tree 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.
        :param multiple_select: Does the tree allow multiple selection?
        :param on_select: Initial [`on_select`][toga.Tree.on_select] handler.
        :param on_activate: Initial [`on_activate`][toga.Tree.on_activate] handler.
        :param 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.
        :param show_headings: Whether or not to show headings at the top of the tree.
            For backwards compatibility, this is set to False if no columns or headings
            are provided.
        :param headings: **DEPRECATED** A list of heading strings for columns.
        :param kwargs: Initial style properties.
        """
        self._data: TreeSourceT | TreeSource

        self._missing_value = missing_value if missing_value else ""
        self._multiple_select = multiple_select

        ######################################################################
        # 2026-02: Backwards compatibility for <= 0.5.3
        ######################################################################
        if headings is not None:
            if columns is None:
                warnings.warn(
                    "The 'headings' keyword argument is deprecated; "
                    "use 'columns' instead.",
                    DeprecationWarning,
                    stacklevel=2,
                )
                columns = headings
            else:
                raise TypeError("Can't specify columns and headings at the same time.")
        if accessors is not None:
            warnings.warn(
                "The `accessors` argument is deprecated. To specify a non-default "
                "accessor for a column, use an `AccessorColumn`. To specify the "
                "ordering of accessors use a `TreeSource` with an `accessors` "
                "argument for the data.",
                DeprecationWarning,
                stacklevel=2,
            )

        if columns is None:
            if accessors is None:
                raise ValueError(
                    "Cannot create a tree without either columns or accessors."
                )
            columns = AccessorColumn.columns_from_headings_and_accessors(
                None, accessors
            )
            if show_headings is None:
                # Don't show headings if only given accessors.
                show_headings = False
        elif isinstance(accessors, Mapping):
            columns = [
                AccessorColumn(column, accessors.get(column, None))
                if isinstance(column, str)
                else column
                for column in columns
            ]
        elif accessors is not None:
            columns = [
                AccessorColumn(column, accessor) if isinstance(column, str) else column
                for column, accessor in zip(columns, accessors, strict=False)
            ]
        ######################################################################
        # End backwards compatibility
        ######################################################################
        else:
            columns = [
                AccessorColumn(column) if isinstance(column, str) else column
                for column in columns
            ]

        ######################################################################
        # 2026-02: Backwards compatibility for <= 0.5.3
        #
        # When removing backwards compatibility for accessors, show_headings can
        # default to True, and this logic can be removed.
        ######################################################################
        self._show_headings = show_headings if show_headings is not None else True
        ######################################################################
        # End backwards compatibility
        ######################################################################

        self._columns: list[ColumnT] = columns

        # Prime some properties that need to exist before the tree is created.
        self.on_select = None
        self.on_activate = None

        super().__init__(id, style, **kwargs)

        if not isinstance(data, Source):
            if accessors is None or isinstance(accessors, Mapping):
                # Use the column's accessors
                accessor_order = [
                    column.accessor
                    for column in columns
                    if getattr(column, "accessor", None) is not None
                ]
            else:
                # use the accessors parameter
                accessor_order = list(accessors)

            if data is None:
                data = TreeSource(accessors=accessor_order, data=[])
            else:
                data = TreeSource(accessors=accessor_order, data=data)

        self.data = data

        self.on_select = on_select
        self.on_activate = on_activate

    def _create(self):
        return self.factory.Tree(interface=self)

    @property
    def enabled(self) -> Literal[True]:
        """Is the widget currently enabled? i.e., can the user interact with the widget?
        Tree widgets cannot be disabled; this property will always return True; any
        attempt to modify it will be ignored.
        """
        return True

    @enabled.setter
    def enabled(self, value: object) -> None:
        pass

    @property
    def data(self) -> TreeSourceT | TreeSource:
        """The data to display in the tree.

        When setting this property:

        * A [`Source`][toga.sources.Source] will be used as-is. It must either be a
        [`TreeSource`][toga.sources.TreeSource], or
          a custom class that provides the same methods.

        * A value of None is turned into an empty TreeSource.

        * Otherwise, the value must be a dictionary or an iterable, which is copied
          into a new TreeSource as shown [here][treesource-item].

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

    @data.setter
    def data(self, data: TreeSourceT | object | None) -> None:
        old_data = getattr(self, "_data", None)
        if old_data is not None:
            self._data.remove_listener(self._impl)

        if data is None:
            data = []

        if isinstance(data, Source):
            self._data = data
        else:
            # try to copy the accessors from the previous data source
            accessors = getattr(old_data, "accessors", None)
            if accessors is None:
                # failing that, use the accessors from the columns, if any
                accessors = [
                    column.accessor
                    for column in self.columns
                    if getattr(column, "accessor", None) is not None
                ]
            self._data = TreeSource(accessors=accessors, data=data)

        self._data.add_listener(self._impl)
        self._impl.change_source(source=self._data)

    @property
    def multiple_select(self) -> bool:
        """Does the tree allow multiple rows to be selected?"""
        return self._multiple_select

    @property
    def selection(self) -> list[Node] | Node | None:
        """The current selection of the tree.

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

        If multiple selection is *not* enabled, returns the selected Node object, or
        [`None`][] if no node is currently selected.
        """
        return self._impl.get_selection()

    def expand(self, node: Node | None = None) -> None:
        """Expand the specified node of the tree.

        If no node is provided, all nodes of the tree will be expanded.

        If the provided node is a leaf node, or the node is already expanded, this is a
        no-op.

        If a node is specified, the children of that node will also be expanded.

        :param node: The node to expand
        """
        if node is None:
            self._impl.expand_all()
        else:
            self._impl.expand_node(node)

    def collapse(self, node: Node | None = None) -> None:
        """Collapse the specified node of the tree.

        If no node is provided, all nodes of the tree will be collapsed.

        If the provided node is a leaf node, or the node is already collapsed,
        this is a no-op.

        :param node: The node to collapse
        """
        if node is None:
            self._impl.collapse_all()
        else:
            self._impl.collapse_node(node)

    def append_column(
        self,
        column: ColumnT[Value] | str | None = None,
        accessor: str | None = None,
        *,
        heading: str | None = None,
    ) -> None:
        """Append a column to the end of the tree.

        :param column: The new column, or a heading string for the new column.
        :param accessor: **DEPRECATED** To specify a non-default accessor for a column,
            use an [`AccessorColumn`][toga.sources.AccessorColumn]. To specify the
            ordering of accessors use a [`TreSource`][toga.sources.TreeSource] 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.
        """
        ######################################################################
        # 2026-02: Backwards compatibility for <= 0.5.3
        ######################################################################
        if heading is not None:
            if column is None:
                warnings.warn(
                    "The 'heading' keyword argument is deprecated; "
                    "use 'column' instead.",
                    DeprecationWarning,
                    stacklevel=2,
                )
                column = heading
            else:
                raise TypeError("Can't specify both 'column' and 'heading' arguments.")

        # Deprecation of accessor is flagged by insert_column()

        ######################################################################
        # End backwards compatibility
        ######################################################################
        self.insert_column(len(self._columns), column, accessor=accessor)

    def insert_column(
        self,
        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 tree.

        :param index: The index at which to insert the column, or the column (or its
            accessor [Deprecated]) before which the new column should be inserted.
        :param column: The new column, or a heading string for the new column.
        :param accessor: **DEPRECATED** To specify a non-default accessor for a column,
            use an [`AccessorColumn`][toga.sources.AccessorColumn]. To specify the
            ordering of accessors use a [`TreSource`][toga.sources.TreeSource] 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.
        """
        ######################################################################
        # 2026-02: Backwards compatibility for <= 0.5.3
        ######################################################################
        if heading is not None:
            if column is None:
                warnings.warn(
                    "The 'heading' keyword argument is deprecated; "
                    "use 'column' instead.",
                    DeprecationWarning,
                    stacklevel=2,
                )
                column = heading
            else:
                raise TypeError("Can't specify both 'column' and 'heading' arguments.")

        if accessor is not None:
            warnings.warn(
                "The `accessor` argument is deprecated. To specify a non-default "
                "accessor for a column, use an `AccessorColumn`. To specify the "
                "ordering of accessors use a `TreeSource` with an `accessors` "
                "argument for the data.",
                DeprecationWarning,
                stacklevel=2,
            )

        ######################################################################
        # End backwards compatibility
        ######################################################################
        if column is None and accessor is None:
            raise ValueError("Must specify either a column or an accessor.")
        elif isinstance(column, str) and not self._show_headings and accessor is None:
            raise ValueError("Must specify an accessor on a tree without headings.")
        elif isinstance(column, str) or column is None:
            column = AccessorColumn(column, accessor)
        elif accessor is not None:
            warnings.warn(
                "The 'accessor' argument is ignored when a column object is supplied.",
                stacklevel=2,
            )

        ######################################################################
        # 2026-02: Backwards compatibility for <= 0.5.3
        ######################################################################
        if isinstance(index, str):
            index = self.accessors.index(index)
        ######################################################################
        # End backwards compatibility
        ######################################################################
        elif not isinstance(index, int):
            index = self._columns.index(index)
        else:
            # Re-interpret negative indices, and clip indices outside valid range.
            if index < 0:
                index = max(len(self._columns) + index, 0)
            else:
                index = min(len(self._columns), index)

        self._columns.insert(index, column)
        try:
            self._impl.insert_column(index, column)
        except TypeError:
            ######################################################################
            # 2026-02: Backwards compatibility for <= 0.5.3
            ######################################################################
            warnings.warn(
                "Tree implementations of insert_column should expect a column object "
                "not heading and accessor.",
                DeprecationWarning,
                stacklevel=2,
            )
            self._impl.insert_column(
                index, column.heading, getattr(column, "accessor", None)
            )
            ######################################################################
            # End backwards compatibility
            ######################################################################

    def remove_column(self, column: int | ColumnT[Value] | str) -> None:
        """Remove a tree column.

        :param column: The index of the column to remove, or the column (or its
            accessor [Deprecated]) to remove.
        """
        ######################################################################
        # 2026-02: Backwards compatibility for <= 0.5.3
        ######################################################################
        if isinstance(column, str):
            index = self.accessors.index(column)
        ######################################################################
        # End backwards compatibility
        ######################################################################
        elif not isinstance(column, int):
            index = self._columns.index(column)
        else:
            if column < 0:
                index = len(self._columns) + column
            else:
                index = column

        # Remove column
        del self._columns[index]
        self._impl.remove_column(index)

    @property
    def columns(self) -> list[ColumnT[Value]]:
        """The columns for the tree (read-only)"""
        return self._columns.copy()

    @property
    def show_headings(self) -> bool:
        """Whether or not the table shows a header at the top (read-only)"""
        return self._show_headings

    @property
    def headings(self) -> list[str] | None:
        """The column headings for the tree (read-only)"""
        print("here")
        if not self._show_headings:
            return None
        else:
            return [column.heading for column in self._columns]

    ######################################################################
    # 2026-02: Backwards compatibility for <= 0.5.3
    ######################################################################
    @property
    def accessors(self) -> list[str | None]:
        """The list of column accessors (read-only) [Deprecated]"""
        warnings.warn(
            "Using accessors is deprecated; use columns instead.",
            DeprecationWarning,
            stacklevel=2,
        )
        return [getattr(column, "accessor", None) for column in self._columns]

    ######################################################################
    # End backwards compatibility
    ######################################################################

    @property
    def missing_value(self) -> str:
        """The value that will be used when a data row doesn't provide a value for an
        attribute.
        """
        return self._missing_value

    @property
    def on_select(self) -> OnSelectHandler:
        """The callback function that is invoked when a row of the tree is selected."""
        return self._on_select

    @on_select.setter
    def on_select(self, handler: toga.widgets.tree.OnSelectHandler) -> None:
        self._on_select = wrapped_handler(self, handler)

    @property
    def on_activate(self) -> OnActivateHandler:
        """The callback function that is invoked when a row of the tree is activated,
        usually with a double click or similar action."""
        return self._on_activate

    @on_activate.setter
    def on_activate(self, handler: toga.widgets.tree.OnActivateHandler) -> None:
        self._on_activate = wrapped_handler(self, handler)

accessors property

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

columns property

The columns for the tree (read-only)

data property writable

The data to display in the tree.

When setting this property:

• A Source will be used as-is. It must either be a TreeSource, or a custom class that provides the same methods.

• A value of None is turned into an empty TreeSource.

• Otherwise, the value must be a dictionary or an iterable, which is copied into a new TreeSource as shown here.

In the last two cases, when creating a new or empty TreeSource, 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

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

headings property

The column headings for the tree (read-only)

missing_value property

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

multiple_select property

Does the tree allow multiple rows to be selected?

on_activate property writable

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

on_select property writable

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

selection property

The current selection of the tree.

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

If multiple selection is not enabled, returns the selected Node object, or [None][] if no node is currently selected.

show_headings property

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

__init__(columns=None, id=None, style=None, data=None, accessors=None, multiple_select=False, on_select=None, on_activate=None, missing_value='', *, show_headings=None, headings=None, **kwargs)

Create a new Tree widget.

:param columns: The column objects or heading strings for the tree. 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.

:param id: The ID for the widget. :param style: A style object. If no style is provided, a default style will be applied to the widget. :param data: Initial data to be displayed in the tree. This can be an object which implements the TreeSourceT protocol, an Iterable object, or [None][]. An Iterable object will be automatically converted to a TreeSource. :param 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 tree data is provided as an iterable, the
[`TreeSource`][toga.sources.TreeSource] created by the Tree will try to
derive its accessors from the column definitions. However, when the tree
data has entries that will not be displayed in the tree, 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 and any additional accessors needed.  When the column is given by a
  heading string then the heading and accessor will be used to create an
  [`AccessorColumn`][toga.sources.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`][toga.sources.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'][toga.sources.AccessorColumn] instance will be created for
each accessor and a tree with no headings will be created.

The accessors are also passed to any [`TreeSource`][toga.sources.TreeSource]
created by the Tree 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.

:param multiple_select: Does the tree allow multiple selection? :param on_select: Initial on_select handler. :param on_activate: Initial on_activate handler. :param 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. :param show_headings: Whether or not to show headings at the top of the tree. For backwards compatibility, this is set to False if no columns or headings are provided. :param headings: DEPRECATED A list of heading strings for columns. :param kwargs: Initial style properties.

Source code in core/src/toga/widgets/tree.py

def __init__(
    self,
    columns: Iterable[str | ColumnT[Value]] | None = None,
    id: str | None = None,
    style: Pack | None = None,
    data: TreeSourceT | object | None = None,
    accessors: Iterable[str] | None = None,
    multiple_select: bool = False,
    on_select: toga.widgets.tree.OnSelectHandler | None = None,
    on_activate: toga.widgets.tree.OnActivateHandler | None = None,
    missing_value: str = "",
    *,
    show_headings: bool | None = None,
    headings: Iterable[str] | None = None,
    **kwargs,
):
    """Create a new Tree widget.

    :param columns: The column objects or heading strings for the tree. Column
        objects must implement the ['ColumnT'][toga.sources.ColumnT] protocol.
        Heading strings will be converted to
        ['AccessorColumn'][toga.sources.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.
    :param id: The ID for the widget.
    :param style: A style object. If no style is provided, a default style will be
        applied to the widget.
    :param data: Initial [`data`][toga.Tree.data] to be displayed in the tree. This
        can be an object which implements the `TreeSourceT` protocol, an Iterable
        object, or [`None`][]. An Iterable object will be automatically converted to
        a [`TreeSource`][toga.sources.TreeSource].
    :param accessors: **DEPRECATED** To specify a non-default accessor name for a
        column, specify columns using
        ['AccessorColumn'][toga.sources.AccessorColumn] instances. To specify the
        ordering of items in table data, specify `data` using a
        [`ListSource`][toga.sources.ListSource] with an `accessors` argument.

        When tree data is provided as an iterable, the
        [`TreeSource`][toga.sources.TreeSource] created by the Tree will try to
        derive its accessors from the column definitions. However, when the tree
        data has entries that will not be displayed in the tree, 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 and any additional accessors needed.  When the column is given by a
          heading string then the heading and accessor will be used to create an
          [`AccessorColumn`][toga.sources.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`][toga.sources.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'][toga.sources.AccessorColumn] instance will be created for
        each accessor and a tree with no headings will be created.

        The accessors are also passed to any [`TreeSource`][toga.sources.TreeSource]
        created by the Tree 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.
    :param multiple_select: Does the tree allow multiple selection?
    :param on_select: Initial [`on_select`][toga.Tree.on_select] handler.
    :param on_activate: Initial [`on_activate`][toga.Tree.on_activate] handler.
    :param 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.
    :param show_headings: Whether or not to show headings at the top of the tree.
        For backwards compatibility, this is set to False if no columns or headings
        are provided.
    :param headings: **DEPRECATED** A list of heading strings for columns.
    :param kwargs: Initial style properties.
    """
    self._data: TreeSourceT | TreeSource

    self._missing_value = missing_value if missing_value else ""
    self._multiple_select = multiple_select

    ######################################################################
    # 2026-02: Backwards compatibility for <= 0.5.3
    ######################################################################
    if headings is not None:
        if columns is None:
            warnings.warn(
                "The 'headings' keyword argument is deprecated; "
                "use 'columns' instead.",
                DeprecationWarning,
                stacklevel=2,
            )
            columns = headings
        else:
            raise TypeError("Can't specify columns and headings at the same time.")
    if accessors is not None:
        warnings.warn(
            "The `accessors` argument is deprecated. To specify a non-default "
            "accessor for a column, use an `AccessorColumn`. To specify the "
            "ordering of accessors use a `TreeSource` with an `accessors` "
            "argument for the data.",
            DeprecationWarning,
            stacklevel=2,
        )

    if columns is None:
        if accessors is None:
            raise ValueError(
                "Cannot create a tree without either columns or accessors."
            )
        columns = AccessorColumn.columns_from_headings_and_accessors(
            None, accessors
        )
        if show_headings is None:
            # Don't show headings if only given accessors.
            show_headings = False
    elif isinstance(accessors, Mapping):
        columns = [
            AccessorColumn(column, accessors.get(column, None))
            if isinstance(column, str)
            else column
            for column in columns
        ]
    elif accessors is not None:
        columns = [
            AccessorColumn(column, accessor) if isinstance(column, str) else column
            for column, accessor in zip(columns, accessors, strict=False)
        ]
    ######################################################################
    # End backwards compatibility
    ######################################################################
    else:
        columns = [
            AccessorColumn(column) if isinstance(column, str) else column
            for column in columns
        ]

    ######################################################################
    # 2026-02: Backwards compatibility for <= 0.5.3
    #
    # When removing backwards compatibility for accessors, show_headings can
    # default to True, and this logic can be removed.
    ######################################################################
    self._show_headings = show_headings if show_headings is not None else True
    ######################################################################
    # End backwards compatibility
    ######################################################################

    self._columns: list[ColumnT] = columns

    # Prime some properties that need to exist before the tree is created.
    self.on_select = None
    self.on_activate = None

    super().__init__(id, style, **kwargs)

    if not isinstance(data, Source):
        if accessors is None or isinstance(accessors, Mapping):
            # Use the column's accessors
            accessor_order = [
                column.accessor
                for column in columns
                if getattr(column, "accessor", None) is not None
            ]
        else:
            # use the accessors parameter
            accessor_order = list(accessors)

        if data is None:
            data = TreeSource(accessors=accessor_order, data=[])
        else:
            data = TreeSource(accessors=accessor_order, data=data)

    self.data = data

    self.on_select = on_select
    self.on_activate = on_activate

append_column(column=None, accessor=None, *, heading=None)

Append a column to the end of the tree.

:param column: The new column, or a heading string for the new column. :param accessor: DEPRECATED To specify a non-default accessor for a column, use an AccessorColumn. To specify the ordering of accessors use a TreSource 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.

Source code in core/src/toga/widgets/tree.py

def append_column(
    self,
    column: ColumnT[Value] | str | None = None,
    accessor: str | None = None,
    *,
    heading: str | None = None,
) -> None:
    """Append a column to the end of the tree.

    :param column: The new column, or a heading string for the new column.
    :param accessor: **DEPRECATED** To specify a non-default accessor for a column,
        use an [`AccessorColumn`][toga.sources.AccessorColumn]. To specify the
        ordering of accessors use a [`TreSource`][toga.sources.TreeSource] 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.
    """
    ######################################################################
    # 2026-02: Backwards compatibility for <= 0.5.3
    ######################################################################
    if heading is not None:
        if column is None:
            warnings.warn(
                "The 'heading' keyword argument is deprecated; "
                "use 'column' instead.",
                DeprecationWarning,
                stacklevel=2,
            )
            column = heading
        else:
            raise TypeError("Can't specify both 'column' and 'heading' arguments.")

    # Deprecation of accessor is flagged by insert_column()

    ######################################################################
    # End backwards compatibility
    ######################################################################
    self.insert_column(len(self._columns), column, accessor=accessor)

collapse(node=None)

Collapse the specified node of the tree.

If no node is provided, all nodes of the tree will be collapsed.

If the provided node is a leaf node, or the node is already collapsed, this is a no-op.

:param node: The node to collapse

Source code in core/src/toga/widgets/tree.py

def collapse(self, node: Node | None = None) -> None:
    """Collapse the specified node of the tree.

    If no node is provided, all nodes of the tree will be collapsed.

    If the provided node is a leaf node, or the node is already collapsed,
    this is a no-op.

    :param node: The node to collapse
    """
    if node is None:
        self._impl.collapse_all()
    else:
        self._impl.collapse_node(node)

expand(node=None)

Expand the specified node of the tree.

If no node is provided, all nodes of the tree will be expanded.

If the provided node is a leaf node, or the node is already expanded, this is a no-op.

If a node is specified, the children of that node will also be expanded.

:param node: The node to expand

Source code in core/src/toga/widgets/tree.py

def expand(self, node: Node | None = None) -> None:
    """Expand the specified node of the tree.

    If no node is provided, all nodes of the tree will be expanded.

    If the provided node is a leaf node, or the node is already expanded, this is a
    no-op.

    If a node is specified, the children of that node will also be expanded.

    :param node: The node to expand
    """
    if node is None:
        self._impl.expand_all()
    else:
        self._impl.expand_node(node)

insert_column(index, column=None, accessor=None, *, heading=None)

Insert an additional column into the tree.

:param index: The index at which to insert the column, or the column (or its accessor [Deprecated]) before which the new column should be inserted. :param column: The new column, or a heading string for the new column. :param accessor: DEPRECATED To specify a non-default accessor for a column, use an AccessorColumn. To specify the ordering of accessors use a TreSource 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.

Source code in core/src/toga/widgets/tree.py

def insert_column(
    self,
    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 tree.

    :param index: The index at which to insert the column, or the column (or its
        accessor [Deprecated]) before which the new column should be inserted.
    :param column: The new column, or a heading string for the new column.
    :param accessor: **DEPRECATED** To specify a non-default accessor for a column,
        use an [`AccessorColumn`][toga.sources.AccessorColumn]. To specify the
        ordering of accessors use a [`TreSource`][toga.sources.TreeSource] 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.
    """
    ######################################################################
    # 2026-02: Backwards compatibility for <= 0.5.3
    ######################################################################
    if heading is not None:
        if column is None:
            warnings.warn(
                "The 'heading' keyword argument is deprecated; "
                "use 'column' instead.",
                DeprecationWarning,
                stacklevel=2,
            )
            column = heading
        else:
            raise TypeError("Can't specify both 'column' and 'heading' arguments.")

    if accessor is not None:
        warnings.warn(
            "The `accessor` argument is deprecated. To specify a non-default "
            "accessor for a column, use an `AccessorColumn`. To specify the "
            "ordering of accessors use a `TreeSource` with an `accessors` "
            "argument for the data.",
            DeprecationWarning,
            stacklevel=2,
        )

    ######################################################################
    # End backwards compatibility
    ######################################################################
    if column is None and accessor is None:
        raise ValueError("Must specify either a column or an accessor.")
    elif isinstance(column, str) and not self._show_headings and accessor is None:
        raise ValueError("Must specify an accessor on a tree without headings.")
    elif isinstance(column, str) or column is None:
        column = AccessorColumn(column, accessor)
    elif accessor is not None:
        warnings.warn(
            "The 'accessor' argument is ignored when a column object is supplied.",
            stacklevel=2,
        )

    ######################################################################
    # 2026-02: Backwards compatibility for <= 0.5.3
    ######################################################################
    if isinstance(index, str):
        index = self.accessors.index(index)
    ######################################################################
    # End backwards compatibility
    ######################################################################
    elif not isinstance(index, int):
        index = self._columns.index(index)
    else:
        # Re-interpret negative indices, and clip indices outside valid range.
        if index < 0:
            index = max(len(self._columns) + index, 0)
        else:
            index = min(len(self._columns), index)

    self._columns.insert(index, column)
    try:
        self._impl.insert_column(index, column)
    except TypeError:
        ######################################################################
        # 2026-02: Backwards compatibility for <= 0.5.3
        ######################################################################
        warnings.warn(
            "Tree implementations of insert_column should expect a column object "
            "not heading and accessor.",
            DeprecationWarning,
            stacklevel=2,
        )
        self._impl.insert_column(
            index, column.heading, getattr(column, "accessor", None)
        )

remove_column(column)

Remove a tree column.

:param column: The index of the column to remove, or the column (or its accessor [Deprecated]) to remove.

Source code in core/src/toga/widgets/tree.py

def remove_column(self, column: int | ColumnT[Value] | str) -> None:
    """Remove a tree column.

    :param column: The index of the column to remove, or the column (or its
        accessor [Deprecated]) to remove.
    """
    ######################################################################
    # 2026-02: Backwards compatibility for <= 0.5.3
    ######################################################################
    if isinstance(column, str):
        index = self.accessors.index(column)
    ######################################################################
    # End backwards compatibility
    ######################################################################
    elif not isinstance(column, int):
        index = self._columns.index(column)
    else:
        if column < 0:
            index = len(self._columns) + column
        else:
            index = column

    # Remove column
    del self._columns[index]
    self._impl.remove_column(index)

Bases: Protocol

Source code in core/src/toga/widgets/tree.py

class OnSelectHandler(Protocol):
    def __call__(self, widget: Tree, **kwargs: Any) -> None:
        """A handler to invoke when the tree is selected.

        :param widget: The Tree that was selected.
        :param kwargs: Ensures compatibility with arguments added in future versions.
        """

__call__(widget, **kwargs)

A handler to invoke when the tree is selected.

:param widget: The Tree that was selected. :param kwargs: Ensures compatibility with arguments added in future versions.

Source code in core/src/toga/widgets/tree.py

def __call__(self, widget: Tree, **kwargs: Any) -> None:
    """A handler to invoke when the tree is selected.

    :param widget: The Tree that was selected.
    :param kwargs: Ensures compatibility with arguments added in future versions.
    """

Bases: Protocol

Source code in core/src/toga/widgets/tree.py

class OnActivateHandler(Protocol):
    def __call__(self, widget: Tree, **kwargs: Any) -> None:
        """A handler to invoke when the tree is activated.

        :param widget: The Tree that was activated.
        :param kwargs: Ensures compatibility with arguments added in future versions.
        """

__call__(widget, **kwargs)

A handler to invoke when the tree is activated.

:param widget: The Tree that was activated. :param kwargs: Ensures compatibility with arguments added in future versions.

Source code in core/src/toga/widgets/tree.py

def __call__(self, widget: Tree, **kwargs: Any) -> None:
    """A handler to invoke when the tree is activated.

    :param widget: The Tree that was activated.
    :param kwargs: Ensures compatibility with arguments added in future versions.
    """