bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_impl/mixins/__init__.py

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

bootstack/widgets/_impl/mixins/configure_mixin.py

@@ -0,0 +1,216 @@
+"""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
+
+
+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:
+        """Build the key→handler map from all @configure_delegate methods in the MRO."""
+        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:
+        """Invoke the delegate handler for `key` with `value`.
+
+        Returns:
+            True if a handler was found and called, False otherwise.
+        """
+        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]:
+        """Query the delegate handler for `key`.
+
+        Returns:
+            A `(handled, value)` tuple. `handled` is False if no handler
+            exists for the key.
+        """
+        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: str | dict | None = None, **kwargs: Any) -> Any:
+        """Set one or more widget options, or query the current value of a named option.
+
+        Args:
+            cnf: Option name to query (e.g. `'accent'`), a dict of options to
+                set, or None when passing options as keyword arguments.
+            **kwargs: Option names and values to set (e.g. `accent='primary'`).
+        """
+        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)
+
+        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)
+
+        return super().configure(cnf, **kwargs)
+
+    config = configure
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Set a configuration option using `widget[key] = value` syntax."""
+        if key in self._configure_delegate_map:
+            self._config_delegate_set(key, value)
+            return
+        return super().__setitem__(key, value)
+
+    def __getitem__(self, key: str) -> Any:
+        """Return the current value of a configuration option using `widget[key]` syntax."""
+        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: str) -> Any:
+        """Return the current value of a configuration option.
+
+        Args:
+            key: Option name, e.g. `'accent'`, `'icon'`.
+        """
+        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: Any, **kwargs: Any) -> None:
+        self._custom_config_store: dict[str, Any] = {}
+        super().__init__(*args, **kwargs)
+
+    def _all_option_keys(self) -> set[str]:
+        """Return the union of stored keys and delegated keys."""
+        return set(self._custom_config_store.keys()) | set(self._configure_delegate_map.keys())
+
+    def configure(self, cnf: str | dict | None = None, **kwargs: Any) -> Any:
+        """Set one or more widget options, or query the current value of a named option.
+
+        Args:
+            cnf: Option name to query (e.g. `'accent'`), a dict of options to
+                set, or None when passing options as keyword arguments.
+            **kwargs: Option names and values to set (e.g. `accent='primary'`).
+
+        Returns:
+            When `cnf` is None, a dict of all options in tkinter tuple format.
+            When `cnf` is a string, a `(name, dbName, dbClass, default, current)`
+            tuple. None when setting options.
+        """
+        if isinstance(cnf, dict):
+            kwargs.update(cnf)
+            cnf = None
+
+        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)
+
+        for key, value in kwargs.items():
+            self._custom_config_store[key] = value
+
+        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: str, value: Any) -> None:
+        """Set an option using `obj[key] = value` syntax."""
+        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: str) -> Any:
+        """Return an option value using `obj[key]` syntax."""
+        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: str) -> Any:
+        """Return the current value for an option.
+
+        Args:
+            key: Option name to query.
+        """
+        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/_impl/mixins/entry_mixin.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bootstack.widgets._impl._parts.numberentry_part import NumberEntryPart
+    from bootstack.widgets._impl._parts.textentry_part import TextEntryPart
+
+
+class EntryMixin:
+    """Exposes the text-editing API of the internal entry part on composite widgets.
+
+    Composite widgets that embed a text or numeric entry part inherit this mixin
+    so callers can manipulate content (insert, delete, select) directly on the
+    composite without accessing the internal part.
+    """
+
+    _entry: TextEntryPart | NumberEntryPart
+
+    def bbox(self, index: int | str) -> tuple[int, int, int, int]:
+        """Return the bounding box of the character at index.
+
+        Args:
+            index: Character index or named position (e.g., `'insert'`, `'end'`).
+
+        Returns:
+            A tuple `(x, y, width, height)` in pixels.
+        """
+        return self._entry.bbox(index)
+
+    def delete(self, first: int | str, last: int | str = None) -> None:
+        """Delete text between two indices.
+
+        Args:
+            first: Start index (inclusive).
+            last: End index (exclusive). If None, deletes a single character at `first`.
+        """
+        return self._entry.delete(first, last)
+
+    def insert(self, index: int | str, text: str) -> None:
+        """Insert text at the given index.
+
+        Args:
+            index: Position to insert at. Use `'end'` to append.
+            text: Text to insert.
+        """
+        return self._entry.insert(index, text)
+
+    def icursor(self, index: int | str) -> None:
+        """Move the insertion cursor to index.
+
+        Args:
+            index: Target cursor position.
+        """
+        self._entry.icursor(index)
+
+    def index(self, index: int | str = 'insert') -> int:
+        """Return the numerical index of a position.
+
+        Args:
+            index: Named position or numerical index. Defaults to `'insert'`
+                (the current cursor position).
+
+        Returns:
+            The numerical character index.
+        """
+        return self._entry.index(index)
+
+    def scan_mark(self, x: int) -> None:
+        """Record the starting position for a drag-to-scroll operation.
+
+        Args:
+            x: The x-coordinate (in pixels) where the drag begins.
+        """
+        return self._entry.scan_mark(x)
+
+    def scan_dragto(self, x: int) -> None:
+        """Scroll the entry to follow the pointer during a drag operation.
+
+        Call after `scan_mark` as the pointer moves.
+
+        Args:
+            x: The current x-coordinate (in pixels) of the pointer.
+        """
+        return self._entry.scan_dragto(x)
+
+    def selection_adjust(self, index: int | str) -> None:
+        """Extend or shrink the selection to include index.
+
+        Args:
+            index: Target index to adjust the selection endpoint to.
+        """
+        return self._entry.selection_adjust(index)
+
+    def selection_clear(self) -> None:
+        """Clear the current text selection."""
+        return self._entry.selection_clear()
+
+    def selection_from(self, index: int | str) -> None:
+        """Set the selection anchor to index.
+
+        Args:
+            index: The index at which the selection starts.
+        """
+        return self._entry.selection_from(index)
+
+    def selection_to(self, index: int | str) -> None:
+        """Extend the selection from the anchor to index.
+
+        Args:
+            index: The index at which the selection ends.
+        """
+        return self._entry.selection_to(index)
+
+    def selection_range(self, first: int | str, last: int | str) -> None:
+        """Select the text between first and last.
+
+        Args:
+            first: Start index (inclusive).
+            last: End index (exclusive). Use `'end'` for the last character.
+        """
+        return self._entry.selection_range(first, last)
+
+    def selection_present(self) -> bool:
+        """Return True if any text is currently selected.
+
+        Returns:
+            True if a selection exists, False otherwise.
+        """
+        return self._entry.selection_present()
+
+    def selection_all(self) -> None:
+        """Select all text in the entry."""
+        return self._entry.selection_range(0, 'end')