bootstack 0.1.0a1__py3-none-any.whl

bootstack/core/capabilities/signals.py

@@ -0,0 +1,242 @@
+"""Signal binding capability for bootstack widgets.
+
+This module provides the core framework service for binding Signals and tkinter
+Variables to widgets. It handles normalization, bidirectional synchronization,
+and lazy creation of Signals.
+
+The widget mixins (TextSignalMixin, SignalMixin) delegate to these functions
+to remain thin glue layers.
+"""
+
+from __future__ import annotations
+
+import tkinter as tk
+from dataclasses import dataclass
+from typing import Any, Callable, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bootstack.core.signals import Signal
+
+
+# =============================================================================
+# Type Detection Helpers
+# =============================================================================
+
+def is_signal(obj: Any) -> bool:
+    """Check if an object is a Signal using duck typing.
+
+    Args:
+        obj: Object to check.
+
+    Returns:
+        True if object has Signal-like interface (var, subscribe, get, set).
+    """
+    return (
+        hasattr(obj, 'var')
+        and hasattr(obj, 'subscribe')
+        and hasattr(obj, 'get')
+        and hasattr(obj, 'set')
+    )
+
+
+def is_variable(obj: Any) -> bool:
+    """Check if an object is a tkinter Variable.
+
+    Args:
+        obj: Object to check.
+
+    Returns:
+        True if object is a tkinter Variable instance.
+    """
+    return isinstance(obj, tk.Variable)
+
+
+# =============================================================================
+# Signal Binding Result
+# =============================================================================
+
+@dataclass
+class SignalBinding:
+    """Result of normalizing a Signal or Variable for widget binding.
+
+    Attributes:
+        signal: The Signal instance (created or provided).
+        variable: The underlying tk.Variable for widget configuration.
+        tk_value: The value to pass to the ttk widget's configure method.
+    """
+    signal: 'Signal[Any]'
+    variable: tk.Variable
+    tk_value: tk.Variable
+
+
+# =============================================================================
+# Normalization Functions
+# =============================================================================
+
+def normalize_signal(
+    value: Any,
+    *,
+    default_value: Any = "",
+) -> SignalBinding | None:
+    """Normalize a Signal, Variable, or value into a SignalBinding.
+
+    This function handles the conversion logic for binding signals to widgets.
+    It accepts either a Signal, a tk.Variable, or passes through None/strings.
+
+    Args:
+        value: The value to normalize. Can be:
+            - A Signal instance: extracts the underlying variable
+            - A tk.Variable: wraps it in a Signal
+            - None: returns None (no binding)
+            - A string (Tcl variable name): returns None (let caller handle)
+        default_value: Default value for creating new Signals (unused for
+            existing Signal/Variable).
+
+    Returns:
+        A SignalBinding with the signal, variable, and tk_value, or None if
+        the value cannot be normalized (e.g., string Tcl name, None).
+
+    Examples:
+        >>> from bootstack.core.signals import Signal
+        >>> sig = Signal("hello")
+        >>> binding = normalize_signal(sig)
+        >>> binding.signal is sig
+        True
+        >>> binding.variable is sig.var
+        True
+
+        >>> var = tk.StringVar(value="world")
+        >>> binding = normalize_signal(var)
+        >>> binding.variable is var
+        True
+        >>> binding.signal.get()
+        'world'
+    """
+    if value is None:
+        return None
+
+    if is_signal(value):
+        # It's a Signal - extract the variable
+        return SignalBinding(
+            signal=value,
+            variable=value.var,
+            tk_value=value.var,
+        )
+
+    if is_variable(value):
+        # It's a tk.Variable - wrap it in a Signal
+        from bootstack.core.signals import Signal
+        signal = Signal.from_variable(value)
+        return SignalBinding(
+            signal=signal,
+            variable=value,
+            tk_value=value,
+        )
+
+    # String (Tcl variable name) or other - cannot normalize
+    return None
+
+
+def create_signal(default_value: Any) -> SignalBinding:
+    """Create a new Signal with the given default value.
+
+    Args:
+        default_value: The initial value for the Signal.
+
+    Returns:
+        A SignalBinding with the new signal, variable, and tk_value.
+
+    Examples:
+        >>> binding = create_signal("")
+        >>> binding.signal.get()
+        ''
+        >>> binding = create_signal(0.0)
+        >>> binding.signal.get()
+        0.0
+    """
+    from bootstack.core.signals import Signal
+    signal = Signal(default_value)
+    return SignalBinding(
+        signal=signal,
+        variable=signal.var,
+        tk_value=signal.var,
+    )
+
+
+def infer_default_value_for_widget(widget_class: str) -> Any:
+    """Infer an appropriate default value based on widget class.
+
+    Args:
+        widget_class: The Tk widget class name (e.g., "TCheckbutton", "TScale").
+
+    Returns:
+        An appropriate default value for the widget type:
+        - False for checkbuttons
+        - 0 for radiobuttons
+        - 0.0 for scales
+        - 0 for progressbars
+        - "" for others
+    """
+    # Checkbutton typically uses boolean
+    if widget_class in ('TCheckbutton', 'Checkbutton'):
+        return False
+    # Radiobutton typically uses int
+    elif widget_class in ('TRadiobutton', 'Radiobutton'):
+        return 0
+    # Scale uses float
+    elif widget_class in ('TScale', 'Scale'):
+        return 0.0
+    # Progressbar uses int
+    elif widget_class in ('TProgressbar', 'Progressbar'):
+        return 0
+    # Default to empty string
+    else:
+        return ""
+
+
+# =============================================================================
+# Query Functions
+# =============================================================================
+
+def query_binding(
+    stored_signal: 'Signal[Any] | None',
+    stored_variable: tk.Variable | None,
+    ttk_base: type,
+    widget: Any,
+    option_name: str,
+) -> 'Signal[Any] | tk.Variable | None':
+    """Query the current signal/variable binding for a widget option.
+
+    Returns the signal if available, otherwise the variable, otherwise
+    queries the widget directly.
+
+    Args:
+        stored_signal: The cached Signal, if any.
+        stored_variable: The cached Variable, if any.
+        ttk_base: The ttk base class for querying.
+        widget: The widget instance.
+        option_name: The option name to query ("textvariable" or "variable").
+
+    Returns:
+        The Signal if stored, else the Variable if stored, else the widget's
+        configured value for the option.
+    """
+    if stored_signal is not None:
+        return stored_signal
+    if stored_variable is not None:
+        return stored_variable
+    try:
+        return ttk_base.cget(widget, option_name)
+    except Exception:
+        return None
+
+
+__all__ = [
+    "is_signal",
+    "is_variable",
+    "SignalBinding",
+    "normalize_signal",
+    "create_signal",
+    "infer_default_value_for_widget",
+    "query_binding",
+]

bootstack/core/capabilities/winfo.py

@@ -0,0 +1,315 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class WinfoMixin:
+    """Widget information (winfo) helpers.
+
+    Tk uses the term **window** to mean **any widget** with a Tk window handle
+    (not just a `Toplevel`). In bootstack documentation we use the word
+    **widget** unless we specifically mean a top-level window.
+
+    Tk's `winfo` command family exposes runtime information about a widget/window:
+    geometry, hierarchy, mapping/visibility, pointer location, screen metrics, and more.
+
+    This mixin provides thin pass-through methods with modern Google-style
+    docstrings for commonly used `winfo_*` APIs in Tkinter.
+
+    Intended usage:
+        class Widget(WinfoMixin, ttk.Widget): ...
+        class App(WinfoMixin, tkinter.Tk): ...
+        class Window(WinfoMixin, tkinter.Toplevel): ...
+
+    Notes:
+        - All methods delegate to the underlying Tkinter implementation.
+        - Many `winfo_*` values are only meaningful after the widget has been
+          realized and geometry has been computed. If you need up-to-date sizes,
+          call `update_idletasks()` first.
+    """
+
+    # -------------------------------------------------------------------------
+    # Existence / mapping / visibility
+    # -------------------------------------------------------------------------
+
+    def winfo_exists(self) -> int:
+        """Return whether this widget exists.
+
+        Returns:
+            1 if the widget exists, 0 otherwise.
+        """
+        return super().winfo_exists()  # type: ignore[misc]
+
+    def winfo_ismapped(self) -> int:
+        """Return whether this widget is currently mapped (shown) on screen.
+
+        A widget may exist but not be mapped (e.g., never packed/gridded/placed,
+        or explicitly unmapped).
+
+        Returns:
+            1 if mapped, 0 otherwise.
+        """
+        return super().winfo_ismapped()  # type: ignore[misc]
+
+    def winfo_viewable(self) -> int:
+        """Return whether this widget and all its ancestors are mapped.
+
+        A widget can be mapped but not viewable if an ancestor is not mapped.
+
+        Returns:
+            1 if viewable, 0 otherwise.
+        """
+        return super().winfo_viewable()  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Widget identity / hierarchy
+    # -------------------------------------------------------------------------
+
+    def winfo_id(self) -> int:
+        """Return a platform-specific identifier for the underlying window.
+
+        Returns:
+            An integer window identifier. Meaning varies by platform.
+        """
+        return super().winfo_id()  # type: ignore[misc]
+
+    def winfo_name(self) -> str:
+        """Return the widget's Tk name (path component, not full path).
+
+        Returns:
+            The widget's name (e.g. "button", "frame", etc.).
+        """
+        return super().winfo_name()  # type: ignore[misc]
+
+    def winfo_pathname(self, id: int, displayof: int | None = None) -> str:
+        """Return the Tk pathname for a window id.
+
+        This is an advanced helper; most apps won't need it.
+
+        Args:
+            id: A platform-specific window id (often from `winfo_id()`).
+            displayof: Optional display selector (Tk-specific). Rarely needed.
+
+        Returns:
+            The Tk pathname corresponding to `id`.
+        """
+        if displayof is None:
+            return super().winfo_pathname(id)  # type: ignore[misc]
+        return super().winfo_pathname(id, displayof)  # type: ignore[misc]
+
+    def winfo_parent(self) -> str:
+        """Return the Tk pathname of this widget's parent.
+
+        Returns:
+            The parent's Tk pathname.
+        """
+        return super().winfo_parent()  # type: ignore[misc]
+
+    def winfo_toplevel(self) -> Any:
+        """Return the toplevel window that contains this widget.
+
+        Returns:
+            The toplevel widget instance.
+        """
+        return super().winfo_toplevel()  # type: ignore[misc]
+
+    def winfo_children(self) -> list[Any]:
+        """Return this widget's direct children.
+
+        Returns:
+            A list of child widget instances.
+        """
+        return super().winfo_children()  # type: ignore[misc]
+
+    def winfo_class(self) -> str:
+        """Return the Tk class name for this widget (e.g. 'TButton').
+
+        Returns:
+            The Tk class name string.
+        """
+        return super().winfo_class()  # type: ignore[misc]
+
+    def winfo_manager(self) -> str:
+        """Return the geometry manager controlling this widget.
+
+        Typical values are: "pack", "grid", "place", or "" if unmanaged.
+
+        Returns:
+            The name of the geometry manager or an empty string.
+        """
+        return super().winfo_manager()  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Geometry: local position/size (relative to parent)
+    # -------------------------------------------------------------------------
+
+    def winfo_x(self) -> int:
+        """Return the x-coordinate of this widget relative to its parent.
+
+        Returns:
+            The x position in pixels.
+        """
+        return super().winfo_x()  # type: ignore[misc]
+
+    def winfo_y(self) -> int:
+        """Return the y-coordinate of this widget relative to its parent.
+
+        Returns:
+            The y position in pixels.
+        """
+        return super().winfo_y()  # type: ignore[misc]
+
+    def winfo_width(self) -> int:
+        """Return the current width of this widget in pixels.
+
+        Note:
+            Geometry may be stale until Tk processes idle tasks. Use
+            `update_idletasks()` if you need a fresh value.
+
+        Returns:
+            The width in pixels.
+        """
+        return super().winfo_width()  # type: ignore[misc]
+
+    def winfo_height(self) -> int:
+        """Return the current height of this widget in pixels.
+
+        Note:
+            Geometry may be stale until Tk processes idle tasks. Use
+            `update_idletasks()` if you need a fresh value.
+
+        Returns:
+            The height in pixels.
+        """
+        return super().winfo_height()  # type: ignore[misc]
+
+    def winfo_reqwidth(self) -> int:
+        """Return the requested width (geometry request) in pixels.
+
+        This is the size the widget asks for before geometry management.
+
+        Returns:
+            The requested width in pixels.
+        """
+        return super().winfo_reqwidth()  # type: ignore[misc]
+
+    def winfo_reqheight(self) -> int:
+        """Return the requested height (geometry request) in pixels.
+
+        This is the size the widget asks for before geometry management.
+
+        Returns:
+            The requested height in pixels.
+        """
+        return super().winfo_reqheight()  # type: ignore[misc]
+
+    def winfo_rootx(self) -> int:
+        """Return the absolute x-coordinate of this widget on the screen.
+
+        Returns:
+            The screen x position in pixels.
+        """
+        return super().winfo_rootx()  # type: ignore[misc]
+
+    def winfo_rooty(self) -> int:
+        """Return the absolute y-coordinate of this widget on the screen.
+
+        Returns:
+            The screen y position in pixels.
+        """
+        return super().winfo_rooty()  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Pointer (mouse) information
+    # -------------------------------------------------------------------------
+
+    def winfo_pointerx(self) -> int:
+        """Return the pointer x-coordinate on the screen.
+
+        This returns the mouse pointer position in screen (root) coordinates.
+
+        Returns:
+            The screen x position of the pointer in pixels.
+        """
+        return super().winfo_pointerx()  # type: ignore[misc]
+
+    def winfo_pointery(self) -> int:
+        """Return the pointer y-coordinate on the screen.
+
+        This returns the mouse pointer position in screen (root) coordinates.
+
+        Returns:
+            The screen y position of the pointer in pixels.
+        """
+        return super().winfo_pointery()  # type: ignore[misc]
+
+    def winfo_pointerxy(self) -> tuple[int, int]:
+        """Return the pointer (x, y) coordinates on the screen.
+
+        Returns:
+            A tuple (x, y) in screen (root) coordinates.
+        """
+        return super().winfo_pointerxy()  # type: ignore[misc]
+
+    def winfo_containing(self, rootx: int, rooty: int) -> Any:
+        """Return the widget that contains the given screen coordinate.
+
+        Args:
+            rootx: Screen x coordinate in pixels.
+            rooty: Screen y coordinate in pixels.
+
+        Returns:
+            The widget instance at that screen coordinate, or None if no widget
+            is present at that location.
+        """
+        return super().winfo_containing(rootx, rooty)  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Screen / display metrics
+    # -------------------------------------------------------------------------
+
+    def winfo_screenwidth(self) -> int:
+        """Return the width of the screen in pixels.
+
+        Returns:
+            Screen width in pixels.
+        """
+        return super().winfo_screenwidth()  # type: ignore[misc]
+
+    def winfo_screenheight(self) -> int:
+        """Return the height of the screen in pixels.
+
+        Returns:
+            Screen height in pixels.
+        """
+        return super().winfo_screenheight()  # type: ignore[misc]
+
+    def winfo_fpixels(self, number: str) -> float:
+        """Convert a distance string to pixels (floating point).
+
+        Tk distance strings can include units like:
+            - "c" (centimeters)
+            - "i" (inches)
+            - "m" (millimeters)
+            - "p" (points)
+
+        Plain numbers are pixels.
+
+        Args:
+            number: A Tk distance string (e.g. "2c", "0.5i", "10").
+
+        Returns:
+            The distance in pixels as a float.
+        """
+        return super().winfo_fpixels(number)  # type: ignore[misc]
+
+    def winfo_pixels(self, number: str) -> int:
+        """Convert a distance string to pixels (integer).
+
+        Args:
+            number: A Tk distance string (e.g. "2c", "0.5i", "10").
+
+        Returns:
+            The distance in pixels as an int (rounded by Tk).
+        """
+        return super().winfo_pixels(number)  # type: ignore[misc]