bootstack 0.1.0a1__py3-none-any.whl

bootstack/widgets/internal/wrapper_base.py

@@ -0,0 +1,304 @@
+"""Shared base for ttk wrapper widgets with bootstyle and config delegation.
+
+This base class wires up:
+- Constructor: delegates to Bootstyle'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`/`bootstyle` queries.
+- Bootstyle handler: implements @configure_delegate('bootstyle') so runtime
+  updates apply via the style engine without monkey-patching ttk.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from bootstack.style.bootstyle import (
+    Bootstyle,
+    extract_accent_from_style,
+    extract_variant_from_style,
+)
+from bootstack.style.token_maps import CONTAINER_CLASSES, ORIENT_CLASSES
+from bootstack.widgets.mixins.configure_mixin import (
+    ConfigureDelegationMixin,
+    configure_delegate,
+)
+from bootstack.widgets.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]
+        font_value = self._init_font_mixin(kwargs)
+        init_wrapper = Bootstyle.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]
+        # 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/bootstyle 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 in ("bootstyle", "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 in ("bootstyle", "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 = Bootstyle.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)
+
+        # 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 = Bootstyle.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 BootstyleBuilderError
+        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 = Bootstyle.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 options from a dictionary source.
+
+        This method should be called before `super()` to capture the style options when they are explicitly exposed as
+        keyword arguments instead of being passed indirectly in the `style_options` parameter.
+
+        This method will also attempt to extract the style_options argument if provided.
+
+        Parameters:
+            options: A list of options to extract.
+            source: The dictionary of keyword arguments to extract from.
+
+        Returns:
+            A dict of style options. e.g. {"icon_only": True, "icon": "bootstrap-fill"}.
+        """
+        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/mixins/__init__.py

@@ -0,0 +1,25 @@
+"""Widget mixins for bootstack."""
+
+from bootstack.widgets.mixins.configure_mixin import (
+    ConfigureDelegationMixin,
+    CustomConfigMixin,
+    configure_delegate,
+)
+from bootstack.widgets.mixins.font_mixin import FontMixin
+from bootstack.widgets.mixins.icon_mixin import IconMixin
+from bootstack.widgets.mixins.signal_mixin import SignalMixin, TextSignalMixin
+from bootstack.widgets.mixins.validation_mixin import ValidationMixin
+from bootstack.widgets.mixins.entry_mixin import EntryMixin
+from bootstack.widgets.mixins.localization_mixin import LocalizationMixin
+
+__all__ = [
+    "ConfigureDelegationMixin",
+    "CustomConfigMixin",
+    "configure_delegate",
+    "FontMixin",
+    "IconMixin",
+    "SignalMixin",
+    "TextSignalMixin",
+    "ValidationMixin",
+    "LocalizationMixin",
+]

bootstack/widgets/mixins/configure_mixin.py

@@ -0,0 +1,186 @@
+"""Configuration delegation helpers for widget classes.
+
+Provides a decorator and mixin so widgets can handle custom configure keys
+without large if/else blocks. Suited for use by bootstack wrapper
+subclasses and custom widgets.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Tuple
+
+
+def configure_delegate(*names: str):
+    """Decorator to mark a method as a configure handler for given names.
+
+    The decorated method should accept a single argument `value` to set,
+    and optionally return None. For getting values, the mixin will read
+    from self._<option_name> directly.
+    """
+
+    def _decorator(func: Callable[[Any, Any], Any]):
+        keys = set(getattr(func, "_bootstack_configure_keys", ()))
+        keys.update(names)
+        setattr(func, "_bootstack_configure_keys", tuple(keys))
+        return func
+
+    return _decorator
+
+
+class ConfigureDelegationMixin:
+    """Mix-in that dispatches configure keys to decorated handlers.
+
+    Subclasses can annotate methods with @configure_delegate("key") to handle
+    custom configuration entries without if/else chains.
+    """
+
+    _configure_delegate_map: Dict[str, str] = {}
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:  # noqa: D401
+        super().__init_subclass__(**kwargs)
+        mapping: Dict[str, str] = {}
+        for base in reversed(cls.__mro__):
+            for name, member in getattr(base, "__dict__", {}).items():
+                keys = getattr(member, "_bootstack_configure_keys", None)
+                if keys:
+                    for k in keys:
+                        mapping[str(k)] = name
+        cls._configure_delegate_map = mapping
+
+    def _config_delegate_set(self, key: str, value: Any) -> bool:
+        method_name = self._configure_delegate_map.get(key)
+        if not method_name:
+            return False
+        handler = getattr(self, method_name)
+        handler(value)
+        return True
+
+    def _config_delegate_get(self, key: str) -> Tuple[bool, Any]:
+        method_name = self._configure_delegate_map.get(key)
+        if not method_name:
+            return False, None
+        handler = getattr(self, method_name)
+        value = handler(None)
+        # For variable options, return the string name instead of the object
+        if key in ('variable', 'textvariable') and hasattr(value, '_name'):
+            return True, str(value)
+        return True, value
+
+    def configure(self, cnf=None, **kwargs):
+        """Configure widget options, handling custom delegated options first."""
+        # Handle custom delegated keys
+        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 in standard Tkinter format: (name, dbName, dbClass, default, current)
+                return (cnf, cnf, cnf.capitalize(), None, value)
+
+        # Forward remaining options to parent
+        return super().configure(cnf, **kwargs)
+
+    config = configure
+
+    def __setitem__(self, key, value):
+        """Set configuration option via indexing."""
+        if key in self._configure_delegate_map:
+            self._config_delegate_set(key, value)
+            return
+        return super().__setitem__(key, value)
+
+    def __getitem__(self, key):
+        """Get configuration option via indexing."""
+        if key in self._configure_delegate_map:
+            handled, value = self._config_delegate_get(key)
+            if handled:
+                return value
+        return super().__getitem__(key)
+
+    def cget(self, key):
+        """Get configuration option."""
+        if key in self._configure_delegate_map:
+            handled, value = self._config_delegate_get(key)
+            if handled:
+                return value
+        return super().cget(key)
+
+
+class CustomConfigMixin(ConfigureDelegationMixin):
+    """Tk-like configure/cget API for non-tkinter classes.
+
+    Stores arbitrary options locally while still honoring @configure_delegate
+    handlers for custom keys. Useful for helper classes that wrap tkinter
+    widgets but do not inherit from them directly.
+    """
+
+    def __init__(self, *args, **kwargs) -> None:
+        self._custom_config_store = {}
+        super().__init__(*args, **kwargs)
+
+    def _all_option_keys(self):
+        """Return all known option keys."""
+        return set(self._custom_config_store.keys()) | set(self._configure_delegate_map.keys())
+
+    def configure(self, cnf=None, **kwargs):
+        """Set or query options using a tkinter-compatible shape."""
+        # allow dict passthrough like tkinter
+        if isinstance(cnf, dict):
+            kwargs.update(cnf)
+            cnf = None
+
+        # Handle delegated setters first
+        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)
+
+        # Store any remaining options
+        for key, value in kwargs.items():
+            self._custom_config_store[key] = value
+
+        # Getter semantics
+        if cnf is None:
+            return {
+                key: (key, key, key.capitalize(), None, self.cget(key))
+                for key in self._all_option_keys()
+            }
+
+        if isinstance(cnf, str):
+            return (cnf, cnf, cnf.capitalize(), None, self.cget(cnf))
+
+        return None
+
+    config = configure
+
+    def __setitem__(self, key, value):
+        """Set option via dictionary style."""
+        if key in self._configure_delegate_map:
+            if self._config_delegate_set(key, value):
+                return
+        self._custom_config_store[key] = value
+
+    def __getitem__(self, key):
+        """Get option via dictionary style."""
+        if key in self._configure_delegate_map:
+            handled, value = self._config_delegate_get(key)
+            if handled:
+                return value
+        return self._custom_config_store.get(key)
+
+    def cget(self, key):
+        """Return the current value for an option."""
+        if key in self._configure_delegate_map:
+            handled, value = self._config_delegate_get(key)
+            if handled:
+                return value
+        return self._custom_config_store.get(key)
+
+
+__all__ = ["configure_delegate", "ConfigureDelegationMixin", "CustomConfigMixin"]

bootstack/widgets/mixins/entry_mixin.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bootstack.widgets.parts.numberentry_part import NumberEntryPart
+    from bootstack.widgets.parts.numberentry_part import TextEntryPart
+
+
+class EntryMixin:
+    """A mixin that exposes the functionality of entry-like widgets on composite widgets"""
+
+    _entry: TextEntryPart | NumberEntryPart
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    def bbox(self, index):
+        """Return the bounding box of character at index"""
+        return self._entry.bbox(index)
+
+    def delete(self, first, last):
+        """Delete text between indices"""
+        return self._entry.delete(first, last)
+
+    def insert(self, index, text):
+        """Insert text at index"""
+        return self._entry.insert(index, text)
+
+    def icursor(self, index):
+        """Set the cursor position"""
+        self._entry.icursor(index)
+
+    def index(self, index="insert"):
+        """Return the character at index (defaults to 'cursor')"""
+        return self._entry.index(index)
+
+    def scan_mark(self, x):
+        """Start drag-to-scroll behavior"""
+        return self._entry.scan_mark(x)
+
+    def scan_dragto(self, x):
+        """Continue drag-to-scroll behavior"""
+        return self._entry.scan_dragto(x)
+
+    def selection_adjust(self, index):
+        """Adjust selection endpoint"""
+        return self._entry.selection_adjust(index)
+
+    def selection_clear(self):
+        """Clear text selection"""
+        return self._entry.selection_clear()
+
+    def selection_from(self, index):
+        """Select text starting from index"""
+        return self._entry.selection_from(index)
+
+    def selection_to(self, index):
+        """Extend selection to index"""
+        return self._entry.selection_to(index)
+
+    def selection_range(self, first, last):
+        """Select text between first and last"""
+        return self._entry.selection_range(first, last)
+
+    def selection_present(self):
+        return self._entry.selection_present()
+
+    def selection_all(self):
+        """Select all text"""
+        return self._entry.selection_range(0, 'end')