bootstack 0.1.0__py3-none-any.whl

bootstack/_runtime/shortcuts.py

@@ -0,0 +1,496 @@
+"""Cross-platform keyboard shortcut management.
+
+This module provides a service for managing keyboard shortcuts with
+automatic platform detection and modifier key translation.
+
+Examples:
+    .. code-block:: python
+
+        import bootstack as bs
+        from bootstack.shortcuts import get_shortcuts
+
+        app = bs.App()
+        shortcuts = get_shortcuts()
+
+        # Register shortcuts
+        shortcuts.register("save", "Mod+S", save_file)
+        shortcuts.register("open", "Mod+O", open_file)
+        shortcuts.register("quit", "Mod+Q", app.quit)
+
+        # Bind to app window
+        shortcuts.bind_to(app)
+
+        # Menu displays shortcut text automatically
+        menu.add_command(text="Save", shortcut="save", command=save_file)
+
+"""
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from typing import Callable, Any
+from weakref import WeakSet
+
+IS_MAC = sys.platform == 'darwin'
+IS_WIN = sys.platform == 'win32'
+
+# Modifier display symbols for Mac
+_MAC_SYMBOLS = {
+    'mod': '\u2318',      # ⌘ Command
+    'command': '\u2318',  # ⌘
+    'ctrl': '\u2303',     # ⌃ Control
+    'control': '\u2303',  # ⌃
+    'alt': '\u2325',      # ⌥ Option
+    'option': '\u2325',   # ⌥
+    'shift': '\u21E7',    # ⇧
+}
+
+# Modifier display names for Windows/Linux
+_WIN_NAMES = {
+    'mod': 'Ctrl',
+    'command': 'Ctrl',
+    'ctrl': 'Ctrl',
+    'control': 'Ctrl',
+    'alt': 'Alt',
+    'option': 'Alt',
+    'shift': 'Shift',
+}
+
+# Tkinter binding modifiers
+_BINDING_MODIFIERS = {
+    'mod': 'Command' if IS_MAC else 'Control',
+    'command': 'Command',
+    'ctrl': 'Control',
+    'control': 'Control',
+    'alt': 'Option' if IS_MAC else 'Alt',
+    'option': 'Option',
+    'shift': 'Shift',
+}
+
+
+@dataclass
+class Shortcut:
+    """A registered keyboard shortcut."""
+
+    key: str
+    """Unique identifier for lookup (e.g. `'save'`, `'file.open'`)."""
+
+    pattern: str
+    """Shortcut pattern (e.g. `'Mod+S'`, `'Shift+Alt+N'`)."""
+
+    command: Callable
+    """Function to execute when triggered."""
+
+    @property
+    def display(self) -> str:
+        """Platform-appropriate display string for menus.
+
+        Returns:
+            On Mac: "⇧⌘S" (symbols, no separators)
+            On Windows/Linux: "Ctrl+Shift+S" (names with + separators)
+        """
+        parts = self.pattern.split('+')
+        key_part = parts[-1]
+        mod_parts = [p.lower() for p in parts[:-1]]
+
+        if IS_MAC:
+            # Mac style: symbols without separators, specific order
+            # Standard order: Control, Option, Shift, Command
+            ordered_mods = []
+            for mod in ['ctrl', 'control', 'alt', 'option', 'shift', 'mod', 'command']:
+                if mod in mod_parts:
+                    symbol = _MAC_SYMBOLS.get(mod, mod)
+                    if symbol not in ordered_mods:
+                        ordered_mods.append(symbol)
+            return ''.join(ordered_mods) + key_part.upper()
+        else:
+            # Windows/Linux style: names with + separators
+            mod_names = []
+            for mod in mod_parts:
+                name = _WIN_NAMES.get(mod, mod.capitalize())
+                if name not in mod_names:
+                    mod_names.append(name)
+            return '+'.join(mod_names + [key_part.upper()])
+
+    @property
+    def binding(self) -> str:
+        """Tkinter binding string.
+
+        Returns:
+            Binding string like "<Control-s>" or "<Command-Shift-s>"
+        """
+        parts = self.pattern.split('+')
+        key_part = parts[-1].lower()
+        mod_parts = [p.lower() for p in parts[:-1]]
+
+        # Convert to Tkinter modifier names
+        tk_mods = []
+        for mod in mod_parts:
+            tk_mod = _BINDING_MODIFIERS.get(mod, mod.capitalize())
+            if tk_mod not in tk_mods:
+                tk_mods.append(tk_mod)
+
+        # Handle function keys - keep uppercase
+        if key_part.upper().startswith('F') and key_part[1:].isdigit():
+            key_part = key_part.upper()
+
+        return f"<{'-'.join(tk_mods + [key_part])}>"
+
+
+class Shortcuts:
+    """Singleton service for managing keyboard shortcuts.
+
+    Provides cross-platform keyboard shortcut registration and binding.
+    The service automatically translates modifier keys for each platform:
+
+    - `Mod` becomes `Ctrl` on Windows/Linux, `Command` on Mac
+    - `Alt` becomes `Alt` on Windows/Linux, `Option` on Mac
+    - `Shift` works the same on all platforms
+
+    Examples:
+        .. code-block:: python
+
+            shortcuts = get_shortcuts()
+
+            # Register shortcuts
+            shortcuts.register("save", "Mod+S", save_file)
+            shortcuts.register("undo", "Mod+Z", undo)
+            shortcuts.register("find", "Mod+F", find)
+
+            # Bind all to window
+            shortcuts.bind_to(app)
+
+            # Get display string for menu
+            shortcuts.display("save")  # "Ctrl+S" on Windows, "⌘S" on Mac
+
+    """
+
+    _instance: 'Shortcuts | None' = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._shortcuts: dict[str, Shortcut] = {}
+            cls._instance._bound_windows: WeakSet = WeakSet()
+            cls._instance._bindings: dict[int, list[tuple[str, str]]] = {}
+        return cls._instance
+
+    def register(self, key: str, pattern: str, command: Callable) -> Shortcut:
+        """Register a keyboard shortcut.
+
+        Args:
+            key: Unique identifier (e.g., "save", "file.open")
+            pattern: Shortcut pattern using symbolic modifiers:
+                - `Mod+S` - Primary modifier + S
+                - `Mod+Shift+S` - Primary modifier + Shift + S
+                - `Alt+F4` - Alt + F4
+                - `F5` - Function key alone
+            command: Function to call when triggered
+
+        Returns:
+            The created Shortcut object.
+
+        Raises:
+            ValueError: If key is already registered.
+
+        Examples:
+            .. code-block:: python
+
+                shortcuts.register("save", "Mod+S", save_file)
+                shortcuts.register("quit", "Mod+Q", app.quit)
+                shortcuts.register("refresh", "F5", refresh)
+
+        """
+        if key in self._shortcuts:
+            raise ValueError(f"Shortcut key '{key}' is already registered")
+
+        shortcut = Shortcut(key=key, pattern=pattern, command=command)
+        self._shortcuts[key] = shortcut
+
+        # Bind to any already-bound windows
+        for window in self._bound_windows:
+            self._bind_shortcut(window, shortcut)
+
+        return shortcut
+
+    def unregister(self, key: str) -> None:
+        """Remove a registered shortcut.
+
+        Args:
+            key: The shortcut key to remove.
+
+        Raises:
+            KeyError: If key is not registered.
+        """
+        if key not in self._shortcuts:
+            raise KeyError(f"Shortcut key '{key}' is not registered")
+
+        shortcut = self._shortcuts.pop(key)
+
+        # Unbind from all windows
+        for window in self._bound_windows:
+            self._unbind_shortcut(window, shortcut)
+
+    def get(self, key: str) -> Shortcut | None:
+        """Get a shortcut by key.
+
+        Args:
+            key: The shortcut key to look up.
+
+        Returns:
+            The Shortcut object, or None if not found.
+        """
+        return self._shortcuts.get(key)
+
+    def display(self, key: str) -> str:
+        """Get display string for a shortcut key.
+
+        Args:
+            key: The shortcut key to look up.
+
+        Returns:
+            Platform-appropriate display string (e.g., "Ctrl+S" or "⌘S"),
+            or empty string if not found.
+        """
+        shortcut = self._shortcuts.get(key)
+        return shortcut.display if shortcut else ''
+
+    def binding(self, key: str) -> str:
+        """Get Tkinter binding string for a shortcut key.
+
+        Args:
+            key: The shortcut key to look up.
+
+        Returns:
+            Tkinter binding string (e.g., "<Control-s>"),
+            or empty string if not found.
+        """
+        shortcut = self._shortcuts.get(key)
+        return shortcut.binding if shortcut else ''
+
+    def bind_to(self, window: Any) -> None:
+        """Bind all registered shortcuts to a window.
+
+        Args:
+            window: The window (App, Toplevel, Tk) to bind shortcuts to.
+
+        Note:
+            Shortcuts registered after calling bind_to will also be
+            automatically bound to this window.
+        """
+        if window in self._bound_windows:
+            return
+
+        self._bound_windows.add(window)
+        window_id = id(window)
+        self._bindings[window_id] = []
+
+        for shortcut in self._shortcuts.values():
+            self._bind_shortcut(window, shortcut)
+
+    def unbind_from(self, window: Any) -> None:
+        """Remove all shortcut bindings from a window.
+
+        Args:
+            window: The window to unbind shortcuts from.
+        """
+        if window not in self._bound_windows:
+            return
+
+        self._bound_windows.discard(window)
+        window_id = id(window)
+
+        # Unbind all shortcuts
+        bindings = self._bindings.pop(window_id, [])
+        for binding_str, func_id in bindings:
+            try:
+                window.unbind(binding_str, func_id)
+            except Exception:
+                pass
+
+    def all(self) -> dict[str, Shortcut]:
+        """Get all registered shortcuts.
+
+        Returns:
+            Dictionary mapping keys to Shortcut objects.
+        """
+        return dict(self._shortcuts)
+
+    def _bind_shortcut(self, window: Any, shortcut: Shortcut) -> None:
+        """Bind a single shortcut to a window."""
+        window_id = id(window)
+        binding_str = shortcut.binding
+
+        def handler(event):
+            shortcut.command()
+            return 'break'
+
+        try:
+            func_id = window.bind(binding_str, handler, add='+')
+            if window_id in self._bindings:
+                self._bindings[window_id].append((binding_str, func_id))
+        except Exception:
+            pass
+
+    def _unbind_shortcut(self, window: Any, shortcut: Shortcut) -> None:
+        """Unbind a single shortcut from a window."""
+        window_id = id(window)
+        binding_str = shortcut.binding
+
+        if window_id not in self._bindings:
+            return
+
+        # Find and remove the binding
+        bindings = self._bindings[window_id]
+        for i, (b_str, func_id) in enumerate(bindings):
+            if b_str == binding_str:
+                try:
+                    window.unbind(binding_str, func_id)
+                except Exception:
+                    pass
+                bindings.pop(i)
+                break
+
+
+def get_shortcuts() -> Shortcuts:
+    """Get the global Shortcuts service instance.
+
+    Returns:
+        The singleton Shortcuts instance.
+
+    Examples:
+        .. code-block:: python
+
+            from bootstack.shortcuts import get_shortcuts
+
+            shortcuts = get_shortcuts()
+            shortcuts.register("save", "Mod+S", save_file)
+            shortcuts.bind_to(app)
+
+    """
+    return Shortcuts()
+
+
+def classify_shortcut(spec: str | None) -> str:
+    """Classify a shortcut spec into one of four kinds.
+
+    Returns one of:
+
+    - `'empty'` — `spec` is `None` or empty.
+    - `'registered'` — `spec` matches a key registered with the
+      `Shortcuts` service. The keypress is (or will be) bound there; a
+      caller should treat it as display-only.
+    - `'pattern'` — a modifier expression like `'Mod+S'` or a bare
+      function key like `'F5'`. Not registered; a caller may register and
+      bind it themselves.
+    - `'literal'` — anything else; a plain display string to show as-is.
+
+    Args:
+        spec: A registered key, modifier pattern, or literal display.
+    """
+    if not spec:
+        return 'empty'
+    if Shortcuts().get(spec) is not None:
+        return 'registered'
+    looks_like_pattern = '+' in spec or (
+        len(spec) >= 2
+        and spec[0].upper() == 'F'
+        and spec[1:].isdigit()
+    )
+    return 'pattern' if looks_like_pattern else 'literal'
+
+
+def format_shortcut(spec: str | None) -> str:
+    """Resolve a shortcut spec to its platform-appropriate display string.
+
+    Accepts three forms in order of precedence:
+
+    1. **Registered key** — the key passed to `Shortcuts.register`
+       (e.g. `"save"`, `"file.open"`). Returns the registered
+       shortcut's `display`.
+    2. **Pattern** — a modifier expression like `"Mod+S"`,
+       `"Ctrl+Shift+N"`, or `"F5"`. Treated as a transient pattern;
+       returns the pattern's platform display without registering anything.
+    3. **Plain text** — anything that doesn't parse as a pattern (no
+       modifier separator, not a function key) is returned unchanged so
+       callers can still pass a literal display string.
+
+    Args:
+        spec: A registered key, modifier pattern, or literal display.
+
+    Returns:
+        Platform-appropriate display string, or empty string when `spec`
+        is empty/None.
+
+    Examples:
+        .. code-block:: python
+
+            format_shortcut("save")       # "⌘S" on Mac, "Ctrl+S" on Win/Linux
+                                          # (assumes 'save' is registered)
+            format_shortcut("Mod+Shift+N") # "⇧⌘N" on Mac, "Ctrl+Shift+N" on Win
+            format_shortcut("F5")         # "F5" everywhere
+            format_shortcut("⌘S")         # "⌘S" — passes through unchanged
+
+    """
+    kind = classify_shortcut(spec)
+    if kind == 'empty':
+        return ''
+    if kind == 'registered':
+        return Shortcuts().get(spec).display
+    if kind == 'pattern':
+        # Transient Shortcut for display only — no registration, no binding.
+        return Shortcut(key='', pattern=spec, command=lambda: None).display
+    # 'literal' — treat as a display string.
+    return spec
+
+
+# Tk on Aqua renders these modifier WORDS as the ⌘/⌥/⌃/⇧ glyphs in menu
+# accelerators. It does NOT parse the glyphs themselves, so a native tk.Menu
+# must be given the word form — not `Shortcut.display`.
+_AQUA_ACCEL_WORDS = {
+    'mod': 'Command', 'command': 'Command', 'cmd': 'Command',
+    'ctrl': 'Control', 'control': 'Control',
+    'alt': 'Option', 'option': 'Option', 'opt': 'Option',
+    'shift': 'Shift',
+}
+
+
+def tk_aqua_accelerator(spec: str | None) -> str:
+    """Accelerator string for a native macOS `tk.Menu` entry.
+
+    Tk on Aqua converts modifier *words* (`Command`, `Option`, `Control`,
+    `Shift`) into the ⌘/⌥/⌃/⇧ glyphs when drawing a menu accelerator, but it
+    does not understand a pre-rendered glyph string. So a native menu must be
+    given the word form (e.g. `'Command+N'`) rather than `format_shortcut`'s
+    display (`'⌘N'`), which would show the modifier but drop the key.
+
+    Accepts the same three forms as `format_shortcut` — a registered key
+    (resolved to its pattern), a pattern, or a literal (returned unchanged).
+
+    Args:
+        spec: A registered key, modifier pattern, or literal display.
+
+    Returns:
+        A Tk-Aqua accelerator string, or empty string when `spec` is empty.
+    """
+    kind = classify_shortcut(spec)
+    if kind == 'empty':
+        return ''
+    if kind == 'literal':
+        return spec
+    pattern = Shortcuts().get(spec).pattern if kind == 'registered' else spec
+
+    parts = pattern.split('+')
+    key = parts[-1]
+    mods: list[str] = []
+    for part in parts[:-1]:
+        word = _AQUA_ACCEL_WORDS.get(part.lower(), part.capitalize())
+        if word not in mods:
+            mods.append(word)
+    return '+'.join(mods + [key.upper()])
+
+
+__all__ = [
+    'Shortcut', 'Shortcuts', 'get_shortcuts', 'format_shortcut',
+    'classify_shortcut', 'tk_aqua_accelerator',
+]

bootstack/_runtime/tk_patch.py

@@ -0,0 +1,43 @@
+"""Install-time patching for Tk widgets only.
+
+This module applies bootstack's Tk autostyle behavior to Tk widgets by
+wrapping their constructors. It does not affect ttk widgets, which are
+provided as explicit subclasses in the bootstack.widgets package.
+"""
+
+from __future__ import annotations
+
+import tkinter as tk
+
+from bootstack.style.style_resolver import StyleResolver
+
+# Native Tk widget classes whose constructors get the autostyle wrapper.
+# Limited to the raw Tk widgets the framework actually instantiates or
+# subclasses (everything else is built on ttk). Implementation detail of this
+# patch — intentionally not exported anywhere.
+_TK_WIDGETS = (
+    tk.Tk,        # application root window
+    tk.Toplevel,  # secondary windows, dialogs, popups
+    tk.Frame,     # Slider/RangeSlider/multiline-text container subclasses
+    tk.Text,      # TextArea / CodeEditor cores
+    tk.Canvas,    # sliders, scroll view, gauge drawing
+    tk.Menu,      # context menus and menu bars
+)
+
+
+def install_tk_autostyle() -> None:
+    """Patch Tk widgets to enable autostyle via StyleResolver.
+
+    - Wraps Tk widget `__init__` with surface color inheritance and theme
+      background application using registered Tk builders.
+    - Leaves ttk widgets untouched; ttk integration is done via wrappers.
+    """
+    # Ensure Tk builders are registered
+    import bootstack.style.builders_tk  # noqa: F401
+
+    for widget in _TK_WIDGETS:
+        _init = StyleResolver.override_tk_widget_constructor(widget.__init__)
+        widget.__init__ = _init
+
+
+__all__ = ["install_tk_autostyle"]