bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_impl/primitives/gridframe.py

@@ -0,0 +1,546 @@
+from __future__ import annotations
+
+import tkinter as tk
+from typing import Any, Literal
+
+from typing_extensions import Unpack
+
+from bootstack.widgets._impl.primitives.frame import Frame, FrameKwargs
+from bootstack.widgets._impl.mixins.configure_mixin import configure_delegate
+from bootstack.widgets.types import Master, Sticky
+
+AutoFlow = Literal["row", "column", "row-dense", "column-dense", "none"]
+Gap = int | tuple[int, int]
+
+
+def _parse_size(value: int | str) -> tuple[int, int]:
+    """Parse size value into (weight, minsize) tuple."""
+    if isinstance(value, int):
+        return value, 0
+    if isinstance(value, str):
+        if value == "auto":
+            return 0, 0
+        if value.endswith("px"):
+            try:
+                return 0, int(value[:-2])
+            except ValueError:
+                return 0, 0
+    return 0, 0
+
+
+class GridFrame(Frame):
+    """A Frame with simplified grid-based layout management and auto-placement.
+
+    GridFrame extends the bootstack Frame with automatic grid-based
+    layout management, including support for row/column definitions,
+    gap spacing, auto-placement, and default sticky behavior.
+
+    Children gridded into this frame automatically receive the frame's
+    default layout options. Simply use the standard `grid()` method
+    on child widgets — no special `add()` method is needed.
+
+    """
+
+    def __init__(
+        self,
+        master: Master = None,
+        *,
+        rows: int | list[int | str] | None = None,
+        columns: int | list[int | str] | None = None,
+        gap: Gap = 0,
+        sticky_items: Sticky | None = None,
+        propagate: bool | None = None,
+        auto_flow: AutoFlow = "row",
+        **kwargs: Unpack[FrameKwargs],
+    ) -> None:
+        """Create a GridFrame with automatic grid-based layout.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            rows: Number of rows as an `int`, or a list of size specs where each
+                spec is an `int` weight or a string such as `'auto'` or `'100px'`.
+            columns: Number of columns or a list of size specs (same format as `rows`).
+            gap: Spacing between cells. An `int` applies the same gap in both
+                directions; a `(col_gap, row_gap)` tuple sets them independently.
+            sticky_items: Default `sticky` value applied to all children when
+                they call `grid()`. If None, no default sticky is applied.
+            propagate: If False, the frame will not resize to fit its contents.
+                Defaults to None (Tk default behaviour).
+            auto_flow: Auto-placement mode — `'row'` (default), `'column'`,
+                `'row-dense'`, `'column-dense'`, or `'none'`.
+
+        Other Parameters:
+            **kwargs: Additional keyword arguments forwarded to `Frame`.
+        """
+        super().__init__(master, **kwargs)
+
+        self._gap = self._normalize_gap(gap)
+        self._default_sticky = sticky_items
+        self._auto_flow = auto_flow
+
+        # Track managed widgets: list of (widget, user_options, computed_position)
+        # computed_position is (row, col, rowspan, colspan)
+        self._managed: list[tuple[tk.Widget, dict[str, Any], tuple[int, int, int, int]]] = []
+
+        # Track occupied cells for auto-placement
+        self._occupied: set[tuple[int, int]] = set()
+
+        # Track widgets hidden via grid_remove (still managed, just hidden)
+        self._removed: set[tk.Widget] = set()
+
+        # Set when a managed child is destroyed out-of-band (Tk destroy()
+        # bypasses grid_forget). Gates the O(N) prune scan so a pure build —
+        # adds with no destroys — never pays for it, keeping construction O(N).
+        self._needs_prune = False
+
+        # Auto-placement cursor
+        self._next_row = 0
+        self._next_col = 0
+
+        # Parse and store row/column definitions
+        self._row_defs: list[tuple[int, int]] = []
+        self._col_defs: list[tuple[int, int]] = []
+
+        if isinstance(rows, int):
+            self._row_defs = [(1, 0)] * rows
+        elif isinstance(rows, list):
+            self._row_defs = [_parse_size(r) for r in rows]
+
+        if isinstance(columns, int):
+            self._col_defs = [(1, 0)] * columns
+        elif isinstance(columns, list):
+            self._col_defs = [_parse_size(c) for c in columns]
+
+        # Apply initial row/column configuration.
+        # Weighted columns use a uniform group keyed by weight so that all
+        # equal-weight columns are exactly the same width regardless of their
+        # children's minimum sizes. Auto/fixed-px columns are not grouped.
+        for i, (weight, minsize) in enumerate(self._row_defs):
+            self.rowconfigure(i, weight=weight, minsize=minsize)
+        for i, (weight, minsize) in enumerate(self._col_defs):
+            kw: dict[str, Any] = {"weight": weight, "minsize": minsize}
+            if weight > 0:
+                kw["uniform"] = f"col_w{weight}"
+            self.columnconfigure(i, **kw)
+
+        if propagate is not None:
+            self.grid_propagate(propagate)
+
+    @staticmethod
+    def _normalize_gap(gap: Gap) -> tuple[int, int]:
+        """Normalize gap to (column_gap, row_gap) tuple."""
+        if isinstance(gap, int):
+            return gap, gap
+        return gap
+
+    @property
+    def _column_gap(self) -> int:
+        """Get the column gap."""
+        return self._gap[0]
+
+    @property
+    def _row_gap(self) -> int:
+        """Get the row gap."""
+        return self._gap[1]
+
+    @configure_delegate('gap')
+    def _delegate_gap(self, value=None) -> tuple[int, int]:
+        """Get or set the gap between cells."""
+        if value is None:
+            return self._gap
+        self._gap = self._normalize_gap(value)
+        # Regrid all widgets with new gap
+        self._regrid_all()
+
+    @property
+    def _num_columns(self) -> int:
+        """Number of defined columns, or a large default for auto-placement."""
+        return len(self._col_defs) if self._col_defs else 100
+
+    @property
+    def _num_rows(self) -> int:
+        """Number of defined rows, or a large default for auto-placement."""
+        return len(self._row_defs) if self._row_defs else 100
+
+    def _is_area_free(self, row: int, col: int, rowspan: int, colspan: int) -> bool:
+        """Check if a rectangular area is free."""
+        return all(
+            (row + dr, col + dc) not in self._occupied
+            for dr in range(rowspan)
+            for dc in range(colspan)
+        )
+
+    def _occupy_area(self, row: int, col: int, rowspan: int, colspan: int) -> None:
+        """Mark a rectangular area as occupied."""
+        for dr in range(rowspan):
+            for dc in range(colspan):
+                self._occupied.add((row + dr, col + dc))
+
+    def _free_area(self, row: int, col: int, rowspan: int, colspan: int) -> None:
+        """Mark a rectangular area as free."""
+        for dr in range(rowspan):
+            for dc in range(colspan):
+                self._occupied.discard((row + dr, col + dc))
+
+    def _prune_destroyed(self) -> None:
+        """Drop managed widgets that have been destroyed, freeing their cells.
+
+        Tk's `destroy()` does not route through `grid_forget()`, so without this
+        the auto-flow cursor and the occupied-cell set would keep stale entries
+        for gone widgets — causing re-added children to fall through to the
+        `(0, 0)` fallback and stack on top of one another.
+        """
+        survivors = []
+        pruned = False
+        for entry in self._managed:
+            widget = entry[0]
+            try:
+                alive = bool(widget.winfo_exists())
+            except Exception:
+                alive = False
+            if alive:
+                survivors.append(entry)
+            else:
+                self._free_area(*entry[2])
+                self._removed.discard(widget)
+                pruned = True
+        if pruned:
+            self._managed = survivors
+            # Restart the flow cursor; `_find_next_position` skips cells still
+            # occupied by survivors, so it lands on the first genuinely free one.
+            self._next_row = 0
+            self._next_col = 0
+
+    def _find_next_position(self, rowspan: int = 1, colspan: int = 1) -> tuple[int, int]:
+        """Find the next available position using auto-flow rules."""
+        if self._auto_flow == "none":
+            return 0, 0
+
+        max_cols = self._num_columns
+        max_rows = self._num_rows
+
+        if "dense" in self._auto_flow:
+            # Dense packing: search from (0,0)
+            if self._auto_flow == "row-dense":
+                for r in range(max_rows):
+                    for c in range(max_cols - colspan + 1):
+                        if self._is_area_free(r, c, rowspan, colspan):
+                            return r, c
+            else:  # column-dense
+                for c in range(max_cols):
+                    for r in range(max_rows - rowspan + 1):
+                        if self._is_area_free(r, c, rowspan, colspan):
+                            return r, c
+        else:
+            # Normal flow: continue from cursor
+            if self._auto_flow == "row":
+                r, c = self._next_row, self._next_col
+                while r < max_rows:
+                    while c <= max_cols - colspan:
+                        if self._is_area_free(r, c, rowspan, colspan):
+                            # Update cursor for next placement
+                            next_c = c + colspan
+                            if self._col_defs and next_c >= len(self._col_defs):
+                                self._next_row = r + 1
+                                self._next_col = 0
+                            else:
+                                self._next_row = r
+                                self._next_col = next_c
+                            return r, c
+                        c += 1
+                    r += 1
+                    c = 0
+            else:  # column
+                r, c = self._next_row, self._next_col
+                while c < max_cols:
+                    while r <= max_rows - rowspan:
+                        if self._is_area_free(r, c, rowspan, colspan):
+                            # Update cursor for next placement
+                            next_r = r + rowspan
+                            if self._row_defs and next_r >= len(self._row_defs):
+                                self._next_col = c + 1
+                                self._next_row = 0
+                            else:
+                                self._next_col = c
+                                self._next_row = next_r
+                            return r, c
+                        r += 1
+                    c += 1
+                    r = 0
+
+        return 0, 0  # Fallback
+
+    def _compute_gap_padding(
+        self, row: int, col: int, user_padx: Any = None, user_pady: Any = None
+    ) -> dict[str, Any]:
+        """Compute padding that includes gap for non-first rows/columns."""
+        result: dict[str, Any] = {}
+
+        # Handle column gap (padx)
+        if col > 0 and self._column_gap:
+            gap_padx = (self._column_gap, 0)
+            if user_padx is not None:
+                result["padx"] = self._merge_padding(gap_padx, user_padx)
+            else:
+                result["padx"] = gap_padx
+        elif user_padx is not None:
+            result["padx"] = user_padx
+
+        # Handle row gap (pady)
+        if row > 0 and self._row_gap:
+            gap_pady = (self._row_gap, 0)
+            if user_pady is not None:
+                result["pady"] = self._merge_padding(gap_pady, user_pady)
+            else:
+                result["pady"] = gap_pady
+        elif user_pady is not None:
+            result["pady"] = user_pady
+
+        return result
+
+    @staticmethod
+    def _merge_padding(
+        gap_pad: tuple[int, int], user_pad: Any
+    ) -> tuple[int, int]:
+        """Merge gap padding with user padding."""
+        if isinstance(user_pad, int):
+            return (gap_pad[0] + user_pad, user_pad)
+        elif isinstance(user_pad, (tuple, list)) and len(user_pad) == 2:
+            return (gap_pad[0] + user_pad[0], user_pad[1])
+        return gap_pad
+
+    def _build_options(
+        self,
+        row: int,
+        col: int,
+        rowspan: int,
+        colspan: int,
+        user_options: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Build final grid options."""
+        options: dict[str, Any] = {
+            "in_": self,
+            "row": row,
+            "column": col,
+        }
+
+        if rowspan > 1:
+            options["rowspan"] = rowspan
+        if colspan > 1:
+            options["columnspan"] = colspan
+
+        # Apply gap padding
+        gap_padding = self._compute_gap_padding(
+            row, col,
+            user_options.get("padx"),
+            user_options.get("pady")
+        )
+        options.update(gap_padding)
+
+        # Apply default sticky
+        if self._default_sticky and "sticky" not in user_options:
+            options["sticky"] = self._default_sticky
+
+        # User options override (except padx/pady which we handled)
+        for key, value in user_options.items():
+            if key not in ("padx", "pady", "row", "column"):
+                options[key] = value
+
+        return options
+
+    def _regrid_all(self) -> None:
+        """Remove and re-grid all widgets."""
+        # Ungrid all (except those in _removed which are already hidden)
+        for widget, _, _ in self._managed:
+            if widget not in self._removed:
+                tk.Grid.forget(widget)
+
+        # Clear and rebuild occupied set
+        self._occupied.clear()
+        self._next_row = 0
+        self._next_col = 0
+
+        # Regrid in order, recalculating positions
+        new_managed: list[tuple[tk.Widget, dict[str, Any], tuple[int, int, int, int]]] = []
+
+        for widget, user_options, _ in self._managed:
+            rowspan = int(user_options.get("rowspan", 1))
+            colspan = int(user_options.get("columnspan", 1))
+
+            # Check if user specified explicit position
+            explicit_row = user_options.get("row")
+            explicit_col = user_options.get("column")
+
+            if explicit_row is not None and explicit_col is not None:
+                row, col = int(explicit_row), int(explicit_col)
+            else:
+                row, col = self._find_next_position(rowspan, colspan)
+
+            self._occupy_area(row, col, rowspan, colspan)
+            new_managed.append((widget, user_options, (row, col, rowspan, colspan)))
+
+            # Only configure visible widgets (not those in _removed)
+            if widget not in self._removed:
+                options = self._build_options(row, col, rowspan, colspan, user_options)
+                tk.Grid.configure(widget, **options)
+
+        self._managed = new_managed
+
+    def _find_widget_index(self, widget: tk.Widget) -> int:
+        """Find index of widget in managed list, return -1 if not found."""
+        for i, (w, _, _) in enumerate(self._managed):
+            if w is widget:
+                return i
+        return -1
+
+    # -------------------------------------------------------------------------
+    # Hook methods called by GridMixin
+    # -------------------------------------------------------------------------
+
+    def _on_child_grid(self, widget: tk.Widget, **options: Any) -> None:
+        """Hook called when a child widget calls grid().
+
+        Applies frame defaults, handles gap spacing, auto-placement, and tracks the widget.
+        """
+        # Reclaim cells from any children destroyed since the last placement so
+        # auto-flow positions this widget correctly (Tk destroy() bypasses
+        # grid_forget()). Only scan when a destroy actually flagged it.
+        if self._needs_prune:
+            self._prune_destroyed()
+            self._needs_prune = False
+
+        # Check if widget was hidden via grid_remove and is being restored
+        if widget in self._removed and not options:
+            # Restore widget to its original position
+            self._removed.discard(widget)
+            idx = self._find_widget_index(widget)
+            if idx >= 0:
+                _, user_options, (row, col, rowspan, colspan) = self._managed[idx]
+                grid_options = self._build_options(row, col, rowspan, colspan, user_options)
+                tk.Grid.configure(widget, **grid_options)
+                return
+
+        # Check if widget is already managed (reconfigure case)
+        existing_idx = self._find_widget_index(widget)
+
+        rowspan = int(options.get("rowspan", 1))
+        colspan = int(options.get("columnspan", 1))
+
+        # Check if user specified explicit position
+        explicit_row = options.get("row")
+        explicit_col = options.get("column")
+
+        if existing_idx >= 0:
+            # Widget already managed - update its options and regrid all
+            _, _, old_pos = self._managed[existing_idx]
+            self._free_area(*old_pos)
+            self._managed[existing_idx] = (widget, options, (0, 0, 1, 1))  # temp position
+            self._regrid_all()
+        else:
+            # New widget
+            if explicit_row is not None and explicit_col is not None:
+                row, col = int(explicit_row), int(explicit_col)
+            else:
+                row, col = self._find_next_position(rowspan, colspan)
+
+            self._occupy_area(row, col, rowspan, colspan)
+            # Rows that weren't pre-defined via `rows=` keep Tk's default weight
+            # of 0 — matching undefined columns — so an auto-flow grid stays
+            # content-sized instead of dividing its parent's height among its
+            # rows. Pass `rows=[1, ...]` to make a row stretch.
+            grid_options = self._build_options(row, col, rowspan, colspan, options)
+            tk.Grid.configure(widget, **grid_options)
+            self._managed.append((widget, options, (row, col, rowspan, colspan)))
+            # Flag a prune when this child is destroyed out-of-band, so the
+            # next placement reclaims its cell without scanning on every add.
+            widget.bind(
+                "<Destroy>",
+                lambda e, w=widget: self._flag_prune(e, w),
+                add="+",
+            )
+
+    def _flag_prune(self, event: tk.Event, widget: tk.Widget) -> None:
+        """Mark the frame for a prune when one of its managed children dies."""
+        if event.widget is widget:
+            self._needs_prune = True
+
+    def _on_child_grid_forget(self, widget: tk.Widget) -> None:
+        """Hook called when a child widget calls grid_forget().
+
+        Removes widget from tracking and frees its occupied area.
+        """
+        idx = self._find_widget_index(widget)
+        if idx < 0:
+            # Not managed by us, just forget it normally
+            tk.Grid.forget(widget)
+            return
+
+        _, _, (row, col, rowspan, colspan) = self._managed[idx]
+        tk.Grid.forget(widget)
+        self._free_area(row, col, rowspan, colspan)
+        self._managed.pop(idx)
+        self._removed.discard(widget)  # Clean up if it was in removed set
+
+    def _on_child_grid_remove(self, widget: tk.Widget) -> None:
+        """Hook called when a child widget calls grid_remove().
+
+        Hides widget but keeps its configuration for later restore via grid().
+        The widget's position is preserved so it can be restored with grid().
+        """
+        idx = self._find_widget_index(widget)
+        if idx < 0:
+            # Not managed by us, just remove it normally
+            tk.Grid.grid_remove(widget)
+            return
+
+        # Hide the widget but keep it in _managed for position restoration
+        tk.Grid.grid_remove(widget)
+        self._removed.add(widget)
+
+    # -------------------------------------------------------------------------
+    # Public configuration methods
+    # -------------------------------------------------------------------------
+
+    def configure_row(
+        self,
+        index: int,
+        weight: int = 1,
+        minsize: int | None = None,
+        pad: int | None = None,
+    ) -> None:
+        """Configure a row's weight and minimum size.
+
+        Args:
+            index: Row index to configure.
+            weight: Stretch weight. Defaults to 1.
+            minsize: Minimum height in pixels.
+            pad: Extra padding around the row.
+        """
+        kwargs: dict[str, Any] = {"weight": weight}
+        if minsize is not None:
+            kwargs["minsize"] = minsize
+        if pad is not None:
+            kwargs["pad"] = pad
+        self.rowconfigure(index, **kwargs)
+
+    def configure_column(
+        self,
+        index: int,
+        weight: int = 1,
+        minsize: int | None = None,
+        pad: int | None = None,
+    ) -> None:
+        """Configure a column's weight and minimum size.
+
+        Args:
+            index: Column index to configure.
+            weight: Stretch weight. Defaults to 1.
+            minsize: Minimum width in pixels.
+            pad: Extra padding around the column.
+        """
+        kwargs: dict[str, Any] = {"weight": weight}
+        if minsize is not None:
+            kwargs["minsize"] = minsize
+        if pad is not None:
+            kwargs["pad"] = pad
+        self.columnconfigure(index, **kwargs)

bootstack/widgets/_impl/primitives/label.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any, Literal, TYPE_CHECKING
+
+from typing_extensions import Unpack
+
+from bootstack._core.mixins.ttk_state import TtkStateMixin
+from bootstack._core.mixins.widget import WidgetCapabilitiesMixin
+from bootstack.widgets._impl._internal.wrapper_base import TTKWrapperBase
+from bootstack.widgets._impl.mixins import IconMixin, LocalizationMixin, TextSignalMixin
+from bootstack.widgets.types import Master, StyledKwargs, Anchor, Justify, Relief, CompoundMode, WidgetState
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+
+class LabelKwargs(StyledKwargs, total=False):
+    # Standard ttk.Label options
+    text: Any
+    image: Any
+    icon: Any
+    icon_only: bool
+    compound: CompoundMode
+    anchor: Anchor
+    justify: Justify
+    padding: Any
+    width: int
+    wraplength: Any
+    font: Any
+    foreground: str
+    background: str
+    relief: Relief
+    localize: bool | Literal['auto']
+    value_format: dict | str
+    state: WidgetState
+    format_spec: str | dict
+    textvariable: Any
+    textsignal: Signal[str]
+
+    # bootstack-specific extensions
+
+
+class Label(LocalizationMixin, TextSignalMixin, IconMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Label):
+    """bootstack wrapper for `ttk.Label` with themed styling and icon support."""
+
+    _ttk_base = ttk.Label
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[LabelKwargs]) -> None:
+        """Create a themed bootstack Label.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            text: Text to display in the label.
+            textvariable: Tk variable linked to the label text.
+                See [tkinter Variables](https://docs.python.org/3/library/tkinter.html#tkinter-variables).
+            textsignal: Reactive Signal linked to the label text (auto-synced with textvariable).
+            image: Image to display.
+            icon: Theme-aware icon spec handled by the style system.
+            icon_only: If True, removes the additional padding reserved for label text.
+            compound: Placement of the image relative to text.
+            anchor: Alignment of the label's content within its area.
+            justify: How to justify multiple lines of text.
+            localize: Determines the widget's localization mode.
+            value_format: Format specification for the label value.
+            padding: Extra space around the label content.
+            width: Width of the label in characters.
+            wraplength: Maximum width before wrapping text.
+            font: Font for text.
+            foreground: Text color.
+            background: Background color.
+            relief: Border style.
+            state: Widget state.
+            takefocus: Whether the widget participates in focus traversal.
+            style: Explicit ttk style name (overrides accent/variant).
+            accent: Accent token for styling, e.g. 'primary', 'danger', 'success'.
+            variant: Style variant, e.g. 'default', 'inverse'.
+            surface: Optional surface token; otherwise inherited.
+            style_options: Optional dict forwarded to the style builder.
+        """
+        kwargs.update(style_options=self._capture_style_options(['icon_only', 'icon', 'density'], kwargs))
+        super().__init__(master, **kwargs)

bootstack/widgets/_impl/primitives/labelframe.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any, Literal
+
+from typing_extensions import Unpack
+
+from bootstack._core.mixins.ttk_state import TtkStateMixin
+from bootstack._core.mixins.widget import WidgetCapabilitiesMixin
+from bootstack.widgets._impl._internal.wrapper_base import TTKWrapperBase
+from bootstack.widgets._impl.mixins import LocalizationMixin
+from bootstack.widgets.types import Master, StyledKwargs, Relief
+
+
+class LabelFrameKwargs(StyledKwargs, total=False):
+    # Standard ttk.Labelframe options
+    text: Any
+    labelanchor: Any
+    padding: Any
+    relief: Relief
+    borderwidth: Any
+    width: int
+    height: int
+
+    # bootstack-specific extensions
+    localize: bool | Literal['auto']
+
+
+class LabelFrame(LocalizationMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.LabelFrame):
+    """bootstack wrapper for `ttk.Labelframe` with themed styling support."""
+
+    _ttk_base = ttk.Labelframe
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[LabelFrameKwargs]) -> None:
+        """Create a themed bootstack Labelframe.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            text: Text for the embedded label.
+            labelanchor: Position of the label relative to the frame.
+            padding: Extra internal padding.
+            relief: Border style.
+            borderwidth: Border width.
+            width: Requested width in pixels.
+            height: Requested height in pixels.
+            style: Explicit ttk style name (overrides accent/variant).
+            accent: Accent token for styling, e.g. 'primary', 'secondary'.
+            surface: Optional surface token; otherwise inherited.
+            style_options: Optional dict forwarded to the style builder.
+            localize: Determines the widget's localization mode.
+        """
+        super().__init__(master, **kwargs)