bootstack 0.1.0a1__py3-none-any.whl

bootstack/widgets/primitives/gridframe.py

@@ -0,0 +1,479 @@
+from __future__ import annotations
+
+import tkinter as tk
+from typing import Literal, Optional, Any, Union
+
+from bootstack.widgets.primitives.frame import Frame
+from bootstack.widgets.mixins.configure_mixin import configure_delegate
+from bootstack.widgets.types import Master
+
+Direction = Literal["vertical", "horizontal", "row", "column", "row-reverse", "column-reverse"]
+Fill = Literal["none", "x", "y", "both"]
+Side = Literal["top", "bottom", "left", "right"]
+Anchor = Literal["n", "ne", "e", "se", "s", "sw", "w", "nw", "center"]
+Sticky = Literal["n", "s", "e", "w", "ns", "ew", "nsew", "ne", "nw", "se", "sw", "nse", "nsw", "new", "sew", ""]
+AutoFlow = Literal["row", "column", "row-dense", "column-dense", "none"]
+Gap = Union[int, tuple[int, int]]
+
+
+def _parse_size(value: Union[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.
+
+    Example:
+        ```python
+        frame = GridFrame(columns=3, gap=10, sticky_items="nsew")
+        Label(frame, text="A").grid()  # auto-placed at row=0, col=0
+        Label(frame, text="B").grid()  # auto-placed at row=0, col=1
+        Label(frame, text="C").grid()  # auto-placed at row=0, col=2
+        Label(frame, text="D").grid()  # auto-placed at row=1, col=0
+        Label(frame, text="Wide").grid(columnspan=2)  # spans 2 columns
+        ```
+    """
+
+    def __init__(
+        self,
+        master: Master = None,
+        *,
+        rows: Optional[Union[int, list[Union[int, str]]]] = None,
+        columns: Optional[Union[int, list[Union[int, str]]]] = None,
+        gap: Gap = 0,
+        sticky_items: Optional[Sticky] = None,
+        propagate: Optional[bool] = None,
+        auto_flow: AutoFlow = "row",
+        **kwargs: Any,
+    ) -> 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'`.
+            **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()
+
+        # 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
+        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):
+            self.columnconfigure(i, weight=weight, minsize=minsize)
+
+        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 _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.
+        """
+        # 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)
+            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)))
+
+    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: Optional[int] = None,
+        pad: Optional[int] = None,
+    ) -> None:
+        """Configure a row's properties."""
+        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: Optional[int] = None,
+        pad: Optional[int] = None,
+    ) -> None:
+        """Configure a column's properties."""
+        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/primitives/label.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any, Literal, TYPE_CHECKING, TypedDict
+
+from typing_extensions import Unpack
+
+from bootstack.core.mixins.ttk_state import TtkStateMixin
+from bootstack.core.mixins.widget import WidgetCapabilitiesMixin
+from bootstack.widgets.internal.wrapper_base import TTKWrapperBase
+from bootstack.widgets.mixins import IconMixin, LocalizationMixin, TextSignalMixin
+from bootstack.widgets.types import Master
+
+if TYPE_CHECKING:
+    from bootstack.core.signals import Signal
+
+
+class LabelKwargs(TypedDict, total=False):
+    # Standard ttk.Label options
+    text: Any
+    image: Any
+    icon: Any
+    icon_only: bool
+    compound: Literal['text', 'image', 'top', 'bottom', 'left', 'right', 'center', 'none'] | str
+    anchor: Any
+    justify: Any
+    padding: Any
+    width: int
+    wraplength: Any
+    font: Any
+    foreground: str
+    background: str
+    relief: Any
+    localize: bool | Literal['auto']
+    value_format: dict | str
+    state: Literal['normal', 'active', 'disabled', 'readonly'] | str
+    takefocus: Any
+    format_spec: str | dict
+    style: str
+    class_: str
+    cursor: str
+    name: str
+    textvariable: Any
+    textsignal: Signal[str]
+
+    # bootstack-specific extensions
+    bootstyle: str  # DEPRECATED: Use accent and variant instead
+    accent: str
+    variant: str
+    surface: str
+    style_options: dict[str, Any]
+
+
+class Label(LocalizationMixin, TextSignalMixin, IconMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Label):
+    """bootstack wrapper for `ttk.Label` with bootstyle 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 (str): Text to display in the label.
+            textvariable (Variable): Tk variable linked to the label text.
+            textsignal (Signal[str]): Reactive Signal linked to the label text (auto-synced with textvariable).
+            image (PhotoImage): Image to display.
+            icon (str | dict): Theme-aware icon spec handled by the style system.
+            icon_only (bool): If True, removes the additional padding reserved for label text.
+            compound (str): Placement of the image relative to text.
+            anchor (str): Alignment of the label's content within its area.
+            justify (str): How to justify multiple lines of text.
+            localize (bool | Literal['auto']): Determines the widget's localization mode.
+            value_format (str | dict): Format specification for the label value.
+            padding (int | tuple): Extra space around the label content.
+            width (int): Width of the label in characters.
+            wraplength (int): Maximum width before wrapping text.
+            font (str | Font): Font for text.
+            foreground (str): Text color.
+            background (str): Background color.
+            relief (str): Border style.
+            state (str): Widget state.
+            takefocus (bool): Whether the widget participates in focus traversal.
+            style (str): Explicit ttk style name (overrides accent/variant).
+            accent (str): Accent token for styling, e.g. 'primary', 'danger', 'success'.
+            variant (str): Style variant, e.g. 'default', 'inverse'.
+            bootstyle (str): DEPRECATED - Use `accent` and `variant` instead.
+                Combined style tokens (e.g., 'secondary', 'info').
+            surface (str): Optional surface token; otherwise inherited.
+            style_options (dict): 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/primitives/labelframe.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any, Literal, TypedDict
+
+from typing_extensions import Unpack
+
+from bootstack.core.mixins.ttk_state import TtkStateMixin
+from bootstack.core.mixins.widget import WidgetCapabilitiesMixin
+from bootstack.widgets.internal.wrapper_base import TTKWrapperBase
+from bootstack.widgets.mixins import LocalizationMixin
+from bootstack.widgets.types import Master
+
+
+class LabelFrameKwargs(TypedDict, total=False):
+    # Standard ttk.Labelframe options
+    text: Any
+    labelanchor: Any
+    padding: Any
+    relief: Any
+    borderwidth: Any
+    width: int
+    height: int
+    style: str
+    class_: str
+    cursor: str
+    name: str
+
+    # bootstack-specific extensions
+    bootstyle: str  # DEPRECATED: Use accent and variant instead
+    accent: str
+    surface: str
+    style_options: dict[str, Any]
+    localize: bool | Literal['auto']
+
+
+class LabelFrame(LocalizationMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.LabelFrame):
+    """bootstack wrapper for `ttk.Labelframe` with bootstyle 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 (str): Text for the embedded label.
+            labelanchor (str): Position of the label relative to the frame.
+            padding (int | tuple): Extra internal padding.
+            relief (str): Border style.
+            borderwidth (int): Border width.
+            width (int): Requested width in pixels.
+            height (int): Requested height in pixels.
+            style (str): Explicit ttk style name (overrides accent/variant).
+            accent (str): Accent token for styling, e.g. 'primary', 'secondary'.
+            bootstyle (str): DEPRECATED - Use `accent` instead.
+            surface (str): Optional surface token; otherwise inherited.
+            style_options (dict): Optional dict forwarded to the style builder.
+            localize (bool | Literal['auto']): Determines the widget's localization mode.
+        """
+        super().__init__(master, **kwargs)