bootstack 0.1.0a1__py3-none-any.whl

bootstack/constants.py

@@ -0,0 +1,325 @@
+"""Constants and type aliases for bootstack.
+
+This module defines constants and type aliases used throughout bootstack,
+including tkinter/ttk configuration values and bootstack-specific enums.
+
+The module provides:
+    - Type aliases using Literal for better type checking
+    - Standard tkinter constants (anchor, fill, relief, etc.)
+    - TTkbootstrap-specific constants (bootstyle colors and types)
+    - Final-typed constants for IDE autocomplete
+
+All constants are exported in __all__ for easy wildcard import:
+    ```python
+    from bootstack.constants import *
+    ```
+
+Type Aliases:
+    Anchor: Widget anchor positions (n, s, e, w, nw, ne, sw, se, center)
+    Fill: Fill modes for pack geometry manager (none, x, y, both)
+    Side: Widget placement side (left, top, right, bottom)
+    Relief: Border relief style (raised, sunken, flat, ridge, groove, solid)
+    Orient: Widget orientation (horizontal, vertical)
+    State: Widget state (normal, disabled, active, hidden, readonly)
+    BootColor: Bootstyle color names (primary, secondary, success, etc.)
+    BootType: Bootstyle type modifiers (outline, link, toggle, etc.)
+
+Example:
+    ```python
+    import bootstack as bs
+    from bootstack.constants import *
+
+    root = bs.Window()
+
+    # Use constants for cleaner code
+    btn = bs.Button(root, text="OK", bootstyle=SUCCESS)
+    btn.pack(side=LEFT, fill=X, padx=10)
+
+    root.mainloop()
+    ```
+"""
+from __future__ import annotations
+
+from typing import Final, Literal
+
+# ---------------------------
+# Type aliases (Literal unions)
+# ---------------------------
+
+Anchor = Literal["nw", "n", "ne", "w", "center", "e", "sw", "s", "se"]
+
+# Tk uses the same value set for -fill and many APIs call this "sticky"
+Sticky = Literal["none", "x", "y", "both"]
+Fill = Sticky
+
+Side = Literal["left", "top", "right", "bottom"]
+
+Relief = Literal["raised", "sunken", "flat", "ridge", "groove", "solid"]
+
+Orient = Literal["horizontal", "vertical"]
+
+Tabs = Literal["numeric"]
+
+Wrap = Literal["char", "word"]
+
+Align = Literal["baseline"]
+
+TkBoolean = Literal[0, 1, True, False]
+
+BorderMode = Literal["inside", "outside"]
+
+State = Literal["normal", "disabled", "active", "hidden", "readonly"]
+
+MenuItemType = Literal["cascade", "checkbutton", "command", "radiobutton", "separator"]
+
+SelectMode = Literal["single", "browse", "multiple", "extended"]
+
+ActiveStyle = Literal["none", "dotbox", "underline"]
+
+PieStyle = Literal["pieslice", "chord", "arc"]
+
+LineCap = Literal["butt", "projecting", "round"]
+
+LineJoin = Literal["bevel", "miter", "round"]
+
+IndexPos = Literal["first", "last"]
+
+ViewArg = Literal["moveto", "scroll", "units", "pages"]
+
+TtkTheme = Literal["clam", "alt", "default"]
+
+MeterMode = Literal["full", "semi"]
+
+ProgressMode = Literal["determinate", "indeterminate"]
+
+BootColor = Literal["primary", "secondary", "success", "danger", "warning", "info", "light", "dark"]
+
+BootType = Literal["outline", "link", "toggle", "inverse", "striped", "toolbutton", "square"]
+
+TreeviewDisplay = Literal["tree", "headings", "tree headings"]
+
+# ---------------------------
+# Booleans (legacy Tk style)
+# ---------------------------
+NO = FALSE = OFF = 0  # type: Final[TkBoolean]
+YES = TRUE = ON = 1  # type: Final[TkBoolean]
+
+# ---------------------------
+# -anchor / -sticky
+# ---------------------------
+N: Final[Anchor] = "n"
+S: Final[Anchor] = "s"
+W: Final[Anchor] = "w"
+E: Final[Anchor] = "e"
+NW: Final[Anchor] = "nw"
+SW: Final[Anchor] = "sw"
+NE: Final[Anchor] = "ne"
+SE: Final[Anchor] = "se"
+NS: Final[Anchor] = "ns"
+EW: Final[Anchor] = "ew"
+NSEW: Final[Anchor] = "nsew"
+CENTER: Final[Anchor] = "center"
+
+# ---------------------------
+# -fill
+# ---------------------------
+NONE: Final[Fill] = "none"
+X: Final[Fill] = "x"
+Y: Final[Fill] = "y"
+BOTH: Final[Fill] = "both"
+
+# ---------------------------
+# -side
+# ---------------------------
+LEFT: Final[Side] = "left"
+TOP: Final[Side] = "top"
+RIGHT: Final[Side] = "right"
+BOTTOM: Final[Side] = "bottom"
+
+# ---------------------------
+# -relief
+# ---------------------------
+RAISED: Final[Relief] = "raised"
+SUNKEN: Final[Relief] = "sunken"
+FLAT: Final[Relief] = "flat"
+RIDGE: Final[Relief] = "ridge"
+GROOVE: Final[Relief] = "groove"
+SOLID: Final[Relief] = "solid"
+
+# ---------------------------
+# -orient
+# ---------------------------
+HORIZONTAL: Final[Orient] = "horizontal"
+VERTICAL: Final[Orient] = "vertical"
+
+# ---------------------------
+# -tabs
+# ---------------------------
+NUMERIC: Final[Tabs] = "numeric"
+
+# ---------------------------
+# -wrap
+# ---------------------------
+CHAR: Final[Wrap] = "char"
+WORD: Final[Wrap] = "word"
+
+# ---------------------------
+# -align
+# ---------------------------
+BASELINE: Final[Align] = "baseline"
+
+# ---------------------------
+# -bordermode
+# ---------------------------
+INSIDE: Final[BorderMode] = "inside"
+OUTSIDE: Final[BorderMode] = "outside"
+
+# ---------------------------
+# Special tags / marks / positions
+# ---------------------------
+SEL: Final[str] = "sel"
+SEL_FIRST: Final[str] = "sel.first"
+SEL_LAST: Final[str] = "sel.last"
+END: Final[str] = "end"
+INSERT: Final[str] = "insert"
+CURRENT: Final[str] = "current"
+ANCHOR: Final[str] = "anchor"
+ALL: Final[str] = "all"  # e.g., Canvas.delete(ALL)
+
+# ---------------------------
+# States
+# ---------------------------
+NORMAL: Final[State] = "normal"
+DISABLED: Final[State] = "disabled"
+ACTIVE: Final[State] = "active"
+HIDDEN: Final[State] = "hidden"  # Canvas state
+READONLY: Final[State] = "readonly"  # ttk state
+
+# ---------------------------
+# Menu item types
+# ---------------------------
+CASCADE: Final[MenuItemType] = "cascade"
+CHECKBUTTON: Final[MenuItemType] = "checkbutton"
+COMMAND: Final[MenuItemType] = "command"
+RADIOBUTTON: Final[MenuItemType] = "radiobutton"
+SEPARATOR: Final[MenuItemType] = "separator"
+
+# ---------------------------
+# Listbox modes / styles
+# ---------------------------
+SINGLE: Final[SelectMode] = "single"
+BROWSE: Final[SelectMode] = "browse"
+MULTIPLE: Final[SelectMode] = "multiple"
+EXTENDED: Final[SelectMode] = "extended"
+
+DOTBOX: Final[ActiveStyle] = "dotbox"
+UNDERLINE: Final[ActiveStyle] = "underline"
+# (NONE from Fill is also a valid ActiveStyle value)
+
+# ---------------------------
+# Canvas styles
+# ---------------------------
+PIESLICE: Final[PieStyle] = "pieslice"
+CHORD: Final[PieStyle] = "chord"
+ARC: Final[PieStyle] = "arc"
+
+FIRST: Final[IndexPos] = "first"
+LAST: Final[IndexPos] = "last"
+
+BUTT: Final[LineCap] = "butt"
+PROJECTING: Final[LineCap] = "projecting"
+ROUND: Final[LineCap] = "round"
+
+BEVEL: Final[LineJoin] = "bevel"
+MITER: Final[LineJoin] = "miter"
+# ROUND already defined above for LineCap; same literal is valid for LineJoin too
+
+# ---------------------------
+# xview / yview args
+# ---------------------------
+MOVETO: Final[ViewArg] = "moveto"
+SCROLL: Final[ViewArg] = "scroll"
+UNITS: Final[ViewArg] = "units"
+PAGES: Final[ViewArg] = "pages"
+
+# ---------------------------
+# Themes / ttk themes
+# ---------------------------
+DEFAULT: Final[str] = "default"
+DEFAULT_THEME: Final[str] = "bootstrap-light"
+# Shared minimum column width default for form layouts
+DEFAULT_MIN_COL_WIDTH: Final[int] = 275
+
+TTK_CLAM: Final[TtkTheme] = "clam"
+TTK_ALT: Final[TtkTheme] = "alt"
+TTK_DEFAULT: Final[TtkTheme] = "default"
+
+# ---------------------------
+# Meter / progressbar
+# ---------------------------
+FULL: Final[MeterMode] = "full"
+SEMI: Final[MeterMode] = "semi"
+DETERMINATE: Final[ProgressMode] = "determinate"
+INDETERMINATE: Final[ProgressMode] = "indeterminate"
+
+# ---------------------------
+# Bootstyle colors / types
+# ---------------------------
+PRIMARY: Final[BootColor] = "primary"
+SECONDARY: Final[BootColor] = "secondary"
+SUCCESS: Final[BootColor] = "success"
+DANGER: Final[BootColor] = "danger"
+WARNING: Final[BootColor] = "warning"
+INFO: Final[BootColor] = "info"
+LIGHT: Final[BootColor] = "light"
+DARK: Final[BootColor] = "dark"
+
+OUTLINE: Final[BootType] = "outline"
+LINK: Final[BootType] = "link"
+TOGGLE: Final[BootType] = "toggle"
+INVERSE: Final[BootType] = "inverse"
+STRIPED: Final[BootType] = "striped"
+TOOLBUTTON: Final[BootType] = "toolbutton"
+SQUARE: Final[BootType] = "square"
+
+# ---------------------------
+# Treeview
+# ---------------------------
+TREE: Final[TreeviewDisplay] = "tree"
+HEADINGS: Final[TreeviewDisplay] = "headings"
+TREEHEADINGS: Final[TreeviewDisplay] = "tree headings"
+
+# ---------------------------
+# Public exports
+# ---------------------------
+__all__ = [
+    # literals (type aliases)
+    "Anchor", "Sticky", "Fill", "Side", "Relief", "Orient", "Tabs", "Wrap",
+    "Align", "BorderMode", "State", "MenuItemType", "SelectMode", "ActiveStyle",
+    "PieStyle", "LineCap", "LineJoin", "IndexPos", "ViewArg", "TtkTheme",
+    "MeterMode", "ProgressMode", "BootColor", "BootType", "TreeviewDisplay",
+    # constants
+    "NO", "FALSE", "OFF", "YES", "TRUE", "ON",
+    "N", "S", "W", "E", "NW", "SW", "NE", "SE", "NS", "EW", "NSEW", "CENTER",
+    "NONE", "X", "Y", "BOTH",
+    "LEFT", "TOP", "RIGHT", "BOTTOM",
+    "RAISED", "SUNKEN", "FLAT", "RIDGE", "GROOVE", "SOLID",
+    "HORIZONTAL", "VERTICAL",
+    "NUMERIC",
+    "CHAR", "WORD",
+    "BASELINE",
+    "INSIDE", "OUTSIDE",
+    "SEL", "SEL_FIRST", "SEL_LAST", "END", "INSERT", "CURRENT", "ANCHOR", "ALL",
+    "NORMAL", "DISABLED", "ACTIVE", "HIDDEN", "READONLY",
+    "CASCADE", "CHECKBUTTON", "COMMAND", "RADIOBUTTON", "SEPARATOR",
+    "SINGLE", "BROWSE", "MULTIPLE", "EXTENDED",
+    "DOTBOX", "UNDERLINE",
+    "PIESLICE", "CHORD", "ARC", "FIRST", "LAST",
+    "BUTT", "PROJECTING", "ROUND", "BEVEL", "MITER",
+    "MOVETO", "SCROLL", "UNITS", "PAGES",
+    "DEFAULT", "DEFAULT_THEME", "DEFAULT_MIN_COL_WIDTH", "TTK_CLAM", "TTK_ALT", "TTK_DEFAULT",
+    "FULL", "SEMI", "DETERMINATE", "INDETERMINATE",
+    "PRIMARY", "SECONDARY", "SUCCESS", "DANGER", "WARNING", "INFO", "LIGHT", "DARK",
+    "OUTLINE", "LINK", "TOGGLE", "INVERSE", "STRIPED", "TOOLBUTTON", "SQUARE",
+    "TREE", "HEADINGS", "TREEHEADINGS",
+]

bootstack/core/__init__.py

@@ -0,0 +1,34 @@
+"""Core utilities and error types."""
+
+from __future__ import annotations
+
+from . import colorutils, publisher, localization, validation, signals, capabilities
+from bootstack.core.exceptions import (
+    TTKBootstrapError,
+    LayoutError,
+    ThemeError,
+    ConfigError,
+    StateError,
+    NavigationError,
+    BootstyleBuilderError,
+    BootstyleParsingError,
+    ConfigurationWarning,
+)
+
+__all__ = [
+    "colorutils",
+    "publisher",
+    "localization",
+    "validation",
+    "signals",
+    "capabilities",
+    "TTKBootstrapError",
+    "LayoutError",
+    "ThemeError",
+    "ConfigError",
+    "StateError",
+    "NavigationError",
+    "BootstyleBuilderError",
+    "BootstyleParsingError",
+    "ConfigurationWarning",
+]

bootstack/core/capabilities/__init__.py

@@ -0,0 +1,45 @@
+"""Core widget capabilities for bootstack.
+
+This package provides framework services that can be used by widget mixins
+and other parts of the library. Each capability module contains reusable
+logic that mixins delegate to, keeping the mixins themselves as thin glue.
+
+Capabilities:
+    signals: Signal/Variable binding and normalization
+    localization: Text translation and value formatting
+"""
+
+from bootstack.core.capabilities.signals import (
+    SignalBinding,
+    is_signal,
+    is_variable,
+    normalize_signal,
+    create_signal,
+    infer_default_value_for_widget,
+    query_binding,
+)
+
+from bootstack.core.capabilities.localization import (
+    resolve_text,
+    resolve_variable_text,
+    apply_spec,
+    get_current_locale,
+    create_formatted_signal,
+)
+
+__all__ = [
+    # Signals capability
+    "SignalBinding",
+    "is_signal",
+    "is_variable",
+    "normalize_signal",
+    "create_signal",
+    "infer_default_value_for_widget",
+    "query_binding",
+    # Localization capability
+    "resolve_text",
+    "resolve_variable_text",
+    "apply_spec",
+    "get_current_locale",
+    "create_formatted_signal",
+]

bootstack/core/capabilities/after.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+
+class AfterMixin:
+    """Scheduling helpers (after).
+
+    Tk’s `after` family lets you schedule callbacks to run later on the Tk event loop.
+
+    Common uses:
+        - Debounce user input (schedule a callback and cancel previous ones).
+        - Run periodic UI updates (schedule, then reschedule from inside the callback).
+        - Defer work until the UI is idle (`after_idle`) so layout/paint can complete.
+
+    Notes:
+        - Callbacks run on the Tk thread/event loop. If you have long-running work,
+          run it off-thread/process and schedule UI updates back onto Tk using `after`.
+        - `after` returns an identifier that can be canceled with `after_cancel`.
+    """
+
+    def after(self, ms: int, func: Callable[..., Any] | None = None, *args: Any) -> str:
+        """Schedule a callback to run after a delay.
+
+        Args:
+            ms: Delay in milliseconds.
+            func: Callback to run. If omitted/None, Tk blocks for `ms` milliseconds
+                while still processing events (use sparingly).
+            *args: Arguments to pass to `func` when it is called.
+
+        Returns:
+            An identifier that can be used with `after_cancel`.
+        """
+        return super().after(ms, func, *args)  # type: ignore[misc]
+
+    def after_idle(self, func: Callable[..., Any], *args: Any) -> str:
+        """Schedule a callback to run when the event loop is idle.
+
+        Idle callbacks run after Tk has finished processing the current batch of
+        events and pending UI work.
+
+        Args:
+            func: Callback to run.
+            *args: Arguments to pass to `func` when it is called.
+
+        Returns:
+            An identifier that can be used with `after_cancel`.
+        """
+        return super().after_idle(func, *args)  # type: ignore[misc]
+
+    def after_cancel(self, id: str) -> None:
+        """Cancel a scheduled callback.
+
+        Args:
+            id: The identifier returned by `after` or `after_idle`.
+        """
+        return super().after_cancel(id)  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Convenience helpers (optional)
+    # -------------------------------------------------------------------------
+
+    def after_repeat(self, ms: int, func: Callable[..., Any], *args: Any) -> Callable[[], None]:
+        """Call `func` repeatedly every `ms` milliseconds.
+
+        This helper schedules `func` and then automatically reschedules it after
+        each run. It returns a `cancel()` function you can call to stop repetition.
+
+        Args:
+            ms: Interval in milliseconds.
+            func: Callback to run each interval.
+            *args: Arguments to pass to `func`.
+
+        Returns:
+            A `cancel()` callable. Call it to stop the repeating schedule.
+
+        Examples:
+            >>> cancel = widget.after_repeat(250, tick)
+            >>> cancel()
+        """
+        cancelled = False
+        token: str | None = None
+
+        def _run():
+            nonlocal token
+            if cancelled:
+                return
+            func(*args)
+            token = self.after(ms, _run)
+
+        token = self.after(ms, _run)
+
+        def cancel() -> None:
+            nonlocal cancelled, token
+            cancelled = True
+            if token is not None:
+                try:
+                    self.after_cancel(token)
+                except Exception:
+                    pass
+                token = None
+
+        return cancel

bootstack/core/capabilities/bind.py

@@ -0,0 +1,154 @@
+"""Event binding capabilities mixin for bootstack widgets."""
+from __future__ import annotations
+
+from typing import Any, Callable, Optional, Union
+
+
+class BindingsMixin:
+    """Event binding and virtual event generation.
+
+    This mixin documents the *Tkinter-style* binding API (`bind`, `unbind`,
+    `bind_all`, etc.) while reflecting bootstack v2’s enhanced event system.
+
+    Differences from stock Tkinter:
+        - Virtual events generated via `event_generate("<<Name>>", data=...)` may
+          carry **arbitrary Python objects** as event payload.
+        - Event handlers receive an event object with a consistent `.data` attribute:
+            - `.data` is the Python object you passed for virtual events.
+            - `.data` is `None` for non-virtual events.
+
+    Notes:
+        - Prefer `bind` over `bind_all` unless you truly need a global binding.
+        - Return the string `"break"` from a handler to stop further processing.
+        - Virtual event data is intended for application-local messaging.
+    """
+
+    # ---------------------------------------------------------------------
+    # Binding (widget, class, and application/global)
+    # ---------------------------------------------------------------------
+
+    def bind(
+            self,
+            sequence: Optional[str] = None,
+            func: Optional[Callable[..., Any]] = None,
+            add: Optional[Union[bool, str]] = None,
+    ) -> Optional[str]:
+        """Bind an event sequence to a handler.
+
+        Args:
+            sequence: Event pattern string (e.g. "<Button-1>", "<KeyPress>", "<<MyEvent>>").
+                If None, returns a string describing all bindings on this widget.
+            func: Handler callable. The handler is called with a single argument:
+                the event object. For bootstack enhanced events, `event.data`
+                is always present (None for regular events, payload for virtual events).
+            add: If true/"+" then this binding is added in addition to existing bindings.
+                If false/None then any existing binding for this sequence is replaced.
+
+        Returns:
+            If `func` is provided, returns an internal Tk binding id that can be used
+            with `unbind(sequence, funcid)`. If `func` is None, returns a Tcl binding
+            script string (Tkinter behavior varies by version) or None.
+
+        Examples:
+            Bind a regular event:
+
+                widget.bind("<Button-1>", on_click)
+
+            Bind a virtual event that carries Python data:
+
+                widget.bind("<<Save>>", on_save)
+                widget.event_generate("<<Save>>", data={"path": "doc.txt"})
+        """
+        return super().bind(sequence, func, add)  # type: ignore[misc]
+
+    def unbind(self, sequence: str, funcid: str | None = None) -> None:
+        """Remove a binding for an event sequence.
+
+        Args:
+            sequence: The event sequence that was previously bound.
+            funcid: The binding id returned from `bind`. If omitted, removes all
+                handlers for the given sequence on this widget.
+        """
+        return super().unbind(sequence, funcid)  # type: ignore[misc]
+
+    def bind_all(
+            self,
+            sequence: Optional[str] = None,
+            func: Optional[Callable[..., Any]] = None,
+            add: Optional[Union[bool, str]] = None,
+    ) -> Optional[str]:
+        """Bind an event sequence at the application level (all widgets).
+
+        Use sparingly. This affects *every* widget in the application.
+
+        Args:
+            sequence: Event pattern string.
+            func: Handler callable.
+            add: Whether to add alongside existing bindings.
+
+        Returns:
+            A binding id when setting a binding, otherwise a binding script string
+            (version-dependent) or None.
+        """
+        return super().bind_all(sequence, func, add)  # type: ignore[misc]
+
+    def unbind_all(self, sequence: str) -> None:
+        """Remove an application-level binding for the given sequence.
+
+        Args:
+            sequence: The event sequence to unbind.
+        """
+        return super().unbind_all(sequence)  # type: ignore[misc]
+
+    def bind_class(
+            self,
+            className: str,
+            sequence: Optional[str] = None,
+            func: Optional[Callable[..., Any]] = None,
+            add: Optional[Union[bool, str]] = None,
+    ) -> Optional[str]:
+        """Bind an event sequence to a Tk widget class.
+
+        This attaches a handler to *all widgets of a given Tk class name*
+        (e.g. "TButton", "TEntry").
+
+        Args:
+            className: Tk class name.
+            sequence: Event pattern string.
+            func: Handler callable.
+            add: Whether to add alongside existing bindings.
+
+        Returns:
+            A binding id when setting a binding, otherwise a binding script string
+            (version-dependent) or None.
+        """
+        return super().bind_class(className, sequence, func, add)  # type: ignore[misc]
+
+    def unbind_class(self, className: str, sequence: str) -> None:
+        """Remove a class-level binding.
+
+        Args:
+            className: Tk class name.
+            sequence: Event sequence to unbind for that class.
+        """
+        return super().unbind_class(className, sequence)  # type: ignore[misc]
+
+    # ---------------------------------------------------------------------
+    # Event generation (including virtual-event payloads)
+    # ---------------------------------------------------------------------
+
+    def event_generate(self, sequence: str, data: Any | None = None, **kw: Any) -> None:
+        """Generate an event.
+
+        This can synthesize both physical events (like "<Button-1>") and virtual
+        events (like "<<MyEvent>>"). For virtual events, bootstack supports
+        attaching a Python payload via the `data` parameter.
+
+        Args:
+            sequence: Event sequence to generate (commonly "<<Name>>" for virtual events).
+            data: Optional Python object payload for **virtual events**. When provided,
+                handlers will receive an event object whose `.data` is this value.
+                For non-virtual events, `data` is ignored and `.data` will be None.
+            **kw: Additional Tk event fields (e.g. x=..., y=..., rootx=..., rooty=...).
+        """
+        return super().event_generate(sequence, data=data, **kw)  # type: ignore[misc]