bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_core/window_controls.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+
+class WindowControlsMixin:
+    """Window lifecycle and show-state controls shared by top-level windows.
+
+    Mixed into `App`, `AppShell`, and `Window` so every top-level window exposes
+    the same close and show-state surface.
+    """
+
+    _internal: Any
+
+    def close(self) -> None:
+        """Close the window and exit its event loop.
+
+        For the application window this quits the loop started by `run()` — the
+        natural action for a "Quit" command. It does not run the `on_close` veto
+        handlers (those guard the user clicking the window's close button), so a
+        programmatic `close()` always proceeds.
+        """
+        self._internal.close()
+
+    def show(self) -> None:
+        """Show the window — typically to reveal it again after `hide()`.
+
+        For the application window, `run()` already shows it and starts the
+        event loop; reach for `show()` to bring a hidden window back.
+        """
+        self._internal.show()
+
+    def hide(self) -> None:
+        """Hide the window without destroying it.
+
+        The window is unmapped (and usually removed from the taskbar). Bring it
+        back with `show()`.
+        """
+        self._internal.hide()
+
+    def minimize(self) -> None:
+        """Minimize the window to the taskbar or dock."""
+        self._internal.minimize()
+
+    def maximize(self) -> None:
+        """Maximize the window where the platform supports it."""
+        self._internal.maximize()
+
+    def set_fullscreen(self, value: bool = True) -> None:
+        """Enter or leave fullscreen mode where supported.
+
+        Args:
+            value: `True` to enter fullscreen, `False` to exit. Default `True`.
+        """
+        self._internal.set_fullscreen(value)
+
+    def set_topmost(self, value: bool = True) -> None:
+        """Pin the window above all others, or release it.
+
+        Args:
+            value: `True` to keep the window above others, `False` to release.
+                Default `True`.
+        """
+        self._internal.set_topmost(value)
+
+    def on_close(self, handler: Callable[[], bool | None]) -> None:
+        """Register a handler invoked when the user clicks the window's close button.
+
+        Handlers run in registration order; return `False` from one to veto the
+        close (the window stays open), or `None`/`True` to allow it. This guards
+        the close-button gesture only — it is not run by the programmatic
+        `close()`.
+
+        Args:
+            handler: Called with no arguments on a close request. Return `False`
+                to cancel the close.
+        """
+        self._internal.add_close_handler(handler)
+
+    def add_close_handler(self, handler: Callable[[], bool | None]) -> None:
+        """Register a veto-able close handler — an alias for `on_close()`.
+
+        Args:
+            handler: Called with no arguments on a close request. Return `False`
+                to cancel the close.
+        """
+        self._internal.add_close_handler(handler)
+
+    def remove_close_handler(self, handler: Callable[[], bool | None]) -> None:
+        """Remove a close handler previously registered with `on_close()`.
+
+        Args:
+            handler: The same callable passed to `on_close()` or
+                `add_close_handler()`. No-op if it was not registered.
+        """
+        self._internal.remove_close_handler(handler)

bootstack/widgets/_core/window_menu.py

@@ -0,0 +1,246 @@
+"""The stacked-toolbar chrome host for top-level windows.
+
+`ChromeHostMixin` gives `App` / `Window` / `AppShell` an `add_toolbar()` factory:
+the window's top region is a vertical stack of `Toolbar`s, each holding buttons,
+labels, widgets, and menus (`toolbar.add_menu(...)`). A menu is just a toolbar
+item — it renders as an in-window dropdown on Windows/Linux and bridges to the
+native global menu bar on macOS (aggregated across every bridged chrome toolbar).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+# Softness for a chrome divider, matching the shell's region dividers: the stroke
+# blends close to its surface for a quiet hairline rather than the default
+# separator border (which blends harder toward the semantic border color).
+_CHROME_DIVIDER_BORDER_STRENGTH = 0.90
+
+
+class _ToolbarStackContainer:
+    """Public-container shim so an `add_toolbar()` toolbar packs into the host's
+    vertical chrome stack (full-width, top-to-bottom in creation order)."""
+
+    _auto_place = True
+
+    def __init__(self, frame: Any) -> None:
+        self._frame = frame
+
+    def _child_master(self) -> Any:
+        return self._frame
+
+    def guide_layout(self, child: Any, **layout_kw: Any) -> None:
+        # Toolbars stack full-width in creation order; the stack owns the layout.
+        child._internal.pack(side="top", fill="x")
+
+
+class ChromeHostMixin:
+    """`add_toolbar()` — the window's top region is a stack of toolbars.
+
+    Each `add_toolbar()` appends a full-width `Toolbar` band; menus live on the
+    toolbars (`toolbar.add_menu(...)`). On macOS the bridged toolbars' menus are
+    aggregated into the native global menu bar; on Windows/Linux they render as
+    in-window dropdowns. `AppShell` overrides `_ensure_toolbar_stack()` to mount
+    the stack into its own region layout.
+    """
+
+    def _menu_root(self) -> Any:
+        """Tk root/toplevel for the native menubar (`['menu']`) + shortcuts."""
+        return getattr(self, "_internal", None)
+
+    # ----- toolbar stack -----
+
+    def add_toolbar(
+        self, *, divider: bool = False, use_macos_menus: bool = True, **toolbar_kwargs: Any
+    ) -> Any:
+        """Append a `Toolbar` to the window's top chrome stack and return it.
+
+        Toolbars stack full-width, top-to-bottom, in the order added — fill each
+        with buttons, labels, widgets, and menus (`toolbar.add_menu(...)`). The
+        returned `Toolbar` is a context manager, so the natural form reads::
+
+            with window.add_toolbar() as tb:
+                tb.add_menu("File")
+                tb.add_spacer()
+                tb.add_theme_toggle()
+
+        Args:
+            divider: Draw a hairline beneath this toolbar (default `False`).
+            use_macos_menus: On macOS, bridge this toolbar's menus to the native
+                global menu bar (in-window dropdowns hide). Default `True`; set
+                `False` to keep its menus in-window even on macOS. No effect on
+                Windows/Linux.
+            **toolbar_kwargs: Forwarded to `Toolbar` — e.g. `surface`, `density`,
+                `button_variant`, `show_window_controls`, `draggable`. Window
+                chrome defaults `surface='chrome'` and `density='compact'` (a tight
+                strip); pass `density='default'` for a roomier bar.
+
+        Returns:
+            The `Toolbar` for this layer.
+        """
+        from bootstack.widgets._impl.primitives import Separator
+        from bootstack.widgets.toolbar import Toolbar
+
+        stack = self._ensure_toolbar_stack()
+        toolbar_kwargs.setdefault("surface", "chrome")
+        # Window chrome reads as a tight strip (menu bars, title bars, command
+        # bars are all compact by convention) — default to compact, overridable.
+        toolbar_kwargs.setdefault("density", "compact")
+        tb = Toolbar(parent=_ToolbarStackContainer(stack), _host=self, **toolbar_kwargs)
+        if divider:
+            # A bare full-width hairline — no margin. The bar above provides any
+            # spacing through its own (chrome) padding, so nothing of the stack
+            # surface leaks below the line when this is the last band before the
+            # content (the window's content surface starts right after the line).
+            Separator(
+                stack, orient="horizontal", surface=toolbar_kwargs["surface"],
+                border_strength=_CHROME_DIVIDER_BORDER_STRENGTH,
+            ).pack(side="top", fill="x")
+        self._register_chrome_toolbar(tb, use_macos_menus)
+        return tb
+
+    def _ensure_default_titlebar(self) -> None:
+        """Give a borderless window a movable, closeable title bar.
+
+        Batteries-included chrome for an `undecorated` window: when the OS title
+        bar is gone and the author added no chrome toolbar of their own, inject a
+        single `add_toolbar(show_window_controls=True)` band (min/max/close on the
+        right, draggable, double-click to maximize) with the window title as a
+        left label — so a borderless window is never stranded.
+
+        No-op when window controls are turned off (`window_controls=False`), when
+        the window is decorated, on macOS (where `overrideredirect` is
+        force-disabled), or when the author already built chrome with
+        `add_toolbar()`. Idempotent — the author-chrome guard makes a second call
+        a no-op. Called from the window's show/run path, after authoring.
+        """
+        import sys
+
+        if not getattr(self, "_window_controls", True):
+            return
+        if not getattr(self, "_undecorated", False):
+            return
+        if sys.platform == "darwin":
+            return
+        if getattr(self, "_chrome_toolbars", None):
+            return  # the author owns the chrome
+        tb = self.add_toolbar(show_window_controls=True)
+        root = self._menu_root()
+        title = ""
+        if root is not None:
+            try:
+                title = root.title()
+            except Exception:
+                title = ""
+        if title:
+            tb.add_label(title)
+
+    def _ensure_toolbar_stack(self) -> Any:
+        stack = getattr(self, "_toolbar_stack", None)
+        if stack is not None:
+            return stack
+        from bootstack.widgets._impl.primitives.packframe import PackFrame
+
+        # The stack carries the chrome surface so any gap between stacked bars
+        # (e.g. a divider's margin) reads as chrome rather than the window's
+        # content surface. Chrome-surfaced toolbars sit seamlessly on it.
+        stack = PackFrame(self._toolbar_stack_parent(), direction="vertical", surface="chrome")
+        self._mount_toolbar_stack(stack)
+        self._toolbar_stack = stack
+        return stack
+
+    def _toolbar_stack_parent(self) -> Any:
+        """Widget the chrome stack is built under (overridable by the host)."""
+        return self._menu_root()
+
+    def _mount_toolbar_stack(self, stack: Any) -> None:
+        """Pack the chrome stack at the top of the window, above the content."""
+        content = getattr(self, "_content_frame", None)
+        pack_kw: dict[str, Any] = {"side": "top", "fill": "x"}
+        if content is not None:
+            pack_kw["before"] = content
+        stack.pack(**pack_kw)
+
+    # ----- macOS native menu bridge -----
+
+    def _register_chrome_toolbar(self, tb: Any, use_macos_menus: bool) -> None:
+        """Track a chrome toolbar and, on macOS, wire its menus into the native
+        global menu bar (aggregated across all bridged toolbars)."""
+        toolbars = getattr(self, "_chrome_toolbars", None)
+        if toolbars is None:
+            toolbars = self._chrome_toolbars = []
+        toolbars.append((tb, use_macos_menus))
+        if use_macos_menus and self._menus_are_native():
+            tb._internal._on_menu_change = self._schedule_native_menu_rebuild
+            self._schedule_native_menu_rebuild()
+
+    def _menus_are_native(self) -> bool:
+        """Whether menus render in the native global bar (macOS / aqua)."""
+        root = self._menu_root()
+        try:
+            return root.tk.call("tk", "windowingsystem") == "aqua"
+        except Exception:
+            return False
+
+    def _aggregate_native_menu_model(self) -> Any:
+        """Build one `MenuModel` from every bridged chrome toolbar's menus, in
+        stack order then left-to-right within each toolbar. Also hides the
+        in-window triggers for bridged toolbars (the native bar shows them)."""
+        from bootstack.widgets._impl.composites.menu.model import MenuModel
+
+        agg = MenuModel()
+        for tb, bridge in getattr(self, "_chrome_toolbars", []):
+            if not bridge:
+                continue
+            model = tb._internal.menu_model
+            if model is None:
+                continue
+            agg.groups.extend(model.groups)
+            for trigger in tb._internal._menu_triggers.values():
+                try:
+                    trigger.pack_forget()
+                except Exception:
+                    pass
+        return agg
+
+    def _schedule_native_menu_rebuild(self) -> None:
+        root = self._menu_root()
+        pending = getattr(self, "_native_menu_pending", None)
+        if root is None:
+            self._rebuild_native_menu()
+            return
+        if pending is not None:
+            try:
+                root.after_cancel(pending)
+            except Exception:
+                pass
+        try:
+            self._native_menu_pending = root.after_idle(self._rebuild_native_menu)
+        except Exception:
+            self._rebuild_native_menu()
+
+    def _cancel_native_menu_pending(self) -> None:
+        """Cancel a scheduled native-menu rebuild and clear the handle.
+
+        Used on teardown / dev-reload reset: an `after_idle` rebuild scheduled
+        just before a reset would otherwise fire against freshly-rebuilt chrome.
+        """
+        pending = getattr(self, "_native_menu_pending", None)
+        if pending is not None:
+            root = self._menu_root()
+            if root is not None:
+                try:
+                    root.after_cancel(pending)
+                except Exception:
+                    pass
+        self._native_menu_pending = None
+
+    def _rebuild_native_menu(self) -> None:
+        from bootstack.widgets._impl.composites.menu.render_native import NativeMenuBar
+
+        self._native_menu_pending = None
+        model = self._aggregate_native_menu_model()
+        renderer = getattr(self, "_native_menu_renderer", None)
+        if renderer is None:
+            self._native_menu_renderer = NativeMenuBar(self._menu_root(), model)
+        else:
+            renderer.set_model(model)

bootstack/widgets/_impl/__init__.py

@@ -0,0 +1 @@
+"""Internal widget implementation — do not import directly from user code."""

bootstack/widgets/_impl/_internal/wrapper_base.py

@@ -0,0 +1,307 @@
+"""Shared base for ttk wrapper widgets with style and config delegation.
+
+This base class wires up:
+- Constructor: delegates to StyleResolver's constructor wrapper for init-time style
+  setup, including surface color inheritance and default variants.
+- Configure: routes keys annotated via @configure_delegate to their handlers,
+  then forwards remaining options to the underlying ttk widget.
+- Index access: `w['key']` and `w['key'] = value` work for delegated keys and
+  for `style` queries.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from bootstack.style.style_resolver import (
+    StyleResolver,
+    extract_accent_from_style,
+    extract_variant_from_style,
+)
+from bootstack.style.token_maps import CONTAINER_CLASSES, ORIENT_CLASSES
+from bootstack.widgets._impl.mixins.configure_mixin import (
+    ConfigureDelegationMixin,
+    configure_delegate,
+)
+from bootstack.widgets._impl.mixins.font_mixin import FontMixin
+
+
+class TTKWrapperBase(FontMixin, ConfigureDelegationMixin):
+    """Base class for all ttk wrapper widgets.
+
+    Subclasses must set `_ttk_base` to the underlying ttk class and inherit
+    from that ttk class as well (MRO: WrapperBase, ttk.Class).
+
+    Includes FontMixin for font modifier syntax support.
+    """
+
+    _ttk_base: type
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:  # type: ignore[override]
+        """Initialize the wrapper, applying font modifier syntax and StyleResolver setup."""
+        font_value = self._init_font_mixin(kwargs)
+        init_wrapper = StyleResolver.override_ttk_widget_constructor(self._ttk_base.__init__)  # type: ignore[attr-defined]
+        init_wrapper(self, *args, **kwargs)
+        if font_value is not None:
+            self._delegate_font(font_value)
+
+    def configure(self, cnf: Any | None = None, **kwargs: Any):  # type: ignore[override]
+        """Configure widget options, routing delegated keys before forwarding to ttk."""
+        # First, route custom keys via delegation
+        if kwargs:
+            for _k in list(kwargs.keys()):
+                if _k in self._configure_delegate_map:
+                    if self._config_delegate_set(_k, kwargs[_k]):
+                        kwargs.pop(_k, None)
+
+        # Getter path for delegated keys
+        if isinstance(cnf, str) and cnf in self._configure_delegate_map:
+            handled, value = self._config_delegate_get(cnf)
+            if handled:
+                return value
+
+        # Forward remaining options directly to ttk
+        return self._ttk_base.configure(self, cnf, **kwargs)  # type: ignore[misc]
+
+    # tk alias
+    config = configure
+
+    # Indexing support: delegate custom keys; handle style queries
+    def __setitem__(self, key: str, value: Any) -> None:  # noqa: D401
+        if key in getattr(self, "_configure_delegate_map", {}):
+            self._config_delegate_set(key, value)
+            return None
+        if key == "style" and getattr(self, "__class__", None).__name__ != "OptionMenu":
+            return self.configure(**{key: value})
+        return self._ttk_base.__setitem__(self, key, value)  # type: ignore[misc]
+
+    def __getitem__(self, key: str) -> Any:  # noqa: D401
+        if key in getattr(self, "_configure_delegate_map", {}):
+            handled, value = self._config_delegate_get(key)
+            if handled:
+                return value
+        if key == "style" and getattr(self, "__class__", None).__name__ != "OptionMenu":
+            return self.configure(cnf=key)
+        return self._ttk_base.__getitem__(self, key)  # type: ignore[misc]
+
+    def rebuild_style(self):
+        """Recreate the widget's current style with updated style options.
+
+        This is useful when runtime style_options change (e.g., showing/hiding
+        dropdown chevrons) and you need the builder to regenerate assets.
+
+        Generates a new style name with the correct hash based on the new
+        style_options, then applies it to the widget.
+
+        NOTE: Style options are updated via the `style_options()` method.
+        """
+        # Use stored _ttk_class if available (for custom style class like ButtonGroup)
+        # Otherwise fall back to actual widget class
+        widget_class = getattr(self, '_ttk_class', None) or self.winfo_class()
+
+        style_options = getattr(self, '_style_options', {})
+
+        # Use stored accent/variant if available
+        accent = getattr(self, '_accent', None)
+        variant = getattr(self, '_variant', None)
+
+        # Fall back to extraction from style if not stored
+        if accent is None or variant is None:
+            current_style = self._ttk_base.cget(self, "style")  # type: ignore[misc]
+            if current_style:
+                if accent is None:
+                    accent = extract_accent_from_style(current_style, default=None)
+                if variant is None:
+                    variant = extract_variant_from_style(current_style, widget_class)
+
+        # Preserve surface and orientation in style_options
+        if not style_options:
+            style_options = {}
+        surface = getattr(self, "_surface", None)
+        if surface and surface != "content":
+            style_options["surface"] = surface
+        if widget_class in ORIENT_CLASSES:
+            try:
+                style_options["orient"] = str(self.cget("orient"))
+            except Exception:
+                pass
+
+        # Generate NEW style name with NEW hash based on new options
+        ttk_style = StyleResolver.create_ttk_style(
+            widget_class=widget_class,
+            style_options=style_options or None,
+            accent=accent,
+            variant=variant,
+        )
+
+        # Apply the new style
+        return self._ttk_base.configure(self, style=ttk_style)  # type: ignore[misc]
+
+    # ----- Built-in delegated handlers -----
+    @configure_delegate("accent")
+    def _delegate_accent(self, value: Any = None):
+        """Get or set the accent token for this widget.
+
+        - Query: returns the current accent token or None
+        - Set: updates the widget style with the new accent, preserving variant
+        """
+        # Query path
+        if value is None:
+            # Try stored value first
+            stored = getattr(self, '_accent', None)
+            if stored:
+                return stored
+            # Fall back to extracting from current style
+            current_style = self._ttk_base.cget(self, "style")  # type: ignore[misc]
+            if not current_style:
+                return None
+            return extract_accent_from_style(current_style, default=None)
+
+        # Set path - use stored _ttk_class if available
+        widget_class = getattr(self, '_ttk_class', None) or self.winfo_class()
+        current_variant = getattr(self, '_variant', None)
+        if current_variant is None:
+            current_style = self._ttk_base.cget(self, "style")  # type: ignore[misc]
+            if current_style:
+                current_variant = extract_variant_from_style(current_style, widget_class)
+
+        # Coerce 'default' to None — means "no accent, use widget's neutral style"
+        if value == 'default':
+            value = None
+
+        # Store the new accent
+        setattr(self, '_accent', value)
+
+        # Use stored style_options
+        style_options = getattr(self, '_style_options', {}).copy()
+
+        surface = getattr(self, "_surface", None)
+        if surface and surface != "content":
+            style_options["surface"] = surface
+
+        if widget_class in ORIENT_CLASSES:
+            try:
+                style_options["orient"] = str(self.cget("orient"))
+            except Exception:
+                pass
+
+        if widget_class in CONTAINER_CLASSES:
+            style_options["surface"] = value
+            setattr(self, "_surface", value)
+
+        ttk_style = StyleResolver.create_ttk_style(
+            widget_class=widget_class,
+            accent=value,
+            variant=current_variant,
+            style_options=style_options or None,
+        )
+        return self._ttk_base.configure(self, style=ttk_style)  # type: ignore[misc]
+
+    @configure_delegate("variant")
+    def _delegate_variant(self, value: Any = None):
+        """Get or set the variant for this widget.
+
+        - Query: returns the current variant name or None
+        - Set: updates the widget style with the new variant, preserving accent
+
+        Note: If the variant is not valid for this widget type, a StyleBuilderError
+        will be raised.
+        """
+        # Query path
+        if value is None:
+            # Try stored value first
+            stored = getattr(self, '_variant', None)
+            if stored:
+                return stored
+            # Fall back to extracting from current style
+            current_style = self._ttk_base.cget(self, "style")  # type: ignore[misc]
+            if not current_style:
+                return None
+            widget_class = getattr(self, '_ttk_class', None) or self.winfo_class()
+            return extract_variant_from_style(current_style, widget_class)
+
+        # Set path - use stored _ttk_class if available
+        widget_class = getattr(self, '_ttk_class', None) or self.winfo_class()
+        current_accent = getattr(self, '_accent', None)
+        if current_accent is None:
+            current_style = self._ttk_base.cget(self, "style")  # type: ignore[misc]
+            if current_style:
+                current_accent = extract_accent_from_style(current_style, default=None)
+
+        # Store the new variant
+        setattr(self, '_variant', value)
+
+        # Use stored style_options
+        style_options = getattr(self, '_style_options', {}).copy()
+
+        surface = getattr(self, "_surface", None)
+        if surface and surface != "content":
+            style_options["surface"] = surface
+
+        if widget_class in ORIENT_CLASSES:
+            try:
+                style_options["orient"] = str(self.cget("orient"))
+            except Exception:
+                pass
+
+        ttk_style = StyleResolver.create_ttk_style(
+            widget_class=widget_class,
+            accent=current_accent,
+            variant=value,
+            style_options=style_options or None,
+        )
+        return self._ttk_base.configure(self, style=ttk_style)  # type: ignore[misc]
+
+    def configure_style_options(self, value=None, **kwargs):
+        """Get or set the widget style options if handled by the widget's style builder.
+
+        Special cascading keys:
+            surface: Updates `_surface` on this widget and (via Frame subclass) triggers
+                `_refresh_descendant_surfaces` to propagate the change to children.
+            input_background: Updates `_input_background` on this widget and (via Frame
+                subclass) triggers `_refresh_descendant_input_backgrounds` to propagate
+                the change to all descendant input widgets.
+        """
+        options = getattr(self, "_style_options", {})
+        if value is None:
+            options.update(**kwargs)
+            setattr(self, "_style_options", options)
+            if "surface" in kwargs:
+                surface = kwargs.get("surface")
+                setattr(self, "_surface", surface or "content")
+            if "input_background" in kwargs:
+                setattr(self, "_input_background", kwargs.get("input_background"))
+            return None
+        else:
+            return options.get(value, None)
+
+    def _capture_style_options(self, options: list[str] = None, source: Any = None):
+        """Extract named kwargs into a style-options dict before passing to super.
+
+        Call this before `super().__init__` to capture style-related kwargs that
+        are exposed as explicit parameters rather than via `style_options=`. Also
+        merges any `style_options` dict already in `source`.
+
+        Args:
+            options: Names of kwargs to extract from `source`.
+            source: The kwargs dict to extract from (mutated in-place).
+
+        Returns:
+            A dict of captured style options, e.g. `{'icon_only': True, 'icon': 'house'}`.
+        """
+        if source is None:
+            return {}
+
+        style_options = source.pop("style_options", {})
+
+        captured = {}
+        for option in options:
+            if option in source:
+                captured[option] = source.pop(option)
+        if captured:
+            style_options.update(**captured)
+
+        return style_options
+
+
+__all__ = ["TTKWrapperBase"]

bootstack/widgets/_impl/_parts/__init__.py

@@ -0,0 +1,11 @@
+"""Widget parts module for composite widgets."""
+
+from bootstack.widgets._impl._parts.textentry_part import TextEntryPart
+from bootstack.widgets._impl._parts.numberentry_part import NumberEntryPart
+from bootstack.widgets._impl._parts.spinnerentry_part import SpinnerEntryPart
+
+__all__ = [
+    'TextEntryPart',
+    'NumberEntryPart',
+    'SpinnerEntryPart',
+]