bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_impl/mixins/signal_mixin.py

@@ -0,0 +1,268 @@
+"""Signal integration mixins for bootstack widgets.
+
+Provides seamless integration between tkinter Variables and reactive Signals,
+exposing both as properties on widgets that support `textvariable` and `variable`
+options. The mixins maintain bidirectional synchronization between Variables and
+Signals automatically.
+
+These mixins are thin glue layers that delegate to the core signal capability
+module for normalization and binding logic.
+"""
+
+from __future__ import annotations
+
+import tkinter as tk
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+from bootstack._core.capabilities.signals import (
+    normalize_signal,
+    create_signal,
+    infer_default_value_for_widget,
+    query_binding,
+)
+from bootstack.widgets._impl.mixins.configure_mixin import configure_delegate
+
+
+class TextSignalMixin:
+    """Mixin providing `.textvariable` and `.textsignal` properties for text-based widgets.
+
+    For widgets that support the `textvariable` option (Entry, Label, Button, etc.),
+    this mixin exposes both the underlying tk.Variable and a reactive Signal as properties,
+    maintaining bidirectional synchronization between them.
+
+    This mixin delegates normalization and binding logic to the core signals capability.
+
+    """
+
+    def __init__(self, *args, **kwargs):
+        """Initialize mixin and extract textsignal/textvariable parameters before tkinter sees them."""
+        # Extract textsignal and textvariable before passing kwargs to tkinter
+        textsignal_value = kwargs.pop('textsignal', None)
+        textvariable_value = kwargs.pop('textvariable', None)
+
+        # Call parent __init__
+        super().__init__(*args, **kwargs)
+
+        # Apply textsignal or textvariable after widget construction
+        # Prefer textsignal if both are provided
+        if textsignal_value is not None:
+            self._config_delegate_set('textsignal', textsignal_value)
+        elif textvariable_value is not None:
+            self._config_delegate_set('textvariable', textvariable_value)
+
+    @configure_delegate("textvariable", "textsignal")
+    def _delegate_textsignal(self, value: Any = None):
+        """Handle textvariable and textsignal configuration.
+
+        Args:
+            value: Signal, tk.Variable, or None for query.
+
+        Returns:
+            Current value for query path, None for set path.
+        """
+        # Query path - return stored value
+        if value is None:
+            return query_binding(
+                getattr(self, '_textsignal', None),
+                getattr(self, '_textvariable', None),
+                self._ttk_base,  # type: ignore[misc]
+                self,
+                'textvariable',
+            )
+
+        # Set path - normalize and apply
+        binding = normalize_signal(value, default_value="")
+        if binding is not None:
+            self._textsignal = binding.signal
+            self._textvariable = binding.variable
+            var_to_set = binding.tk_value
+        else:
+            # String (Tcl variable name) or other - pass through
+            var_to_set = value
+            if value:
+                self._textvariable = value
+
+        # Apply via base ttk widget to avoid recursion
+        return self._ttk_base.configure(self, textvariable=var_to_set)  # type: ignore[misc]
+
+    @property
+    def textsignal(self) -> Signal[str]:
+        """Get or lazily create the textsignal.
+
+        If no textvariable has been set, creates a new Signal with empty string.
+        If textvariable exists, wraps it in a Signal.
+
+        Returns:
+            The reactive Signal for this widget's text.
+        """
+        if not hasattr(self, '_textsignal'):
+            # Create fresh signal
+            binding = create_signal("")
+            self._textsignal = binding.signal
+            self._textvariable = binding.variable
+            try:
+                self._ttk_base.configure(self, textvariable=binding.tk_value)  # type: ignore[misc]
+            except Exception:
+                pass
+        return self._textsignal
+
+    @textsignal.setter
+    def textsignal(self, value: Signal[str]) -> None:
+        """Set the textsignal, extracting and configuring its underlying variable.
+
+        Args:
+            value: Signal to use for this widget's text.
+        """
+        self._delegate_textsignal(value)
+
+    @property
+    def textvariable(self) -> tk.Variable:
+        """Get the underlying tk.Variable.
+
+        If not yet created, accessing this property will trigger lazy creation
+        via the textsignal property.
+
+        Returns:
+            The tk.Variable (usually StringVar) for this widget's text.
+
+        See [tkinter Variables](https://docs.python.org/3/library/tkinter.html#tkinter-variables).
+        """
+        if not hasattr(self, '_textvariable'):
+            # Trigger lazy creation via textsignal
+            _ = self.textsignal
+        return self._textvariable
+
+    @textvariable.setter
+    def textvariable(self, value: tk.Variable) -> None:
+        """Set the textvariable, creating a synced Signal automatically.
+
+        Args:
+            value: tk.Variable to use for this widget's text.
+        """
+        self._delegate_textsignal(value)
+
+
+class SignalMixin:
+    """Mixin providing `.variable` and `.signal` properties for value-based widgets.
+
+    For widgets that support the `variable` option (Checkbutton, Radiobutton, Scale, etc.),
+    this mixin exposes both the underlying tk.Variable and a reactive Signal as properties,
+    maintaining bidirectional synchronization between them.
+
+    This mixin delegates normalization and binding logic to the core signals capability.
+
+    """
+
+    def __init__(self, *args, **kwargs):
+        """Initialize mixin and extract signal/variable parameters before tkinter sees them."""
+        # Extract signal and variable before passing kwargs to tkinter
+        signal_value = kwargs.pop('signal', None)
+        variable_value = kwargs.pop('variable', None)
+
+        # Call parent __init__
+        super().__init__(*args, **kwargs)
+
+        # Apply signal or variable after widget construction
+        # Prefer signal if both are provided
+        if signal_value is not None:
+            self._config_delegate_set('signal', signal_value)
+        elif variable_value is not None:
+            self._config_delegate_set('variable', variable_value)
+
+    @configure_delegate("variable", "signal")
+    def _delegate_signal(self, value: Any = None):
+        """Handle variable and signal configuration.
+
+        Args:
+            value: Signal, tk.Variable, or None for query.
+
+        Returns:
+            Current value for query path, None for set path.
+        """
+        # Query path - return stored value
+        if value is None:
+            return query_binding(
+                getattr(self, '_signal', None),
+                getattr(self, '_variable', None),
+                self._ttk_base,  # type: ignore[misc]
+                self,
+                'variable',
+            )
+
+        # Set path - normalize and apply
+        binding = normalize_signal(value)
+        if binding is not None:
+            self._signal = binding.signal
+            self._variable = binding.variable
+            var_to_set = binding.tk_value
+        else:
+            # String (Tcl variable name) or other - pass through
+            var_to_set = value
+            if value:
+                self._variable = value
+
+        # Apply via base ttk widget to avoid recursion
+        return self._ttk_base.configure(self, variable=var_to_set)  # type: ignore[misc]
+
+    @property
+    def signal(self) -> Signal[Any]:
+        """Get or lazily create the signal.
+
+        If no variable has been set, creates a new Signal with appropriate default
+        (False for Checkbutton, 0 for Scale, etc.). If variable exists, wraps it in a Signal.
+
+        Returns:
+            The reactive Signal for this widget's value.
+        """
+        if not hasattr(self, '_signal'):
+            # Infer default value based on widget type
+            default_value = infer_default_value_for_widget(self.winfo_class())
+            binding = create_signal(default_value)
+            self._signal = binding.signal
+            self._variable = binding.variable
+            try:
+                self._ttk_base.configure(self, variable=binding.tk_value)  # type: ignore[misc]
+            except Exception:
+                pass
+        return self._signal
+
+    @signal.setter
+    def signal(self, value: Signal[Any]) -> None:
+        """Set the signal, extracting and configuring its underlying variable.
+
+        Args:
+            value: Signal to use for this widget's value.
+        """
+        self._delegate_signal(value)
+
+    @property
+    def variable(self) -> tk.Variable:
+        """Get the underlying tk.Variable.
+
+        If not yet created, accessing this property will trigger lazy creation
+        via the signal property.
+
+        Returns:
+            The tk.Variable (IntVar, BooleanVar, DoubleVar, etc.) for this widget's value.
+
+        See [tkinter Variables](https://docs.python.org/3/library/tkinter.html#tkinter-variables).
+        """
+        if not hasattr(self, '_variable'):
+            # Trigger lazy creation via signal
+            _ = self.signal
+        return self._variable
+
+    @variable.setter
+    def variable(self, value: tk.Variable) -> None:
+        """Set the variable, creating a synced Signal automatically.
+
+        Args:
+            value: tk.Variable to use for this widget's value.
+        """
+        self._delegate_signal(value)
+
+
+__all__ = ["TextSignalMixin", "SignalMixin"]

bootstack/widgets/_impl/mixins/validation_mixin.py

@@ -0,0 +1,226 @@
+"""Validation mixin for widgets with enhanced event system.
+
+This mixin provides validation functionality using the enhanced event system
+that allows passing data directly through virtual events.
+"""
+
+from __future__ import annotations
+
+import tkinter
+from tkinter import TclError
+from tkinter.ttk import Widget
+from typing import Any, Callable
+
+from bootstack.events import ValidationEvent
+from bootstack.signals import Signal
+from bootstack.validation import ValidationRule
+from bootstack.validation.types import RuleTriggerType, RuleType, ValidationOptions
+
+
+class ValidationMixin(Widget):
+    """Pure-Tkinter validation mixin for bound widgets.
+
+    Provides debounced auto-validation on key/blur with virtual event emission.
+    Event data is accessible via `event.data` in handlers.
+
+    """
+
+    EVENT_VALID = '<<Valid>>'
+    EVENT_INVALID = '<<Invalid>>'
+    EVENT_VALIDATED = '<<Validate>>'
+    SEQ_KEYUP = '<KeyRelease>'
+    SEQ_BLUR = '<FocusOut>'
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Set up validation state before the widget is fully initialized.
+
+        Initialises the rule list, debounce tracking, and optional convenience
+        callbacks. Binds `<<KeyRelease>>` and `<<FocusOut>>` to trigger
+        debounced validation automatically.
+        """
+        # Validation rules
+        self._rules: list[ValidationRule] = []
+
+        # Debounce tracking
+        self._debounce_ids: dict[str, str] = {}
+
+        # Optional convenience callbacks
+        self._on_invalid_command: Callable | None = None
+        self._on_valid_command: Callable | None = None
+        self._on_validated_command: Callable | None = None
+
+        super().__init__(*args, **kwargs)  # next in MRO must be a Tk/ttk widget
+
+        # Reactive validity state — the source of truth for the field's display
+        # and for form-level aggregation. Updated on every validation run.
+        self._valid_signal: Signal = Signal(True)
+        self._error_signal: Signal = Signal("")
+
+        self._setup_validation_binds()
+
+    def _set_validity(self, is_valid: bool, message: str) -> None:
+        """Update the reactive validity signals (the source of truth)."""
+        self._error_signal.set("" if is_valid else message)
+        self._valid_signal.set(is_valid)
+
+    # ---------------- Public API ----------------
+
+    def value(self) -> Any:
+        """Default value accessor; override for non-Entry widgets.
+
+        Returns:
+            Current widget value
+        """
+        if hasattr(self, 'get'):
+            try:
+                return self.get()
+            except AttributeError:
+                return None
+        return None
+
+    def add_validation_rule(self, rule_type: RuleType, **kwargs: ValidationOptions) -> None:
+        """Add a single validation rule.
+
+        Args:
+            rule_type: Type of validation rule (e.g., 'required', 'min_length')
+            **kwargs: Rule-specific options (e.g., min_length=5, message='...')
+        """
+        self._rules.append(ValidationRule(rule_type, **kwargs))
+
+    def add_validation_rules(self, rules: list[ValidationRule]) -> None:
+        """Replace all validation rules.
+
+        Args:
+            rules: List of ValidationRule objects
+        """
+        self._rules = list(rules)
+
+    def validate(self, value: Any, trigger: RuleTriggerType = "manual") -> bool:
+        """Run validation rules against a value.
+
+        Emits `<<Valid>>`, `<<Invalid>>`, and `<<Validate>>` events
+        with data payload containing validation results.
+
+        Args:
+            value: Value to validate
+            trigger: Trigger type ('manual', 'key', 'blur', or 'always')
+
+        Returns:
+            True if every applicable rule passed (vacuously true when no rule
+            applies for this trigger), False on the first failure.
+        """
+        ran_rule = False
+
+        for rule in self._rules:
+            if trigger != "manual" and rule.trigger not in ("always", trigger):
+                continue
+
+            ran_rule = True
+            result = rule.validate(value)
+
+            if not result.is_valid:
+                # Update validity state, then emit invalid + validated events.
+                self._set_validity(False, result.message)
+                payload = ValidationEvent(value=value, is_valid=False, message=result.message)
+                self.event_generate(self.EVENT_INVALID, data=payload)
+                self.event_generate(self.EVENT_VALIDATED, data=payload)
+                return False
+
+        if ran_rule:
+            # Update validity state, then emit valid + validated events.
+            self._set_validity(True, "")
+            payload = ValidationEvent(value=value, is_valid=True, message="")
+            self.event_generate(self.EVENT_VALID, data=payload)
+            self.event_generate(self.EVENT_VALIDATED, data=payload)
+
+        # Nothing failed — pass (vacuously when no rule ran for this trigger).
+        return True
+
+    # Optional: ergonomic callback registration
+    def on_invalid(self, func: Callable) -> None:
+        """Register callback for `<<Invalid>>`. Callback receives a `ValidationEvent` payload (value, is_valid, message)."""
+        self._on_invalid_command = func
+
+    def off_invalid(self, bind_id: str | None = None) -> None:
+        """Unsubscribe from `<<Invalid>>` events.
+
+        Args:
+            bind_id: ID returned by `on_invalid()`. If None, removes all bindings.
+        """
+        self.unbind('<<Invalid>>', bind_id)
+
+    def on_valid(self, func: Callable) -> None:
+        """Register callback for `<<Valid>>`. Callback receives a `ValidationEvent` payload (value, is_valid, message)."""
+        self._on_valid_command = func
+
+    def off_valid(self, bind_id: str | None = None) -> None:
+        """Unsubscribe from `<<Valid>>` events.
+
+        Args:
+            bind_id: ID returned by `on_valid()`. If None, removes all bindings.
+        """
+        self.unbind('<<Valid>>', bind_id)
+
+    def on_validated(self, func: Callable) -> None:
+        """Register callback for `<<Validate>>`. Callback receives a `ValidationEvent` payload (value, is_valid, message)."""
+        self._on_validated_command = func
+
+    def off_validated(self, bind_id: str | None = None) -> None:
+        """Unsubscribe from `<<Validate>>` events.
+
+        Args:
+            bind_id: ID returned by `on_validated()`. If None, removes all bindings.
+        """
+        self.unbind('<<Validate>>', bind_id)
+
+    # ---------------- Internals ----------------
+
+    def _get_validation_value(self) -> Any:
+        """Get the current value for validation purposes.
+
+        For entry widgets, this should return the current text being typed,
+        not the committed value. Prefers get() method over value() method.
+        """
+        if hasattr(self, 'get'):
+            try:
+                return self.get()
+            except (AttributeError, TclError):
+                pass
+        return self.value()
+
+    def _setup_validation_binds(self, keyup_delay_ms: int = 50, blur_delay_ms: int = 50) -> None:
+        """Set up automatic validation bindings with debouncing."""
+        # Auto-validate (debounced)
+        self.bind(self.SEQ_KEYUP, lambda e: self._debounced("key", keyup_delay_ms), add=True)
+        self.bind(self.SEQ_BLUR, lambda e: self._debounced("blur", blur_delay_ms), add=True)
+
+        # Wire optional convenience callbacks
+        self.bind(self.EVENT_VALIDATED, self._dispatch_validated, add=True)
+        self.bind(self.EVENT_VALID, self._dispatch_valid, add=True)
+        self.bind(self.EVENT_INVALID, self._dispatch_invalid, add=True)
+
+    def _debounced(self, trigger: RuleTriggerType, ms: int) -> None:
+        """Debounce validation to avoid excessive checks during typing."""
+        key = f"debounce:{trigger}"
+        aid: str | None = self._debounce_ids.get(key)
+        if aid:
+            try:
+                self.after_cancel(aid)
+            except TclError:
+                pass
+        # defer reading value until the timer fires
+        self._debounce_ids[key] = self.after(ms, lambda: self.validate(self._get_validation_value(), trigger))
+
+    # ----- optional dispatchers for on_* convenience -----
+
+    def _dispatch_validated(self, event: tkinter.Event) -> None:
+        if self._on_validated_command:
+            self._on_validated_command(event)
+
+    def _dispatch_valid(self, event: tkinter.Event) -> None:
+        if self._on_valid_command:
+            self._on_valid_command(event)
+
+    def _dispatch_invalid(self, event: tkinter.Event) -> None:
+        if self._on_invalid_command:
+            self._on_invalid_command(event)

bootstack/widgets/_impl/primitives/__init__.py

@@ -0,0 +1,49 @@
+"""Primitive bootstack widgets."""
+
+from .badge import Badge
+from .button import Button
+from .card import Card
+from .checkbutton import CheckButton
+from .checktoggle import CheckToggle
+from .combobox import Combobox
+from .entry import Entry
+from .frame import Frame
+from .gridframe import GridFrame
+from .label import Label
+from .labelframe import LabelFrame
+from .packframe import PackFrame
+from .panedwindow import PanedWindow
+from .progressbar import Progressbar
+from .radiobutton import RadioButton
+from .radiotoggle import RadioToggle
+from .scrollbar import Scrollbar
+from .separator import Separator
+from .sizegrip import SizeGrip
+from .spinbox import Spinbox
+from .switch import Switch
+from .treeview import TreeView
+
+__all__ = [
+    "Badge",
+    "Button",
+    "Card",
+    "CheckButton",
+    "CheckToggle",
+    "Combobox",
+    "Entry",
+    "Frame",
+    "GridFrame",
+    "Label",
+    "LabelFrame",
+    "PackFrame",
+    "PanedWindow",
+    "Progressbar",
+    "RadioButton",
+    "RadioToggle",
+    "Scrollbar",
+    "Separator",
+    "SizeGrip",
+    "Spinbox",
+    "Switch",
+    "TreeView",
+]

bootstack/widgets/_impl/primitives/_menubutton.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any, Literal, TYPE_CHECKING
+
+from typing_extensions import Unpack
+
+from bootstack._core.mixins.ttk_state import TtkStateMixin
+from bootstack._core.mixins.widget import WidgetCapabilitiesMixin
+from bootstack.widgets._impl._internal.wrapper_base import TTKWrapperBase
+from bootstack.widgets._impl.mixins import IconMixin, LocalizationMixin, TextSignalMixin
+from bootstack.widgets.types import Master, StyledKwargs, CompoundMode, WidgetState, WidgetDensity
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+
+class MenuButtonKwargs(StyledKwargs, total=False):
+    # Standard ttk.Menubutton options
+    text: Any
+    image: Any
+    icon: Any
+    icon_only: bool
+    compound: CompoundMode
+    direction: Any
+    menu: Any
+    padding: Any
+    state: WidgetState
+    textvariable: Any
+    textsignal: Signal[Any]
+
+    # bootstack-specific extensions
+    density: WidgetDensity
+    localize: bool | Literal['auto']
+
+
+class MenuButton(LocalizationMixin, TextSignalMixin, IconMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Menubutton):
+    """bootstack wrapper for `ttk.Menubutton` with themed styling and icon support."""
+
+    _ttk_base = ttk.Menubutton
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[MenuButtonKwargs]) -> None:
+        """Create a themed bootstack Menubutton.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            text: Text to display in the menubutton.
+            image: Image to display.
+            icon: Theme-aware icon spec handled by the style system.
+            icon_only: If True, removes the additional padding reserved for label text.
+            compound: Placement of the image relative to text.
+            direction: Direction for the menu to appear.
+            menu: Associated tk.Menu instance.
+            padding: Extra space around the content.
+            density: Widget density — 'default' or 'compact'.
+            state: Widget state — 'normal', 'active', 'disabled', or 'readonly'.
+            takefocus: Whether the widget participates in focus traversal.
+            textvariable: Tk variable linked to the text.
+                See [tkinter Variables](https://docs.python.org/3/library/tkinter.html#tkinter-variables).
+            textsignal: Reactive Signal linked to the text (auto-synced with textvariable).
+            style: Explicit ttk style name (overrides accent/variant).
+            accent: Accent token for styling, e.g. 'primary', 'danger', 'success'.
+            variant: Style variant, e.g. 'solid', 'outline', 'ghost'.
+            surface: Optional surface token; otherwise inherited.
+            style_options: Optional dict forwarded to the style builder.
+            localize: Determines the widget's localization mode.
+        """
+        kwargs.update(style_options=self._capture_style_options(['icon_only', 'icon', 'density'], kwargs))
+        super().__init__(master, **kwargs)
+
+        # When a native tk.Menu is attached, post it ourselves with the
+        # focus-ring affordance offset so it aligns with the visible button
+        # border. Subclasses (OptionMenu, DropdownButton) use a ContextMenu
+        # and override show_menu, so this only affects the native path.
+        # On Aqua, Tk's native Menubutton class binding drives an NSMenu
+        # state machine that manages mouse/focus capture; bypassing it with
+        # a manual `menu post` strands focus after item selection, so we
+        # skip the offset path on Mac and let the default class binding run.
+        if self.tk.call('tk', 'windowingsystem') != 'aqua':
+            self.bind("<Button-1>", self._on_button_press, add="+")
+
+    def _on_button_press(self, _event):
+        """Focus self, and if a native menu is attached, post it with offset."""
+        self.focus_set()
+        try:
+            menu_path = self.cget('menu')
+        except Exception:
+            menu_path = None
+        if not menu_path:
+            return None
+        try:
+            # If the menu is already visible, unpost so a second click closes it.
+            if int(self.tk.eval(f"winfo viewable {menu_path}")):
+                self.tk.call(menu_path, 'unpost')
+                return 'break'
+            from bootstack.style.style_builder_base import StyleBuilderBase
+            offset = StyleBuilderBase.scale_from_source(10)
+            x = self.winfo_rootx() + offset
+            y = self.winfo_rooty() + self.winfo_height()
+            self.tk.call(menu_path, 'post', x, y)
+        except Exception:
+            return None
+        # Suppress Tk's default class binding so it doesn't also post the
+        # menu at its un-offset position.
+        return 'break'