Simplified widgets using tkinter.ttk.Treeview

buttonbox.py

#!/usr/bin/env python3

# Button box component, lays out buttons in a horizontal or vertical layout
# evenly.

# GUI stuff
import tkinter
from tkinter import ttk


# The component
class ButtonBox(ttk.Frame):
    def __init__(
        self, parent, orientation=tkinter.HORIZONTAL, weight=1, **kwargs
    ):
        super(ButtonBox, self).__init__(parent, **kwargs)

        if orientation == tkinter.HORIZONTAL:
            self.columnconfigure(0, weight=weight)
        elif orientation == tkinter.VERTICAL:
            self.rowconfigure(0, weight=weight)
        else:
            raise ValueError(
                "Expected orientation to be tkinter.HORIZONTAL or "
                "tkinter.VERTICAL, got %r" % orientation
            )

        self._orientation = orientation
        self._buttons = []
        self._next_pos = 0

    def add_button(
        self,
        text,
        command,
        span=1,
        weight=1,
        sticky=(tkinter.N, tkinter.S, tkinter.E, tkinter.W),
        **kwargs
    ):
        btn = ttk.Button(self, text=text, command=command)
        self._buttons.append(btn)
        pos = self._next_pos
        self._next_pos += span

        if self._orientation == tkinter.HORIZONTAL:
            btn.grid(
                row=0, column=pos, rowspan=1, columnspan=span, sticky=sticky
            )
            self.columnconfigure(pos, weight=weight)
        else:
            btn.grid(
                row=pos, column=0, rowspan=span, columnspan=1, sticky=sticky
            )
            self.rowconfigure(pos, weight=weight)

        return self


# Example usage
if __name__ == "__main__":
    print("Running button box example")
    tk = tkinter.Tk()

    def _pressed(x, *a):
        print("%r pressed (a=%r)" % (x, a))

    widget = ButtonBox(parent=tk)
    widget.add_button("Button 1", command=lambda *a: _pressed("B1", *a))
    widget.add_button("Button 2", command=lambda *a: _pressed("B2", *a))
    widget.add_button("Button 3", command=lambda *a: _pressed("B3", *a))
    widget.pack(fill="both", expand=True)
    tk.mainloop()

enumlist.py

#!/usr/bin/env python3

"""
A drop-down list widget that takes an Enum for its input.
"""

# © 2024 Stuart Longland VK4MSL
# SPDX-License-Identifier: Python-2.0

# GUI stuff
from .objectlist import ObjectList


# The component
class EnumList(ObjectList):
    """
    Drop-down list box using Enums.  Sorting and label generation can be
    customised through subclassing.
    """

    def __init__(
        self,
        parent,
        enum,
        value=None,
        on_select=None,
        add_none=False,
        reverse=False,
        **kwargs
    ):
        """
        Create a new EnumList object.

        :param parent:      Tkinter parent object
        :type parent:       class:`tkinter.Widget`
        :param enum:        The enumeration that represents the possible
                            values.
        :type enum:         class:`Enum`
        :param on_select:   Call-back function when an item is selected
        :type on_select:    function
        :param add_none:    Add an option for ``None``
        :type add_none:     boolean
        :param reverse:     Reverse the sort order
        :type reverse:      boolean
        """
        values = list(enum)
        if add_none:
            values.insert(0, None)

        self._enum = enum

        super(EnumList, self).__init__(
            parent,
            values=values,
            value=value,
            on_select=on_select,
            reverse=reverse,
            **kwargs
        )

    # Internals

    def _get_identity(self, value):
        """
        Cast the value to the Enum value.
        """
        if value is None:
            return None

        return self._enum(value)

    def _get_text(self, value):
        """
        Conversion of a value to a string.  This simple version returns the
        "name" of the enum value, or an empty string for ``None``.

        This may be customised in a sub-class for special handling.
        """
        if value is None:
            return ""
        else:
            return value.name


# Example usage
if __name__ == "__main__":
    from enum import Enum
    import tkinter

    print("Running EnumList example")
    tk = tkinter.Tk()

    class TestEnum(Enum):
        EnumA = 1
        EnumB = 2
        EnumC = 3

    def _on_select(lst, selection):
        print("Selected: %r" % selection)

    widget = EnumList(
        parent=tk, enum=TestEnum, on_select=_on_select, add_none=True
    )

    assert widget.selection is None
    assert widget.text == ""

    widget.selection = 2  # EnumB
    print(widget.selection)

    widget.pack(fill="both", expand=True)
    tk.mainloop()

objectlist.py

#!/usr/bin/env python3

"""
A drop-down list widget that takes arbtrary objects for input.
"""

# © 2024 Stuart Longland VK4MSL
# SPDX-License-Identifier: Python-2.0

# GUI stuff
import tkinter
from tkinter import ttk


# The component
class ObjectList(ttk.Frame):
    """
    Drop-down list box using arbitrary object instances.  Sorting and label
    generation can be customised through subclassing.
    """

    def __init__(
        self,
        parent,
        values,
        value=None,
        on_select=None,
        add_none=False,
        reverse=False,
        **kwargs
    ):
        """
        Create a new ObjectList object.

        :param parent:      Tkinter parent object
        :type parent:       class:`tkinter.Widget`
        :param values:      The possible selection values permitted.
        :type values:       class:`Sequence`
        :param on_select:   Call-back function when an item is selected
        :type on_select:    function
        :param reverse:     Reverse the sort order
        :type reverse:      boolean
        """
        super(ObjectList, self).__init__(parent, **kwargs)

        self._on_select = on_select
        self._reverse = reverse
        (self._values, self._labels) = self._enumerate_values(values)
        self._values_rmap = dict(
            (self._get_identity(value), posn)
            for (posn, value) in enumerate(self._values)
        )

        self._label_var = tkinter.StringVar(value=self._get_text(value))
        self._listbox = ttk.Combobox(self, textvariable=self._label_var)
        self._listbox["values"] = self._labels
        self._listbox.state(["readonly"])
        self._listbox.grid(
            row=0,
            column=0,
            sticky=(tkinter.N, tkinter.S, tkinter.E, tkinter.W),
        )
        self._listbox.bind("<<ComboboxSelected>>", self._on_lbselect)

        self.columnconfigure(0, weight=1)
        self.rowconfigure(0, weight=1)

    # Selection API

    @property
    def text(self):
        """
        Return the human-readable selection text value.
        """
        return self._label_var.get()

    @property
    def selection(self):
        """
        Retrieve the currently selected enum value.
        """
        # current() returns the index of the current value or -1 if the current value is
        # not in the values list.
        selection = self._listbox.current()
        if selection < 0:
            return None
        else:
            return self._values[selection]

    @selection.setter
    def selection(self, value):
        """
        Select one of the possible enum values, or none of them if ``None``.
        """
        if value is None:
            self._listbox.current(-1)
        else:
            self._listbox.current(
                self._values_rmap[self._get_identity(value)]
            )

    @property
    def on_select(self):
        """
        Return the callback called when a selection is changed.
        """
        return self._on_select

    @on_select.setter
    def on_select(self, callback):
        """
        Change the callback called when a selection is changed.
        """
        self._on_select = callback

    # Internals

    def _get_identity(self, value):
        """
        Return an identifier for the value provided.  This is used to select a
        specific value key.  The default implementation returns the object's
        ``id()`` (in CPython; this function returns the C pointer.)
        """
        return id(value)

    def _enumerate_values(self, values):
        """
        Enumerate all possible values and their labels.

        Returns (tuple_of_values, tuple_of_labels)
        """
        # Generates a list of [(enumvalue, enumlabel)]
        labelled_values = sorted(
            ((value, self._get_text(value)) for value in values),
            key=lambda i: self._get_sort_key(*i),
            reverse=self._reverse,
        )

        # Split these into two separate tuples, return as a 2-element tuple of
        # tuples.
        return tuple(zip(*labelled_values))

    def _get_sort_key(self, value, label):
        """
        Return the sort order key for the enumeration.  The default
        implementation sorts by text label ascending, this can be overridden
        in a sub-class.
        """
        return label

    def _get_text(self, value):
        """
        Conversion of a value to a string.  This simple version returns the
        result of ``str(value)``, or an empty string for ``None``.

        This may be customised in a sub-class for special handling.
        """
        if value is None:
            return ""
        else:
            return str(value)

    def _on_lbselect(self, *args):
        if self.on_select is not None:
            self.on_select(self, self.selection)


# Example usage
if __name__ == "__main__":
    from enum import Enum

    print("Running ObjectList example")
    tk = tkinter.Tk()

    class MyObjectClass(object):
        def __init__(self, label):
            self._label = label

        def __str__(self):
            return self._label

        def __repr__(self):
            return "%s(%r)" % (self.__class__.__name__, self._label)

    values = [
        None,
        MyObjectClass("Option 1"),
        MyObjectClass("Option 2"),
        MyObjectClass("Option 3"),
    ]

    def _on_select(lst, selection):
        print("Selected: %r" % selection)

    widget = ObjectList(parent=tk, values=values, on_select=_on_select)

    assert widget.selection is None
    assert widget.text == ""

    widget.selection = values[2]  # Option 2
    print(widget.selection)

    widget.pack(fill="both", expand=True)
    tk.mainloop()

table.py

#!/usr/bin/env python3

"""
Simplified table widget based on ttk.Treeview.  This simplifies the Treeview
widget, distilling the essential functions needed to manage a simple table
view.

The Treeview widget is actually very capable, but it has a rather obscure API
owing to its complexity _and_ its background as being a Tk widget that has
been "mapped" to Python's API.

The following wrapper provides a simplified and opinionated interface that
allows for display and manipulation of tabular data only.  A distinctly "KISS"
approach is taken here.

- multi-selections are supported, but not the default
- true 'tree' structures are not supported
- `None` is rendered as an empty string
- Other data types are coerced to strings on passing to the Treeview
- There is some support there for custom row types through subclassing
"""

# © 2024 Stuart Longland VK4MSL
# SPDX-License-Identifier: Python-2.0

from collections.abc import MutableSequence, MutableMapping, Sequence, Mapping

# GUI stuff
import tkinter
from tkinter import ttk


class TableItem(MutableMapping):
    """
    Item base class for representing rows in the table.  This stores
    references to the textual label for the row (left-most column), any values
    for the columns themselves, the item ID (as assigned by Tkinter) and a
    reference to an application-specific object.

    :param table:       The Table object that this row is a part of.
    :type table:        class:`Table`
    :param value:       The value representing the label of the row.  If not a
                        string, it will be stringified using the ``str()``
                        operator.
    :param columns:     The values of the optional data columns.
    :type columns:      tuple
    :param iid:         The iid returned by ``tkinter`` when inserted
    :type iid:          str
    :param objectref:   Optional object reference for the application
    """

    def __init__(self, table, value, columns=None, iid=None, objectref=None):
        self._table = table
        self._value = value
        self._columns = list(columns)
        self._iid = iid
        self._objectref = objectref

    # Debugging

    def __repr__(self):
        return "%s(table=%r, value=%r, columns=%r, iid=%r, objectref=%r)" % (
            self.__class__.__name__,
            self._table,
            self._value,
            self._columns,
            self._iid,
            self._objectref,
        )

    # Interaction with the item label itself

    @property
    def value(self):
        """
        Return the value associated for this row.
        """
        return self._value

    @value.setter
    def value(self, value):
        """
        Update the value associated with this row.
        """
        self._value = value

        if self._iid is not None:
            # Stringify "value" in case it's an object
            self._table._treeview.item(self._iid, text=self._get_text(value))

    @property
    def objectref(self):
        """
        Return the application object linked to this row.
        """
        return self._objectref

    @objectref.setter
    def objectref(self, value):
        """
        Update the application object linked to this row.
        """
        self._objectref = value

    # MutableMapping interface for interacting with columns

    def __getitem__(self, key):
        """
        Return the value of the column specified by ``key``.

        :param key: Either the name or index of the column requested.
        :type key: str or int
        """
        (pos,) = self._get_pos(key)
        return self._columns[pos]

    def __setitem__(self, key, value):
        """
        Set the value of the column specified by ``key``.

        :param key:     Either the name or index of the column requested.
        :type key:      str or int
        :param value:   The value being set, if it is not a ``str``, it will
                        be stringified before being passed to the Treeview.
        """
        (pos, name) = self._get_pos(key)
        self._set_column(name, pos, value)

    def __delitem__(self, key):
        """
        Clear the value of the column specified by ``key``.  This is
        equivalent to:

        item[key] = None

        :param key: Either the name or index of the column requested.
        :type key: str or int
        """
        (pos, name) = self._get_pos(key)
        self._set_column(name, pos, None)

    def __iter__(self):
        """
        Iterate over the names of the columns.
        """
        return iter(self._table._columns)

    def __len__(self):
        """
        Returnt the number of columns.
        """
        return len(self._table._columns)

    # Internals

    def _get_text(self, value):
        """
        Translate the given value to a text string.  The default
        implementation passes this to the table class for conversion.
        """
        return self._table._get_text(value)

    def _get_pos(self, name):
        """
        Given a name or index, find the piece of information that's missing
        and return both.

        :param name: Name of a column (``str``) or index (``int``).
        :type name: str or int
        """
        if isinstance(name, int):
            return (name, self._table._columns[name])
        else:
            return (self._table._columns_by_name[name], name)

    def _set_column(self, name, pos, value):
        """
        Set the value of a column, updating the underlying Treeview at the
        same time.
        """
        self._columns[pos] = value

        if self._iid is not None:
            # Stringify "text" in case it's an object
            self._table._treeview.set(self._iid, name, self._get_text(value))


# The component
class Table(ttk.Frame, MutableSequence):
    _ITEM_CLASS = TableItem

    """
    Table component for Tkinter applications.  This can be sub-classed by
    applications to customise the behaviour.
    """

    def __init__(
        self,
        parent,
        columns=None,
        multiselect=False,
        on_select=None,
        **kwargs
    ):
        """
        Create a new Table object.

        :param parent:      Tkinter parent object
        :type parent:       class:`tkinter.Widget`
        :param columns:     The columns and their labels, a sequence of
                            two-element tuples of the form ``(name, title)``.
        :type columns:      class:`Sequence`
        :param multiselect: Whether we allow selecting multiple rows or not?
        :type multiselect:  boolean
        :param on_select:   Call-back function when an item is selected
        :type on_select:    function
        """
        if columns is None:
            columns = ()

        super(Table, self).__init__(parent, **kwargs)

        self._columns = tuple(c[0] for c in columns)
        self._columns_by_name = dict(
            (name, pos) for pos, name in enumerate(self._columns)
        )
        self._items = []
        self._multiselect = multiselect
        self._on_select = on_select

        self._treeview = ttk.Treeview(
            self,
            columns=self._columns,
            selectmode="extended" if multiselect else "browse",
        )
        self._treeview.grid(
            row=0,
            column=0,
            sticky=(tkinter.N, tkinter.S, tkinter.E, tkinter.W),
        )
        self._treeview.bind("<<TreeviewSelect>>", self._on_tvselect)

        # Set up headings
        for name, label in columns:
            self._treeview.heading(name, text=self._get_text(label))

        self.columnconfigure(0, weight=1)
        self.rowconfigure(0, weight=1)

    # Selection API

    @property
    def selection(self):
        """
        Retrieve the selections made on the table.

        If ``multiselect`` is ``True``:
            a ``set`` of indices is returned.  If nothing is selected,
            an empty ``set`` is returned.

        Else if ``multiselect`` is ``False``:
            the index of the row selected is returned.
            If nothing is selected, ``None`` is returned.
        """
        selection = self._treeview.selection()
        if self._multiselect:
            return set(self._treeview.index(iid) for iid in selection)
        else:
            try:
                return self._treeview.index(selection[0])
            except IndexError:
                return None

    @selection.setter
    def selection(self, indices):
        """
        Replace the selections made on the table.

        If ``indices`` is ``None``:
            De-select all rows.

        Else if ``multiselect`` is ``True``:
            ``indices`` is either a single index, or a sequence of indices.
            These rows will be selected (and others de-selected).

        Else if ``multiselect`` is ``False``:
            ``indices`` is an integer row index.  It will be selected.
        """
        if indices is None:
            # De-select all
            selection = ()
        elif self._multiselect:
            # Set multi-selection
            if not isinstance(indices, Sequence):
                indices = (indices,)
            selection = tuple(self._items[idx]._iid for idx in indices)
        else:
            # Set single-selection
            selection = (self._items[indices]._iid,)

        self._treeview.selection_set(*selection)

    def selection_add(self, *indices):
        """
        Add the indicated rows (given by row index) to the current selection
        without de-selecting other rows.  Requires ``multiselect`` set to
        ``True``.
        """
        self._selection_update("add", *indices)

    def selection_remove(self, *indices):
        """
        Remove the indicated rows (given by row index) to the current selection
        without de-selecting other rows.  Requires ``multiselect`` set to
        ``True``.
        """
        self._selection_update("remove", *indices)

    def selection_toggle(self, *indices):
        """
        Toggle the indicated rows (given by row index) to the current selection
        without de-selecting other rows.  Requires ``multiselect`` set to
        ``True``.
        """
        self._selection_update("toggle", *indices)

    @property
    def on_select(self):
        """
        Return the callback called when a selection is changed.
        """
        return self._on_select

    @on_select.setter
    def on_select(self, callback):
        """
        Change the callback called when a selection is changed.
        """
        self._on_select = callback

    # MutableSequence interface

    def __getitem__(self, idx):
        """
        Return the item on row ``idx``; if there's an object reference, return
        the object reference itself, otherwise just return the ``TableItem``.
        """
        item = self._items[idx]
        if item.objectref is not None:
            return item.objectref
        else:
            return item

    def __setitem__(self, idx, itemdata):
        """
        Replace the data for row ``idx``.  ``itemdata`` can take a couple of
        forms:

        - Bare value: ``itemdata`` will be stringified and used for the row
          label value.
        - Two-element tuple ``(value, columndict)``: ``value`` will be
          stringified and used as the row label value.  ``columndict`` is a
          mapping of column names to _their_ values for this row: again, all
          will be stringified for display purposes.
        - N-element tuple: N > 1; the first element of the tuple is taken as
          the row value, the remainder is the values of each column.
        """
        (value, columns, objectref) = self._getobject(itemdata)
        item = self._items[idx]
        item.value = value
        item.objectref = objectref
        for pos, col in enumerate(columns):
            item[pos] = col

    def __delitem__(self, idx):
        """
        Remove the row at index ``idx``.
        """
        item = self._items[idx]
        self._treeview.delete(item._iid)
        self._items.pop(idx)

    def __len__(self):
        """
        Return the number of rows in the table.
        """
        return len(self._items)

    def insert(self, idx, itemdata):
        """
        Insert a new row into the table.  See ``__setitem__`` above.
        """
        (value, columns, objectref) = self._getobject(itemdata)
        iid = self._treeview.insert(
            "",
            idx,
            text=str(value),
            values=tuple(self._get_text(c) for c in columns),
        )
        item = self._ITEM_CLASS(
            table=self,
            value=value,
            columns=columns,
            iid=iid,
            objectref=objectref,
        )
        self._items.insert(idx, item)

    # Internals

    def _selection_update(self, method, *indices):
        if not self._multiselect:
            raise NotImplementedError("This is not a multi-select table")

        getattr(self._treeview, "selection_%s" % method)(
            *(self._items[idx]._iid for idx in indices)
        )

    def _getobject(self, itemdata):
        """
        Extract the row information and object reference from the given
        object.  Sub-classes may override this, returning a tuple of the form:
        ``(rowvalue, columnvalues, objectref)``.
        """
        if isinstance(itemdata, str):
            # Assume plain row with no column data
            value = itemdata
            columns = (None,) * len(self._columns)
        elif isinstance(itemdata, Sequence):
            # Row with column data
            value = itemdata[0]
            if isinstance(itemdata[1], Mapping):
                # Columns given as a dict, convert to tuple
                columns = tuple(itemdata[1].get(c) for c in self._columns)
            else:
                columns = tuple(itemdata[1:])

            if len(columns) < len(self._columns):
                # Pad the columns
                columns += (None,) * (len(self._columns) - len(columns))
        else:
            raise TypeError(
                "Don't know how to handle type %s" % type(itemdata)
            )

        return (value, columns, None)

    def _get_text(self, value):
        """
        Conversion of a value to a string.  This simple version returns an
        empty string for ``None``, and ``str(value)`` for everything else.

        This may be customised in a sub-class for special handling.
        """
        if value is None:
            return ""
        else:
            return str(value)

    def _on_tvselect(self, *args):
        if self.on_select is not None:
            self.on_select(self, self.selection)


# Example usage
if __name__ == "__main__":
    print("Running Table example")
    tk = tkinter.Tk()

    def _on_select(tbl, selection):
        print("Selected: %r" % selection)

    widget = Table(
        parent=tk,
        columns=[("a", "Column A"), ("b", "Column B"), ("c", "Column C")],
        on_select=_on_select,
    )
    widget.append("A bare string")
    widget.append(("String with column data (tuple)", 111, 222, 333))
    widget.append("To be deleted")
    widget.append(
        ("String with column data (dict)", {"a": 444, "b": 555, "c": 666})
    )
    widget.append("Bare string, will be added to later")

    widget.selection = 1
    print(widget.selection)

    del widget[2]
    widget[3]["a"] = 123
    widget[3]["b"] = 456
    widget[3]["c"] = 789

    widget.pack(fill="both", expand=True)
    tk.mainloop()