bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_impl/primitives/flexframe.py

@@ -0,0 +1,448 @@
+from __future__ import annotations
+
+import tkinter as tk
+from typing import Any
+
+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
+
+
+def _alive(widget: tk.Widget) -> bool:
+    """True if `widget` still exists (Tk `destroy()` leaves dead references)."""
+    try:
+        return bool(widget.winfo_exists())
+    except tk.TclError:
+        return False
+
+
+class FlexFrame(Frame):
+    """A grid-backed 1-D flex container (the engine behind Row and Column).
+
+    Lays children along a single main axis using the Tk *grid* geometry
+    manager. Unlike pack, grid can express whole-group main-axis distribution
+    (`justify`) without phantom spacer widgets — an empty track with a weight
+    claims space on its own. That makes true weighted growth, correct
+    `space-around`, and a `Spacer` element all expressible on one engine.
+
+    Children are added through `add_child`, which appends to an ordered managed
+    list and re-plans the whole layout (`_relayout`). Re-planning on every add
+    is required because `justify`'s phantom tracks and the content-track indices
+    shift as children come and go — the same approach `GridFrame` uses.
+
+    Layout model (HStack == one row, N columns shown; Column transposes):
+
+    - The single cross track always carries `weight=1` so `align`
+      (start/center/end/stretch) has room to position a child even when the
+      container is larger than its content.
+    - `justify` injects phantom weighted tracks *between/around* the content
+      cells (no widget) — only when nothing grows (grow defeats justify).
+    - `grow` / `grow_items` / `weights=` put weight on the *content* tracks.
+    - `Spacer` children occupy a real content track whose weight (flexible) or
+      `minsize` (fixed) is taken from the spacer.
+    - Gap is synthesized with edge-aware leading `padx`/`pady`, skipping the
+      phantom and spacer breaks so it never doubles up around them.
+    """
+
+    def __init__(
+        self,
+        master: Master = None,
+        *,
+        direction: str = "horizontal",
+        horizontal_items: str = "left",
+        vertical_items: str = "top",
+        grow_items: bool = False,
+        weights: list[int] | None = None,
+        gap: int = 0,
+        propagate: bool | None = None,
+        **kwargs: Unpack[FrameKwargs],
+    ) -> None:
+        """Create a FlexFrame.
+
+        The public layout vocabulary is screen-axis based: `horizontal_items` and
+        `vertical_items` set how children sit on the x and y axes (values are edge
+        names — `left`/`right`/`top`/`bottom`/`center`/`stretch`, plus `space-*`
+        for the stacking axis). Internally the frame resolves which screen axis is
+        the *main* (stacking) axis and which is the *cross* axis from `direction`.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            direction: Main axis — `'horizontal'` (a Row) or `'vertical'`
+                (a Column). Defaults to `'horizontal'`.
+            horizontal_items: How children are positioned on the x axis. For a
+                Row (horizontal stacks) this arranges the group
+                (`left`/`center`/`right`/`space-*`); for a Column it aligns each
+                child (`left`/`center`/`right`/`stretch`). Defaults to `'left'`.
+            vertical_items: How children are positioned on the y axis. For a
+                Column (vertical stacks) this arranges the group
+                (`top`/`center`/`bottom`/`space-*`); for a Row it aligns each
+                child (`top`/`center`/`bottom`/`stretch`). Defaults to `'top'`.
+            grow_items: When True, every content child grows equally (uniform)
+                to share the main axis. Defaults to False.
+            weights: Positional shorthand for per-child `grow` —
+                `weights[i]` is the flex-grow weight of content child `i`
+                (share of leftover main-axis space, not a fixed size). Overrides
+                `grow_items` and per-child `grow`; missing trailing entries are
+                0. Defaults to None.
+            gap: Spacing in pixels between adjacent content children. Defaults
+                to 0.
+            propagate: When False, the frame does not resize to fit its
+                children. Defaults to None (Tk default).
+
+        Other Parameters:
+            **kwargs: Additional keyword arguments forwarded to `Frame`.
+        """
+        super().__init__(master, **kwargs)
+        self._direction = direction
+        self._horizontal_items = horizontal_items
+        self._vertical_items = vertical_items
+        self._grow_items = grow_items
+        self._weights = weights
+        self._gap = gap
+        # Ordered (widget, opts) entries. opts may carry: grow, horizontal,
+        # vertical, padx, pady (resolved margins), and spacer metadata
+        # (_spacer, _spacer_size, _spacer_weight).
+        self._managed: list[tuple[tk.Widget, dict[str, Any]]] = []
+        # Highest main-axis track index configured on the previous relayout,
+        # so we can zero stale tracks when the plan shrinks.
+        self._used_main_tracks = 0
+        # Count of managed children carrying `grow` or spacer metadata. Lets the
+        # append fast-path decide in O(1) whether the stack is "pure" (see
+        # `_can_append_in_place`) without rescanning every add.
+        self._flex_child_count = 0
+        if propagate is not None:
+            self.grid_propagate(propagate)
+
+    # ----- direction helpers -------------------------------------------------
+
+    @property
+    def _row_dir(self) -> bool:
+        """True when the main axis is horizontal (columns vary)."""
+        return self._direction in ("horizontal", "row")
+
+    def _main_distribution(self) -> str:
+        """Normalize the stacking-axis value to start/center/end/space-* tokens."""
+        if self._row_dir:
+            value = self._horizontal_items
+            start, end = "left", "right"
+        else:
+            value = self._vertical_items
+            start, end = "top", "bottom"
+        if value == start:
+            return "start"
+        if value == end:
+            return "end"
+        return value  # center, space-between, space-around, space-evenly
+
+    def _cross_default(self) -> str:
+        """The cross-axis (non-stacking) container alignment value."""
+        return self._vertical_items if self._row_dir else self._horizontal_items
+
+    def _cross_sticky(self, value: str) -> str:
+        """Map a cross-axis edge value to Tk sticky chars for this direction."""
+        if value == "stretch":
+            return "ns" if self._row_dir else "ew"
+        if self._row_dir:  # cross axis is vertical
+            if value == "top":
+                return "n"
+            if value == "bottom":
+                return "s"
+        else:  # cross axis is horizontal
+            if value == "left":
+                return "w"
+            if value == "right":
+                return "e"
+        return ""  # center
+
+    def index_of(self, widget: tk.Widget) -> int:
+        """Return the managed index of `widget`, or -1 if not managed."""
+        for i, (w, _) in enumerate(self._managed):
+            if w is widget:
+                return i
+        return -1
+
+    # ----- child management --------------------------------------------------
+
+    def add_child(
+        self, widget: tk.Widget, opts: dict[str, Any], index: int | None = None
+    ) -> None:
+        """Add `widget` to the flow (at `index`, else appended) and re-plan.
+
+        A plain append onto a "pure" start-aligned stack grids only the new
+        child (the fast path) instead of re-planning every sibling, so building
+        an N-child stack is O(N) rather than O(N^2). Anything that can shift a
+        sibling's track — a mid-list insert, a distribution mode, or a
+        grow/spacer child — takes the full `_relayout`.
+        """
+        entry = (widget, dict(opts))
+        appending = index is None or index >= len(self._managed)
+        new_is_flex = bool(opts.get("grow")) or bool(opts.get("_spacer"))
+        # Decide the fast path BEFORE the count reflects this child (the check
+        # asks whether the EXISTING stack is pure).
+        fast = appending and not new_is_flex and self._can_append_in_place()
+        if appending:
+            self._managed.append(entry)
+        else:
+            self._managed.insert(max(index, 0), entry)
+        if new_is_flex:
+            self._flex_child_count += 1
+        if fast:
+            self._grid_appended_plain(widget, opts)
+        else:
+            self._relayout()
+
+    def remove_child(self, widget: tk.Widget) -> None:
+        """Remove `widget` from the flow (grid-forget it) and re-plan."""
+        idx = self.index_of(widget)
+        if idx < 0:
+            return
+        _, removed_opts = self._managed[idx]
+        if removed_opts.get("grow") or removed_opts.get("_spacer"):
+            self._flex_child_count -= 1
+        try:
+            tk.Grid.forget(widget)
+        except tk.TclError:
+            pass
+        self._managed.pop(idx)
+        self._relayout()
+
+    def _can_append_in_place(self) -> bool:
+        """True when appending a plain child cannot move any existing sibling.
+
+        Holds only for a start-aligned stack with no container-level growth and
+        no grow/spacer children: every child then occupies one consecutive
+        track, so a new child simply takes the next one. Any distribution mode
+        (`grow`, `weights`, `grow_items`, a `Spacer`, or a `space-*`/`center`/
+        `end` justify) interleaves phantom tracks or shifts weights and needs a
+        full re-plan. O(1) — `_flex_child_count` avoids a per-add scan.
+        """
+        return (
+            self._flex_child_count == 0
+            and not self._grow_items
+            and self._weights is None
+            and self._main_distribution() == "start"
+        )
+
+    def _grid_appended_plain(self, widget: tk.Widget, opts: dict[str, Any]) -> None:
+        """Grid a single just-appended child, leaving its siblings in place.
+
+        Valid only under `_can_append_in_place`. Mirrors the content-child arm
+        of `_relayout` for the pure case: one track per child, no growth, cross
+        sticky from the child's alignment, and a leading gap after the first.
+        """
+        row_dir = self._row_dir
+        idx = len(self._managed) - 1  # one track per child in the pure case
+        cross_cfg = self.grid_rowconfigure if row_dir else self.grid_columnconfigure
+        main_cfg = self.grid_columnconfigure if row_dir else self.grid_rowconfigure
+        cross_cfg(0, weight=1)        # cross track fills so alignment has room
+        main_cfg(idx, weight=0)
+
+        cross_key = "vertical" if row_dir else "horizontal"
+        cross_val = opts.get(cross_key) or self._cross_default()
+        sticky = self._cross_sticky(cross_val)
+
+        main_axis = "padx" if row_dir else "pady"
+        cross_axis = "pady" if row_dir else "padx"
+        lead = self._gap if idx > 0 else 0
+        trail = 0
+        margin_main = opts.get(main_axis)
+        if isinstance(margin_main, tuple):
+            lead += margin_main[0]
+            trail = margin_main[1]
+        elif margin_main is not None:
+            lead += margin_main
+        pad: dict[str, Any] = {}
+        if lead or trail:
+            pad[main_axis] = (lead, trail)
+        margin_cross = opts.get(cross_axis)
+        if margin_cross is not None:
+            pad[cross_axis] = margin_cross
+
+        self._grid_cell(widget, idx, sticky, pad)
+        self._used_main_tracks = max(self._used_main_tracks, idx)
+
+    # ----- configuration delegates -------------------------------------------
+
+    @configure_delegate('gap')
+    def _delegate_gap(self, value=None) -> int:
+        """Get or set the gap between children."""
+        if value is None:
+            return self._gap
+        self._gap = value
+        self._relayout()
+
+    @configure_delegate('horizontal_items')
+    def _delegate_horizontal_items(self, value=None) -> str:
+        """Get or set how children are positioned on the x axis."""
+        if value is None:
+            return self._horizontal_items
+        self._horizontal_items = value
+        self._relayout()
+
+    @configure_delegate('vertical_items')
+    def _delegate_vertical_items(self, value=None) -> str:
+        """Get or set how children are positioned on the y axis."""
+        if value is None:
+            return self._vertical_items
+        self._vertical_items = value
+        self._relayout()
+
+    # ----- the planner -------------------------------------------------------
+
+    def _grid_cell(
+        self, widget: tk.Widget, idx: int, sticky: str, pad: dict[str, Any]
+    ) -> None:
+        """Place `widget` into main-track `idx` on the single cross track."""
+        opts: dict[str, Any] = {"in_": self, "sticky": sticky, **pad}
+        if self._row_dir:
+            opts.update(row=0, column=idx)
+        else:
+            opts.update(column=0, row=idx)
+        tk.Grid.configure(widget, **opts)
+
+    def _relayout(self) -> None:
+        """Re-plan and re-grid every managed child from scratch."""
+        row_dir = self._row_dir
+        main_cfg = self.grid_columnconfigure if row_dir else self.grid_rowconfigure
+        cross_cfg = self.grid_rowconfigure if row_dir else self.grid_columnconfigure
+
+        # Reposition surviving children IN PLACE — re-gridding an already-gridded
+        # widget (grid_configure) moves it without an unmap/remap, so we must NOT
+        # grid_forget them here: that would fire spurious <Unmap>/<Map> (and thus
+        # on_detach/on_attach) on every sibling whenever one child is added or
+        # removed. A genuinely removed child is grid-forgotten by remove_child
+        # before this runs, so it is already out of self._managed.
+        #
+        # Zero the tracks the previous plan used so a now-shorter plan leaves no
+        # stale weights/minsizes/uniform groups (configuring a track does not
+        # touch the widgets in it).
+        for i in range(self._used_main_tracks + 1):
+            main_cfg(i, weight=0, minsize=0, uniform="")
+        self._used_main_tracks = 0
+
+        # Drop children destroyed out from under us: Tk's destroy() does not route
+        # through remove_child, so a dead child lingers in _managed and re-gridding
+        # it below would raise "bad window path name". (GridFrame guards the same.)
+        if any(not _alive(w) for w, _ in self._managed):
+            self._managed = [e for e in self._managed if _alive(e[0])]
+            self._flex_child_count = sum(
+                1 for _, o in self._managed if o.get("grow") or o.get("_spacer")
+            )
+
+        items = self._managed
+        if not items:
+            return
+
+        # The cross track always fills so align has room to work.
+        cross_cfg(0, weight=1)
+
+        j = self._main_distribution()
+        per_child_grow = any(
+            o.get("grow") for _, o in items if not o.get("_spacer")
+        )
+        has_spacer = any(o.get("_spacer") for _, o in items)
+        any_grow = (
+            self._grow_items
+            or per_child_grow
+            or self._weights is not None
+            or has_spacer
+        )
+        # justify only engages when nothing competes for the main axis.
+        use_just = (not any_grow) and j != "start"
+        uniform_grow = self._grow_items and not per_child_grow and self._weights is None
+
+        # Build a plan of phantom breaks ('p', weight) and content ('c', w, o).
+        plan: list[tuple] = []
+        if use_just and j in ("end", "center", "space-evenly", "space-around"):
+            plan.append(("p", 1))
+        for i, (w, o) in enumerate(items):
+            if i > 0 and use_just:
+                if j in ("space-between", "space-evenly"):
+                    plan.append(("p", 1))
+                elif j == "space-around":
+                    plan.append(("p", 2))
+            plan.append(("c", w, o))
+        if use_just and j in ("center", "space-evenly", "space-around"):
+            plan.append(("p", 1))
+
+        idx = 0
+        content_seen = 0
+        prev_content = False
+        for entry in plan:
+            if entry[0] == "p":
+                main_cfg(idx, weight=entry[1])
+                idx += 1
+                prev_content = False
+                continue
+
+            _, widget, o = entry
+
+            # Spacer: a real child whose track carries the slack/fixed size.
+            if o.get("_spacer"):
+                size = o.get("_spacer_size")
+                if size is not None:
+                    main_cfg(idx, weight=0, minsize=size)
+                else:
+                    main_cfg(idx, weight=o.get("_spacer_weight", 1))
+                self._grid_cell(widget, idx, "", {})
+                idx += 1
+                prev_content = False
+                continue
+
+            # Content child: resolve its main-axis weight. `grow` is bool | int —
+            # grow=True means weight 1, grow=N sets the relative weight. Coerce
+            # bool to int so Tk's columnconfigure never sees a bool.
+            weight = o.get("grow")
+            if isinstance(weight, bool):
+                weight = 1 if weight else 0
+            if weight is None and self._grow_items:
+                weight = 1
+            if self._weights is not None:
+                weight = (
+                    int(self._weights[content_seen])
+                    if content_seen < len(self._weights)
+                    else 0
+                )
+            weight = int(weight or 0)
+            grows = weight > 0
+            if uniform_grow:
+                main_cfg(idx, weight=weight, uniform="flex")
+            else:
+                main_cfg(idx, weight=weight)
+
+            # Cross-axis sticky from the child's cross alignment (+ main-axis
+            # stretch when growing). The cross axis is vertical for a Row and
+            # horizontal for a Column, so the relevant per-child key flips.
+            cross_key = "vertical" if row_dir else "horizontal"
+            cross_val = o.get(cross_key) or self._cross_default()
+            sticky = ""
+            if grows:
+                sticky += "ew" if row_dir else "ns"
+            sticky += self._cross_sticky(cross_val)
+
+            # Gap (leading, between content only) + per-child margins.
+            main_axis = "padx" if row_dir else "pady"
+            cross_axis = "pady" if row_dir else "padx"
+            lead = self._gap if prev_content else 0
+            trail = 0
+            margin_main = o.get(main_axis)
+            if isinstance(margin_main, tuple):
+                lead += margin_main[0]
+                trail = margin_main[1]
+            elif margin_main is not None:
+                lead += margin_main
+            pad: dict[str, Any] = {}
+            if lead or trail:
+                pad[main_axis] = (lead, trail)
+            margin_cross = o.get(cross_axis)
+            if margin_cross is not None:
+                pad[cross_axis] = margin_cross
+
+            self._grid_cell(widget, idx, sticky, pad)
+            idx += 1
+            content_seen += 1
+            prev_content = True
+
+        self._used_main_tracks = max(idx - 1, 0)

bootstack/widgets/_impl/primitives/frame.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any
+
+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.types import Master, StyledKwargs
+from bootstack.style.style import get_style
+from ..mixins import configure_delegate
+
+
+class FrameKwargs(StyledKwargs, total=False):
+    # Standard ttk.Frame options
+    padding: Any
+    width: int
+    height: int
+
+    # bootstack-specific extensions
+    input_background: str
+    show_border: bool
+
+
+class Frame(TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Frame):
+    """bootstack wrapper for `ttk.Frame` with themed styling support."""
+
+    _ttk_base = ttk.Frame
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[FrameKwargs]) -> None:
+        """Create a themed bootstack Frame.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            padding: Extra padding inside the frame.
+            relief: Border style.
+            borderwidth: Border width.
+            width: Requested width in pixels.
+            height: Requested height in pixels.
+            takefocus: Widget accepts focus during keyboard traversal.
+            style: Explicit ttk style name (overrides accent/variant).
+            accent: Accent token for styling, e.g. 'primary', 'secondary', 'success'.
+            variant: Style variant (if applicable).
+            surface: Optional surface token; otherwise inherited.
+            input_background: Surface token used as the fill color for all input
+                widgets (Entry, Combobox, Spinbox, Field) inside this container. Cascades
+                to descendants the same way `surface` does. Input foreground, border,
+                and focus-ring colors are all derived from this fill so contrast is always
+                correct. Defaults to `'content'` (the app background), which keeps
+                inputs visually distinct regardless of the container surface. Override
+                with any surface token (e.g. `'card'`) to match the container.
+            show_border: Draw a border around the frame.
+            style_options: Optional dict forwarded to the style builder.
+        """
+        existing = kwargs.pop('style_options', {})
+        captured = self._capture_style_options(['show_border'], kwargs)
+        kwargs['style_options'] = {**existing, **captured}
+        super().__init__(master, **kwargs)
+
+    # A canvas-painting Frame subclass (Meter, Slider, …) recolors on a theme
+    # change by defining `_bs_apply_theme(self)`; the unified theme walk in
+    # `bootstack.style.style` calls it. There is no per-widget subscription or
+    # `<Map>` deferral — visibility is resolved by the walk at apply time.
+
+    def configure_style_options(self, value=None, **kwargs):
+        """Set style options and refresh descendant surfaces if needed."""
+        old_surface = getattr(self, "_surface", "background")
+        old_input_bg = getattr(self, "_input_background", None)
+        result = super().configure_style_options(value, **kwargs)
+        if value is None:
+            if "surface" in kwargs:
+                new_surface = getattr(self, "_surface", "background")
+                if old_surface != new_surface:
+                    self.rebuild_style()
+                    self._refresh_descendant_surfaces(old_surface, new_surface)
+            if "input_background" in kwargs:
+                new_input_bg = getattr(self, "_input_background", None)
+                if old_input_bg != new_input_bg:
+                    self._refresh_descendant_input_backgrounds(old_input_bg, new_input_bg)
+        return result
+
+    def _refresh_descendant_surfaces(self, old_surface: str, new_surface: str) -> None:
+        if old_surface == new_surface:
+            return
+
+        style = get_style()
+        builder_tk = style._get_tk_builder()
+
+        for child in self._iter_descendants():
+            try:
+                child_surface = getattr(child, "_surface", None)
+            except Exception:
+                child_surface = None
+
+            explicit_surface = None
+            try:
+                explicit_surface = getattr(child, "_style_options", {}).get("surface")
+            except Exception:
+                explicit_surface = None
+
+            if explicit_surface and explicit_surface != old_surface:
+                continue
+
+            if child_surface != old_surface:
+                continue
+
+            try:
+                setattr(child, "_surface", new_surface)
+            except Exception:
+                continue
+
+            if hasattr(child, "rebuild_style"):
+                try:
+                    child.rebuild_style()
+                except Exception:
+                    pass
+            else:
+                try:
+                    builder_tk.call_builder(child, surface=new_surface)
+                except Exception:
+                    pass
+
+    def _refresh_descendant_input_backgrounds(self, old_bg: str | None, new_bg: str | None) -> None:
+        if old_bg == new_bg:
+            return
+
+        style = get_style()
+        builder_tk = style._get_tk_builder()
+
+        for child in self._iter_descendants():
+            try:
+                child_input_bg = getattr(child, "_input_background", None)
+            except Exception:
+                child_input_bg = None
+
+            explicit_input_bg = None
+            try:
+                explicit_input_bg = getattr(child, "_style_options", {}).get("input_background")
+            except Exception:
+                explicit_input_bg = None
+
+            if explicit_input_bg and explicit_input_bg != old_bg:
+                continue
+
+            if child_input_bg != old_bg:
+                continue
+
+            try:
+                setattr(child, "_input_background", new_bg)
+            except Exception:
+                continue
+
+            if hasattr(child, "rebuild_style"):
+                try:
+                    child.rebuild_style()
+                except Exception:
+                    pass
+            else:
+                try:
+                    builder_tk.call_builder(child, input_background=new_bg)
+                except Exception:
+                    pass
+
+    def _iter_descendants(self):
+        stack = list(self.winfo_children())
+        while stack:
+            widget = stack.pop()
+            yield widget
+            try:
+                stack.extend(widget.winfo_children())
+            except Exception:
+                pass
+
+    @configure_delegate('show_border')
+    def _delegate_show_border(self, value=None):
+        """Get or set whether to draw a border."""
+        if value is not None:
+            return self.configure_style_options('show_border')
+        else:
+            self.configure_style_options(show_border=True)
+            return self.rebuild_style()