treeviewex 1.0.0__py3-none-any.whl

treeviewex/__init__.py

@@ -0,0 +1,3 @@
+from .treeviewex import CellType, TreeviewEx
+
+__all__ = ["CellType", "TreeviewEx"]

treeviewex/treeviewex.py

@@ -0,0 +1,599 @@
+# python3
+"""Treeview extension."""
+
+from __future__ import annotations
+
+from enum import Enum, auto
+from tkinter import HORIZONTAL, VERTICAL, Entry, Event, Frame
+from tkinter.ttk import Combobox, Scrollbar, Treeview
+from typing import Callable, Union
+
+
+class CellType(Enum):
+    """Enum defining cell types."""
+
+    ENTRY = auto()
+    READONLY = auto()
+    COMBOBOX = auto()
+
+
+__all__ = ["CellType", "TreeviewEx"]
+
+
+def _colid2colindex(column_id: str) -> int:
+    """
+    Convert a column ID to a column index.
+
+    Parameters
+    ----------
+    column_id : str
+        Column ID.
+
+    Returns
+    -------
+    int
+        Column index.
+
+    """
+    return int(column_id[1:]) - 1
+
+
+class TreeviewEx(Treeview):  # pylint: disable=too-many-ancestors
+    """Extended Treeview widget."""
+
+    def __init__(self, master=None, **kwargs):
+        """
+        Initialize the widget.
+
+        Parameters
+        ----------
+        master : widget, optional
+            Parent widget. The default is None.
+        **kwargs : dict
+            Additional options passed to tkinter.ttk.Treeview.
+
+        Returns
+        -------
+        None.
+
+        """
+        # Initialization
+        self.readonly_rows = set()  # Keep read-only row IDs
+        self.readonly_columns = set()  # Keep read-only column IDs
+        self.readonly_cells = set()  # Keep read-only cells as (row, col)
+        self.combobox_rows = set()  # Keep row IDs that use a combobox
+        self.combobox_columns = set()  # Keep column IDs that use a combobox
+        self.combobox_cells = set()  # Keep combobox cells as (row, col)
+        self.combobox_row_values = {}  # Map row IDs to combobox value lists
+        self.combobox_column_values = {}  # Map columns to combobox value lists
+        self.combobox_cell_values = {}  # Map cells to combobox value lists
+
+        # Other initialization
+        self.frame = Frame(master=master)
+        super().__init__(self.frame, **kwargs)
+
+        # Create the Entry widget as a member
+        self.entry = Entry(self)
+        self.entry.bind("<Return>", self._on_return)
+        self.entry.bind("<FocusOut>", self._on_focus_out)
+        self.entry.bind("<Escape>", self._on_escape)
+
+        # Create the Combobox widget as a member
+        self.combobox = Combobox(self)
+        self.combobox.bind("<Return>", self._on_return)
+        self.combobox.bind("<Escape>", self._on_escape)
+        self.combobox.bind("<<ComboboxSelected>>", self._on_combobox_selected)
+
+        # Create a vertical scrollbar and connect it
+        self.scrollbar_y = Scrollbar(
+            self.frame, orient=VERTICAL, command=self._on_scroll_y
+        )
+        self.configure(yscrollcommand=self.scrollbar_y.set)
+
+        # Create a horizontal scrollbar and connect it
+        self.scrollbar_x = Scrollbar(
+            self.frame, orient=HORIZONTAL, command=self._on_scroll_x
+        )
+        self.configure(xscrollcommand=self.scrollbar_x.set)
+
+        super().grid(row=0, column=0, sticky="nsew")
+        self.scrollbar_y.grid(row=0, column=1, sticky="ns")
+        self.scrollbar_x.grid(row=1, column=0, sticky="ew")
+
+        # Set frame row/column weights to adjust the layout
+        self.frame.grid_rowconfigure(0, weight=1)
+        self.frame.grid_columnconfigure(0, weight=1)
+
+        # Bind additional behavior for the <Double-1> event
+        self._additional_bind_double_click()
+
+        # Bind the mouse wheel event
+        self.bind("<MouseWheel>", self._on_mouse_wheel)
+
+        # Variables to keep editing state
+        self._editing_cell = None
+        self._editing_combobox_values = None  # Values for active combobox edit
+
+    def _on_scroll_y(self, *args):
+        """
+        Handle vertical scroll events.
+
+        Parameters
+        ----------
+        *args : tuple
+            Scrollbar callback arguments.
+
+        Returns
+        -------
+        None.
+
+        """
+        if self._editing_cell:
+            self.cancel_edit()
+        self.yview(*args)
+
+    def _on_scroll_x(self, *args):
+        """
+        Handle horizontal scroll events.
+
+        Parameters
+        ----------
+        *args : tuple
+            Scrollbar callback arguments.
+
+        Returns
+        -------
+        None.
+
+        """
+        if self._editing_cell:
+            self.cancel_edit()
+        self.xview(*args)
+
+    def _on_mouse_wheel(self, event):
+        """
+        Handle mouse wheel events.
+
+        Parameters
+        ----------
+        event : Event
+            Mouse wheel event.
+
+        Returns
+        -------
+        None.
+
+        """
+        if self._editing_cell:
+            self.cancel_edit()
+
+        # Run vertical scrolling
+        self.yview_scroll(-1 * (event.delta // 120), "units")
+
+    def _additional_bind_double_click(self):
+        """
+        Add a double-click handler.
+
+        Returns
+        -------
+        None.
+
+        """
+        # Keep the existing <Double-1> binding and add this handler
+        super().bind("<Double-1>", self._combined_handler, add="+")
+
+    def _combined_handler(self, event: Event):
+        """
+        Handle double-click events.
+
+        Parameters
+        ----------
+        event : Event
+            Event object.
+
+        Returns
+        -------
+        None.
+
+        """
+        self.on_double_click(event)  # Additional behavior
+
+    def bind(
+        self,
+        sequence: str | None = None,
+        func: Callable | None = None,
+        add: bool | None = None,
+    ) -> str:
+        """
+        Override bind.
+
+        Parameters
+        ----------
+        sequence : str, optional
+            Same as the sequence argument of Treeview.bind().
+        func : Callable, optional
+            Same as the func argument of Treeview.bind().
+        add : bool, optional
+            Same as the add argument of Treeview.bind().
+
+        Returns
+        -------
+        str
+            Same return value as Treeview.bind().
+
+        """
+        if sequence == "<Double-1>":
+
+            def combined_handler(event):
+                self.on_double_click(event)
+                if func:
+                    func(event)
+
+            return super().bind(sequence, combined_handler, add=add)
+        else:
+            return super().bind(sequence, func, add=add)
+
+    def pack(self, **kwargs):
+        """
+        Override pack.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments for pack.
+
+        Returns
+        -------
+        None.
+
+        """
+        self.frame.pack(**kwargs)
+
+    def grid(self, **kwargs):
+        """
+        Override grid.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments for grid.
+
+        Returns
+        -------
+        None.
+
+        """
+        self.frame.grid(**kwargs)
+
+    def column(self, column: str, option=None, **kw):
+        """
+        Override column.
+
+        Parameters
+        ----------
+        column : str
+            Column ID.
+        option : str, optional
+            Column option. The default is None.
+        **kw : dict
+            Additional keyword arguments.
+
+        Returns
+        -------
+        Any
+            Return value from Treeview.column().
+
+        """
+        if option is None and "stretch" not in kw:
+            kw["stretch"] = False
+        return super().column(column, option, **kw)
+
+    def get_clicked_cell_id_pair(self, event: Event) -> tuple:
+        """
+        Get the cell IDs at the clicked position.
+
+        Parameters
+        ----------
+        event : Event
+            Click event.
+
+        Returns
+        -------
+        tuple
+            Pair of (row ID, column ID).
+
+        """
+        cell_id_pair = ("", "")
+        region = self.identify_region(event.x, event.y)
+        if region != "cell":
+            return ("", "")
+        cell_id_pair = (
+            self.identify_row(event.y),
+            self.identify_column(event.x),
+        )
+        return cell_id_pair
+
+    def on_double_click(self, event: Event) -> None:
+        """
+        Handle double-click action.
+
+        Parameters
+        ----------
+        event : Event
+            Event object.
+
+        Returns
+        -------
+        None.
+
+        """
+        cell_id_pair = self.get_clicked_cell_id_pair(event)
+        if cell_id_pair != ("", ""):
+            self.start_edit(cell_id_pair)
+
+    def get_cell_value(self, cell_id_pair: tuple) -> str:
+        """
+        Get a cell value.
+
+        Parameters
+        ----------
+        cell_id_pair : tuple
+            Pair of (row ID, column ID).
+
+        Returns
+        -------
+        str
+            Cell value.
+
+        """
+        row_id, column_id = cell_id_pair
+        return self.item(row_id, "values")[_colid2colindex(column_id)]
+
+    def start_edit(self, cell_id_pair: tuple) -> None:
+        """Start editing a cell."""
+        if not self.is_valid_cell(cell_id_pair):
+            raise ValueError(f"Invalid cell specified: {cell_id_pair}")
+
+        row_id, column_id = cell_id_pair
+
+        cell_type = self._get_cell_type(cell_id_pair)
+
+        # Skip editing when the cell is read-only
+        if cell_type == CellType.READONLY:
+            return
+
+        # Continue with edit processing
+        self._editing_cell = cell_id_pair
+        cell_value = self.get_cell_value(cell_id_pair)
+
+        # Get the cell position and size
+        bbox = self.bbox(row_id, column_id)
+        if not bbox:
+            raise ValueError(
+                f"Cannot determine the position of the cell: {cell_id_pair}"
+            )
+
+        x, y, width, height = bbox
+
+        # For combobox cells
+        if cell_type == CellType.COMBOBOX:
+            # Keep the current value list
+            if cell_id_pair in self.combobox_cell_values:
+                self._editing_combobox_values = self.combobox_cell_values[
+                    cell_id_pair
+                ]
+            elif row_id in self.combobox_row_values:
+                self._editing_combobox_values = self.combobox_row_values[row_id]
+            elif column_id in self.combobox_column_values:
+                self._editing_combobox_values = self.combobox_column_values[
+                    column_id
+                ]
+            else:
+                self._editing_combobox_values = []
+
+            # Configure the Combobox widget
+            self.combobox.delete(0, "end")
+            self.combobox.insert(0, cell_value)
+            self.combobox["values"] = self._editing_combobox_values
+
+            self.combobox.place(x=x, y=y, width=width, height=height)
+            self.combobox.focus_set()
+        elif cell_type == CellType.ENTRY:
+            # Configure the Entry widget
+            self.entry.delete(0, "end")
+            self.entry.insert(0, cell_value)
+            self.entry.place(x=x, y=y, width=width, height=height)
+            self.entry.focus_set()
+
+    def is_valid_cell(self, cell_id_pair: tuple) -> bool:
+        """
+        Check whether a cell exists.
+
+        Parameters
+        ----------
+        cell_id_pair : tuple
+            Pair of (row ID, column ID).
+
+        Returns
+        -------
+        bool
+            True if the cell is valid, otherwise False.
+
+        """
+        row_id, column_id = cell_id_pair
+        try:
+            col_index = _colid2colindex(column_id)  # Convert column ID to index
+        except (ValueError, IndexError):  # pragma: no cover
+            return False  # pragma: no cover
+
+        if row_id not in self.get_children() or col_index >= len(
+            self["columns"]
+        ):
+            return False
+
+        return True
+
+    def _on_return(self, event):  # pylint: disable=unused-argument
+        """Handle the <Return> event."""
+        if self._editing_cell:
+            widget = event.widget
+            self.update_cell(self._editing_cell, widget)
+
+    def _on_focus_out(self, event):  # pylint: disable=unused-argument
+        """Handle the <FocusOut> event."""
+        if self._editing_cell:
+            widget = event.widget
+            self.update_cell(self._editing_cell, widget)
+
+    def _on_escape(self, event):  # pylint: disable=unused-argument
+        """Handle the <Escape> event."""
+        self.cancel_edit()
+
+    def _on_combobox_selected(self, event):  # pylint: disable=unused-argument
+        """Handle combobox selection events."""
+        if self._editing_cell:
+            widget = event.widget
+            self.update_cell(self._editing_cell, widget)
+
+    def _get_cell_type(self, cell_id_pair: tuple) -> CellType:
+        """
+        Determine a cell type.
+
+        Parameters
+        ----------
+        cell_id_pair : tuple
+            Pair of (row ID, column ID).
+
+        Returns
+        -------
+        CellType
+            CellType.READONLY, CellType.COMBOBOX, or CellType.ENTRY.
+
+        """
+        row_id, column_id = cell_id_pair
+
+        # Check read-only settings
+        if (
+            row_id in self.readonly_rows
+            or column_id in self.readonly_columns
+            or cell_id_pair in self.readonly_cells
+        ):
+            return CellType.READONLY
+
+        # Check combobox settings
+        if (
+            row_id in self.combobox_rows
+            or column_id in self.combobox_columns
+            or cell_id_pair in self.combobox_cells
+        ):
+            return CellType.COMBOBOX
+
+        return CellType.ENTRY
+
+    def update_cell(
+        self, cell_id_pair: tuple, widget: Union[Entry, Combobox]
+    ) -> None:
+        """Update a cell value."""
+        if not self.is_valid_cell(cell_id_pair):
+            raise ValueError(f"Invalid cell specified: {cell_id_pair}")
+
+        cell_type = self._get_cell_type(cell_id_pair)
+
+        # Do not update when the cell is read-only
+        if cell_type == CellType.READONLY:
+            self.cancel_edit()
+            return
+
+        # Update value for ENTRY or COMBOBOX cells
+        if cell_type == CellType.ENTRY or cell_type == CellType.COMBOBOX:
+            # Get the new value
+            new_value = widget.get()
+            # Update only when the value changed
+            if new_value != self.get_cell_value(cell_id_pair):
+                values = list(self.item(cell_id_pair[0], "values"))
+                col_index = _colid2colindex(cell_id_pair[1])
+                values[col_index] = new_value
+                self.item(cell_id_pair[0], values=values)
+
+        self.cancel_edit()
+
+    def cancel_edit(self):
+        """
+        Cancel editing.
+
+        Returns
+        -------
+        None.
+
+        """
+        self.entry.place_forget()  # Hide Entry
+        self.combobox.place_forget()  # Hide Combobox
+        self._editing_cell = None
+        self._editing_combobox_values = None
+
+    def set_readonly_row(self, row_id: str, readonly: bool = True) -> None:
+        """Set a row as read-only."""
+        if readonly:
+            self.readonly_rows.add(row_id)
+        else:
+            self.readonly_rows.discard(row_id)
+
+    def set_readonly_column(
+        self, column_id: str, readonly: bool = True
+    ) -> None:
+        """Set a column as read-only."""
+        if readonly:
+            self.readonly_columns.add(column_id)
+        else:
+            self.readonly_columns.discard(column_id)
+
+    def set_readonly_cell(
+        self, cell_id_pair: tuple, readonly: bool = True
+    ) -> None:
+        """Set a cell as read-only."""
+        if readonly:
+            self.readonly_cells.add(cell_id_pair)
+        else:
+            self.readonly_cells.discard(cell_id_pair)
+
+    def set_combobox_row(
+        self, row_id: str, values: list | None = None, is_combobox: bool = True
+    ) -> None:
+        """Set a row to use a combobox."""
+        if is_combobox:
+            self.combobox_rows.add(row_id)
+            if values is not None:
+                self.combobox_row_values[row_id] = values
+        else:
+            self.combobox_rows.discard(row_id)
+            self.combobox_row_values.pop(row_id, None)
+
+    def set_combobox_column(
+        self,
+        column_id: str,
+        values: list | None = None,
+        is_combobox: bool = True,
+    ) -> None:
+        """Set a column to use a combobox."""
+        if is_combobox:
+            self.combobox_columns.add(column_id)
+            if values is not None:
+                self.combobox_column_values[column_id] = values
+        else:
+            self.combobox_columns.discard(column_id)
+            self.combobox_column_values.pop(column_id, None)
+
+    def set_combobox_cell(
+        self,
+        cell_id_pair: tuple,
+        values: list | None = None,
+        is_combobox: bool = True,
+    ) -> None:
+        """Set a cell to use a combobox."""
+        if is_combobox:
+            self.combobox_cells.add(cell_id_pair)
+            if values is not None:
+                self.combobox_cell_values[cell_id_pair] = values
+        else:
+            self.combobox_cells.discard(cell_id_pair)
+            self.combobox_cell_values.pop(cell_id_pair, None)

treeviewex-1.0.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: treeviewex
+Version: 1.0.0
+Summary: A TreeView extension for Tkinter
+Project-URL: Homepage, https://github.com/fangface-hub/treeviewex
+Project-URL: Repository, https://github.com/fangface-hub/treeviewex
+Project-URL: Issues, https://github.com/fangface-hub/treeviewex/issues
+Author: fangface
+License: MIT
+License-File: LICENSE
+Keywords: tkinter,treeview,ui
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# TreeviewEx
+
+[日本語](README_ja.md)
+
+Treeview extension for Tkinter.
+
+This package adds the following features to the standard tkinter Treeview:
+
+- Vertical and horizontal scroll bars
+- Cell editing
+- Read-only settings for rows, columns, and cells
+
+All other behavior is the same as the standard tkinter Treeview.
+
+---
+
+## Testing
+
+1. Install dependencies
+
+   ```bash
+   uv sync --group dev
+   ```
+
+2. Run the tests
+
+   ```bash
+   uv run pytest -q
+   ```
+
+3. Show coverage report
+
+   ```bash
+   uv run coverage run -m pytest -q
+   uv run coverage report -m
+   ```
+
+4. Generate an HTML report (optional)
+
+   ```bash
+   uv run coverage html
+   ```
+
+---
+
+## Build
+
+1. Install dependencies
+
+   ```bash
+   uv sync --group dev
+   ```
+
+2. Build the package
+
+   ```bash
+   uv build
+   ```
+
+3. Check the generated wheel in the dist folder
+
+---
+
+## Usage
+
+1. Install the package
+
+   ```bash
+   uv pip install path/to/TreeviewEx.whl
+   ```
+
+2. Run the sample
+
+   ```bash
+   uv run python sample/sample.py
+   ```
+
+Example:
+
+```python
+from treeviewex import TreeviewEx
+from tkinter import Tk
+
+root = Tk()
+root.title("TreeviewEx Example")
+
+treeview_ex = TreeviewEx(root)
+treeview_ex.grid(row=0, column=0, sticky="nsew")
+
+columns = ("col1", "col2", "col3", "col4")
+treeview_ex["columns"] = columns
+treeview_ex.heading("#0", text="", anchor="w")
+treeview_ex.column("#0", width=0, stretch=False)
+for col in columns:
+    treeview_ex.heading(col, text=f"{col.capitalize()}")
+    treeview_ex.column(col, width=100)
+
+for i in range(100):
+    treeview_ex.insert(
+        "",
+        "end",
+        text="",
+        values=(f"Value {i}A", f"Value {i}B", f"Value {i}C", f"Value {i}D"),
+    )
+
+root.grid_rowconfigure(0, weight=1)
+root.grid_columnconfigure(0, weight=1)
+
+root.mainloop()
+```
+
+---
+
+## Public interfaces
+
+### set_readonly_row(row_id: str, readonly: bool = True) -> None
+
+Set the specified row to readonly.
+
+### set_readonly_column(column_id: str, readonly: bool = True) -> None
+
+Set the specified column to readonly.
+
+### set_readonly_cell(cell_id_pair: tuple, readonly: bool = True) -> None
+
+Set the specified cell to readonly.
+
+### set_combobox_row(row_id: str, values: list = None, is_combobox: bool = True) -> None
+
+Set the specified row to be editable with a Combobox.
+
+### set_combobox_column(column_id: str, values: list = None, is_combobox: bool = True) -> None
+
+Set the specified column to be editable with a Combobox.
+
+### set_combobox_cell(cell_id_pair: tuple, values: list = None, is_combobox: bool = True) -> None
+
+Set the specified cell to be editable with a Combobox.
+
+---
+
+## License
+
+This project is licensed under the MIT License.

treeviewex-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+treeviewex/__init__.py,sha256=nBsuFVnD6AqRyBqmp-d8a6MG-lVR7IZLEGOOetCgXfg,86
+treeviewex/treeviewex.py,sha256=XrYvhH9eNACXt8JAyykC8nT9EnQCOaH9PsuuuvmNg-s,16838
+treeviewex-1.0.0.dist-info/METADATA,sha256=wf1_xn9tYHI8piyJ1l9YeP6mcEb-5ZA4YEMIANyUQbc,3089
+treeviewex-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+treeviewex-1.0.0.dist-info/licenses/LICENSE,sha256=CIAHTomy63TLfdjZOibgqUQd6-IEmm7raWIxEqizNo8,1065
+treeviewex-1.0.0.dist-info/RECORD,,

treeviewex-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

treeviewex-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 fangface
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.