bootstack 0.1.0a1__py3-none-any.whl

bootstack/core/mixins/widget.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from typing import Mapping, Any
+
+from bootstack.core.capabilities.after import AfterMixin
+from bootstack.core.capabilities.bind import BindingsMixin
+from bootstack.core.capabilities.bindtags import BindtagsMixin
+from bootstack.core.capabilities.clipboard import ClipboardMixin
+from bootstack.core.capabilities.focus import FocusMixin
+from bootstack.core.capabilities.grab import GrabMixin
+from bootstack.core.capabilities.grid import GridMixin
+from bootstack.core.capabilities.pack import PackMixin
+from bootstack.core.capabilities.place import PlaceMixin
+from bootstack.core.capabilities.selection import SelectionMixin
+from bootstack.core.capabilities.winfo import WinfoMixin
+
+
+class WidgetCapabilitiesMixin(
+    AfterMixin,
+    BindingsMixin,
+    BindtagsMixin,
+    ClipboardMixin,
+    FocusMixin,
+    GrabMixin,
+    GridMixin,
+    PackMixin,
+    PlaceMixin,
+    SelectionMixin,
+    WinfoMixin,
+):
+    """Common widget API surface (tk + ttk).
+
+    This mixin aggregates documented capability mixins into a single interface
+    suitable for both Tk and ttk widgets, plus a small set of commonly used
+    widget operations (configure/cget/destroy, stacking order, etc.).
+    """
+
+    # -------------------------------------------------------------------------
+    # Lifecycle
+    # -------------------------------------------------------------------------
+
+    def destroy(self) -> None:
+        """Destroy this widget and release its Tk resources."""
+        return super().destroy()  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Configuration
+    # -------------------------------------------------------------------------
+
+    def configure(self, cnf: Mapping[str, Any] | None = None, **kw: Any) -> Any:
+        """Configure widget options.
+
+        Args:
+            cnf: Optional mapping of option values.
+            **kw: Option values as keyword arguments.
+
+        Returns:
+            Tk returns configuration details when called with no args; otherwise
+            the return value is implementation-dependent.
+        """
+        if cnf is None:
+            return super().configure(**kw)  # type: ignore[misc]
+        return super().configure(cnf, **kw)  # type: ignore[misc]
+
+    config = configure
+
+    def cget(self, key: str) -> Any:
+        """Return the current value for an option.
+
+        Args:
+            key: Option name (with or without a leading dash).
+
+        Returns:
+            The option value.
+        """
+        return super().cget(key)  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Stacking order
+    # -------------------------------------------------------------------------
+
+    def lift(self, aboveThis: Any | None = None) -> None:
+        """Raise this widget above its siblings.
+
+        Args:
+            aboveThis: Optional sibling widget to raise above.
+        """
+        return super().lift(aboveThis)  # type: ignore[misc]
+
+    tkraise = lift
+
+    def lower(self, belowThis: Any | None = None) -> None:
+        """Lower this widget below its siblings.
+
+        Args:
+            belowThis: Optional sibling widget to lower below.
+        """
+        return super().lower(belowThis)  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Layout convenience
+    # -------------------------------------------------------------------------
+
+    def forget(self) -> None:
+        """Remove the widget from layout (best-effort).
+
+        This calls the appropriate forget method depending on the active geometry manager:
+
+            - grid  -> grid_forget()
+            - pack  -> pack_forget()
+            - place -> place_forget()
+        """
+        try:
+            mgr = self.winfo_manager()  # type: ignore[attr-defined]
+        except Exception:
+            mgr = ""
+
+        if mgr == "grid":
+            try:
+                self.grid_forget()  # type: ignore[attr-defined]
+            except Exception:
+                pass
+        elif mgr == "pack":
+            try:
+                self.pack_forget()  # type: ignore[attr-defined]
+            except Exception:
+                pass
+        elif mgr == "place":
+            try:
+                self.place_forget()  # type: ignore[attr-defined]
+            except Exception:
+                pass

bootstack/core/publisher.py

@@ -0,0 +1,147 @@
+"""Publisher-Subscriber pattern implementation for bootstack.
+
+This module implements a simple publisher-subscriber (pub-sub) pattern used
+for theme change notifications and widget updates throughout bootstack.
+
+The Publisher class manages subscribers on different channels and broadcasts
+messages to all subscribers when events occur (like theme changes).
+
+Classes:
+    Channel: Enum defining subscriber channels (STD for tk, TTK for ttk)
+    Subscriber: Data class storing subscriber information
+    Publisher: Manages subscriptions and publishes messages to subscribers
+
+Example:
+    ```python
+    from bootstack.publisher import Publisher, Channel
+
+    # Subscribe a function to theme changes
+    def on_theme_change():
+        print("Theme changed!")
+
+    Publisher.subscribe(
+        func=on_theme_change,
+        channel=Channel.TTK
+    )
+
+    # Publish a message to all TTK subscribers
+    Publisher.publish(Channel.TTK)
+    ```
+"""
+from enum import Enum
+from typing import List
+
+
+class Channel(Enum):
+    """A grouping for Publisher subscribers. Indicates whether the
+    widget is a legacy `STD` tk widget or a styled `TTK` widget.
+
+    Attributes:
+
+        STD (1):
+            Legacy tkinter widgets.
+
+        TTK (2):
+            Themed tkinter widgets.
+    """
+
+    STD = 1
+    TTK = 2
+
+
+class Subscriber:
+    """A subscriber data class used to store information about a specific
+    subscriber to the `Publisher`."""
+
+    def __init__(self, name, func, channel):
+        """Create a subscriber.
+
+        Parameters:
+
+            name (str):
+                The name of the subscriber
+
+            func (Callable):
+                The function to call when messaging.
+
+            channel (Channel):
+                The subscription channel.
+        """
+        self.name = name
+        self.func = func
+        self.channel = channel
+
+
+class Publisher:
+    """Publish events to subscribed widgets for theme changes or configuration updates."""
+
+    __subscribers = {}
+
+    @staticmethod
+    def subscriber_count():
+        return len(Publisher.__subscribers)
+
+    @staticmethod
+    def subscribe(name, func, channel):
+        """Subscribe to an event.
+
+        Parameters:
+
+            name (str):
+                The widget's tkinter/tcl name.
+
+            func (Callable):
+                A function to call when passing a message.
+
+            channel (Channel):
+                Indicates the channel grouping the subscribers.
+        """
+        subs = Publisher.__subscribers
+        subs[name] = Subscriber(name, func, channel)
+
+    @staticmethod
+    def unsubscribe(name):
+        """Remove a subscriber.
+
+        Parameters:
+
+            name (str):
+                The widget's tkinter/tcl name.
+        """
+        subs = Publisher.__subscribers
+        try:
+            del subs[str(name)]
+        except:
+            pass
+
+    def get_subscribers(channel):
+        """Return a list of subscribers.
+
+        Returns:
+
+            List:
+                List of key-value tuples
+        """
+        subs = Publisher.__subscribers.values()
+        channel_subs = [s for s in subs if s.channel == channel]
+        return channel_subs
+
+    def publish_message(channel, *args):
+        """Publish a message to all subscribers.
+
+        Parameters:
+
+            channel (Channel):
+                The name of the channel to subscribe.
+
+            **args:
+                optional arguments to pass to the subscribers.
+        """
+        subs: list[Subscriber] = Publisher.get_subscribers(channel)
+        for sub in subs:
+            sub.func(*args)
+
+    @staticmethod
+    def clear_subscribers():
+        """Reset all subscriptions."""
+        Publisher.__subscribers.clear()

bootstack/core/signals/README.md

@@ -0,0 +1,112 @@
+Signals for ttkbootstrap
+========================
+
+Lightweight reactive state built on top of tkinter's ``Variable`` API.
+Signals wrap a ``tk.Variable`` and provide a small, typed interface for
+reading, writing, deriving, and subscribing to changes.
+
+Architecture
+- ``Signal[T]``: Generic wrapper around a ``tk.Variable`` with ``get()``,
+  ``set()``, ``subscribe()``, and ``map()``.
+- ``_SignalTrace`` (internal): Manages Tcl traces for a variable
+  (``trace_add``/``trace_remove``).
+- ``TraceOperation``: Literal type alias for trace operations
+  ("array", "read", "write", "unset").
+
+Key behaviors
+- Value access: ``signal()`` or ``signal.get()`` returns the current value;
+  ``signal.set(v)`` updates it. Signals can be passed directly to widget
+  options like ``textvariable``/``variable``; tkinter uses their Tcl name.
+- Subscriptions: ``subscribe(cb, immediate=False)`` registers a callback and
+  returns a trace id. Multiple subscriptions of the same callback are supported.
+  Use ``unsubscribe(cb)`` to remove all subscriptions for that callback or
+  ``unsubscribe_all()`` to clear all.
+- Derived signals: ``map(transform)`` creates a new signal that follows this
+  one using a transform function. A weak reference prevents the parent from
+  keeping derived signals alive unnecessarily.
+- Robustness: The last known value is cached and returned if the underlying
+  Tcl variable is destroyed. Redundant updates are skipped when the new value
+  equals the current one. Exact type matching is enforced in ``set()``.
+
+Usage
+1) Quick start
+```python
+from ttkbootstrap.core.signals import Signal
+
+count = Signal(0)
+print(count.get())    # -> 0
+count.set(1)
+print(count())        # -> 1 (callable alias of get)
+```
+
+2) With widgets
+```python
+import tkinter as tk
+import ttkbootstrap as ttk
+from ttkbootstrap.core.signals import Signal
+
+root = ttk.Window()
+name = Signal("")
+
+entry = ttk.Entry(root, textvariable=name)
+entry.pack()
+
+label = ttk.Label(root)
+label.pack()
+
+name.subscribe(lambda v: label.configure(text=f"Hello, {v}!"), immediate=True)
+
+root.mainloop()
+```
+
+3) Derived signals with ``map``
+```python
+from ttkbootstrap.core.signals import Signal
+
+price = Signal(10.0)
+with_tax = price.map(lambda p: round(p * 1.07, 2))
+
+with_tax.subscribe(lambda v: print("price with tax:", v), immediate=True)
+price.set(12.0)
+```
+
+4) Wrap existing tkinter variables
+```python
+import tkinter as tk
+from ttkbootstrap.core.signals import Signal
+
+root = tk.Tk()
+tk_var = tk.IntVar(value=5)
+sig = Signal.from_variable(tk_var)
+
+sig.subscribe(print, immediate=True)  # -> 5
+tk_var.set(6)  # prints 6
+sig.set(7)     # keeps both in sync
+```
+
+5) Multiple subscriptions and immediate firing
+```python
+from ttkbootstrap.core.signals import Signal
+
+flag = Signal(False)
+
+fid1 = flag.subscribe(lambda v: print("A:", v), immediate=True)
+fid2 = flag.subscribe(lambda v: print("B:", v))
+
+flag.set(True)  # triggers both
+
+flag.unsubscribe(lambda v: print("B:", v))  # remove all B callbacks
+```
+
+Import path
+- Public API is re-exported at the package level:
+  - ``from ttkbootstrap.core.signals import Signal, TraceOperation``
+
+Notes
+- Tkinter is not thread-safe. Perform cross-thread updates using ``after``
+  on a Tk widget.
+- Callbacks should be fast; long-running work should be scheduled off the UI
+  thread.
+ - Create ``Signal`` after you create the Tk/Window so the underlying
+   ``tk.Variable`` is attached to the same interpreter, or pass ``master=...``
+   when constructing ``Signal``.

bootstack/core/signals/__init__.py

@@ -0,0 +1,8 @@
+"""Reactive signal primitives for bootstack widgets."""
+from .signal import Signal
+from .types import TraceOperation
+
+__all__ = [
+    "Signal",
+    "TraceOperation",
+]

bootstack/core/signals/integration.py

@@ -0,0 +1,100 @@
+"""Integration helpers for using Signal with tkinter/ttk widgets.
+
+Call `enable_widget_integration()` once early (after creating your Tk/Window)
+to allow passing `Signal` objects directly to widget constructors and
+`configure(...)` for options like `textvariable` and `variable`.
+
+Without this, some environments/widgets may not coerce custom objects to the
+required Tcl variable name automatically.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Iterable, Tuple
+
+import tkinter as tk
+import tkinter.ttk as ttk
+
+
+def _is_signal(obj: Any) -> bool:
+    try:
+        # Cheap duck-typing to avoid hard import dependency
+        m = type(obj).__module__
+        return (
+            (m.startswith("bootstack.signals") or m.startswith("bootstack.core.signals"))
+            and hasattr(obj, "name")
+            and hasattr(obj, "var")
+        )
+    except Exception:
+        return False
+
+
+def _coerce_kwargs(kwargs: dict[str, Any]) -> None:
+    for key in ("textvariable", "variable"):
+        if key in kwargs:
+            val = kwargs[key]
+            if _is_signal(val):
+                kwargs[key] = str(val)
+
+
+def _wrap_init(cls: type) -> None:
+    orig_init = cls.__init__  # type: ignore[attr-defined]
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:  # type: ignore[override]
+        _coerce_kwargs(kwargs)
+        orig_init(self, *args, **kwargs)  # type: ignore[misc]
+
+    cls.__init__ = __init__  # type: ignore[assignment]
+
+
+def _wrap_configure(cls: type) -> None:
+    orig_config = cls.configure  # type: ignore[attr-defined]
+
+    def configure(self, cnf: Any = None, **kwargs: Any):  # type: ignore[override]
+        if isinstance(cnf, dict):
+            _coerce_kwargs(cnf)
+        _coerce_kwargs(kwargs)
+        return orig_config(self, cnf, **kwargs)  # type: ignore[misc]
+
+    cls.configure = configure  # type: ignore[assignment]
+    cls.config = configure  # type: ignore[assignment]
+
+
+def _patch(classes: Iterable[type]) -> None:
+    for cls in classes:
+        _wrap_init(cls)
+        _wrap_configure(cls)
+
+
+def enable_widget_integration() -> None:
+    """Enable passing `Signal` directly to widget options.
+
+    Patches common tk/ttk widget classes so that when you pass a `Signal`
+    instance to `textvariable` or `variable` in the constructor or in
+    `configure(...)`, it is automatically converted to its Tcl name.
+    """
+
+    ttk_classes: Tuple[type, ...] = (
+        ttk.Entry,
+        ttk.Label,
+        ttk.Button,
+        ttk.Checkbutton,
+        ttk.Radiobutton,
+        ttk.Combobox,
+        ttk.Spinbox,
+        ttk.Progressbar,
+        ttk.Scale,
+        ttk.OptionMenu,
+    )
+
+    tk_classes: Tuple[type, ...] = (
+        tk.Entry,
+        tk.Label,
+        tk.Button,
+        tk.Checkbutton,
+        tk.Radiobutton,
+    )
+
+    _patch(ttk_classes)
+    _patch(tk_classes)
+