bootstack 0.1.0a1__py3-none-any.whl

bootstack/style/bootstyle_builder_mixed.py

@@ -0,0 +1,93 @@
+"""Builder utilities for TTK widgets with embedded Tk components.
+
+This module handles styling for TTK widgets that contain legacy Tk components
+that aren't styled by the TTK theme engine, such as:
+- ttk.Combobox (contains Tk listbox and scrollbar in popdown)
+- Other hybrid widgets as needed
+
+These widgets require manual Tcl/Tk calls to style their embedded components.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from bootstack.style.bootstyle_builder_base import BootstyleBuilderBase
+from bootstack.style.theme_provider import ThemeProvider
+
+
+class BootstyleBuilderMixed(BootstyleBuilderBase):
+    """Builder for TTK widgets containing legacy Tk components.
+
+    This class provides methods to style embedded Tk components within
+    TTK widgets that aren't handled by the standard TTK theme engine.
+    """
+
+    def __init__(
+        self,
+        theme_provider: Optional[ThemeProvider] = None,
+        style_instance: Optional[Any] = None
+    ):
+        """Initialize the mixed builder.
+
+        Args:
+            theme_provider: Optional ThemeProvider instance
+            style_instance: Optional Style instance
+        """
+        super().__init__(theme_provider, style_instance)
+
+    def update_combobox_popdown_style(self, widget: Any) -> None:
+        """Update styling for legacy Tk components in ttk.Combobox.
+
+        The ttk.Combobox contains embedded Tk components (popdown listbox
+        and scrollbar) that aren't styled by the TTK theme engine and must
+        be configured manually via Tcl/Tk calls.
+
+        This method configures:
+        - The popdown listbox window (colors, borders, selection)
+        - The scrollbar within the popdown
+
+        Args:
+            widget: ttk.Combobox widget to update
+        """
+        # Match the entry field: surface = 'content', selection = primary
+        surface = self.color('content')
+        on_surface = self.on_color(surface)
+        select = self.color('primary')
+        on_select = self.on_color(select)
+
+        # Listbox has no border of its own — the popdown frame already draws
+        # the outer border, and stacking a listbox highlight on top creates a
+        # visible double-border effect.
+        tk_settings = [
+            "-borderwidth", 0,
+            "-highlightthickness", 0,
+            "-background", surface,
+            "-foreground", on_surface,
+            "-selectbackground", select,
+            "-selectforeground", on_select,
+            "-activestyle", "none",
+            "-relief", "flat",
+        ]
+
+        try:
+            # Skip if the popdown hasn't been created yet (lazy construction).
+            # The postcommand handler will style it on first open.
+            popdown_path = f"{widget}.popdown"
+            if not int(widget.tk.eval(f"winfo exists {popdown_path}")):
+                return
+            widget.tk.call(f"{popdown_path}.f.l", "configure", *tk_settings)
+
+            # Build a themed scrollbar style and apply it to the popdown
+            # scrollbar. Bootstyle.create_ttk_style returns a hashed style
+            # name (e.g. bs[xxx].Default.Vertical.TScrollbar) that is rebuilt
+            # automatically on theme change.
+            from bootstack.style.bootstyle import Bootstyle
+            sb_style = Bootstyle.create_ttk_style(
+                'TScrollbar', variant='default',
+                style_options={'orient': 'vertical', 'show_arrows': False},
+            )
+            widget.tk.call(f"{popdown_path}.f.sb", "configure", "-style", sb_style)
+        except Exception:
+            # Silently fail if widget isn't fully initialized or mapped yet
+            pass

bootstack/style/bootstyle_builder_tk.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import threading
+from typing import Callable, Dict, Optional
+from collections.abc import Sequence
+
+from typing_extensions import Any, Protocol
+
+from bootstack.style.bootstyle_builder_base import BootstyleBuilderBase, IconSpec
+from bootstack.style.theme_provider import ThemeProvider
+
+
+class TkBuilderCallable(Protocol):
+    def __call__(self, builder: "BootstyleBuilderBuilderTk", widget: Any, **options: Any) -> None:  # noqa: ANN401
+        ...
+
+
+class BootstyleBuilderBuilderTk(BootstyleBuilderBase):
+    """Builder registry for legacy Tk widgets.
+
+    Mirrors the TTK BootstyleBuilder API, but targets Tk widgets and passes
+    the actual widget instance to builder functions.
+
+    Usage:
+        >>> @BootstyleBuilderBuilderTk.register_builder('Button')
+        ... def build_tk_button(builder, widget, **opts):
+        ...     bg = builder.color(opts.get('surface', 'content'))
+        ...     widget.configure(background=bg, foreground=builder.colors.get('foreground'))
+    """
+
+    _registry: Dict[str, TkBuilderCallable] = {}
+    _lock = threading.Lock()
+    _builders_loaded = False
+
+    def __init__(self, theme_provider: Optional[ThemeProvider] = None, style_instance: Optional[Any] = None):
+        super().__init__(theme_provider, style_instance)
+
+    # Color utilities and provider/colors properties are inherited from BootstyleBase
+
+    # ----- Registry API -----
+    @classmethod
+    def register_builder(cls, widget_name: str):
+        """Register a Tk widget builder by Tk class name (e.g., 'Button')."""
+
+        if not isinstance(widget_name, str) or not widget_name:
+            raise ValueError("`widget_name` must be a non-empty string")
+
+        def deco(func: TkBuilderCallable) -> TkBuilderCallable:
+            with cls._lock:
+                cls._registry[widget_name] = func
+            return func
+
+        return deco
+
+    @classmethod
+    def has_builder(cls, widget_name: str) -> bool:
+        cls._ensure_builders_loaded()
+        with cls._lock:
+            return widget_name in cls._registry
+
+    @classmethod
+    def get_registered_widgets(cls) -> list[str]:
+        cls._ensure_builders_loaded()
+        with cls._lock:
+            return list(cls._registry.keys())
+
+    @classmethod
+    def _ensure_builders_loaded(cls) -> None:
+        # Fast path
+        if cls._builders_loaded:
+            return
+        try:
+            import bootstack.style.builders_tk  # noqa: F401
+        except Exception:
+            # If not present, that's fine; avoid repeated import attempts
+            pass
+        finally:
+            cls._builders_loaded = True
+
+    def call_builder(self, widget: Any, **options: Any) -> None:  # noqa: ANN401
+        """Call a registered builder for this Tk widget instance."""
+        # Prefer Tk's class name; fallback to Python class name
+        try:
+            widget_name = widget.winfo_class()
+        except Exception:
+            widget_name = widget.__class__.__name__
+
+        # Ensure builder modules are imported
+        self._ensure_builders_loaded()
+
+        with self._lock:
+            builder_func = self._registry.get(widget_name)
+
+        if builder_func is None:
+            # Nothing to do for this Tk widget
+            return
+
+        builder_func(self, widget, **options)
+
+    # --- Icons ---
+    def map_stateful_icons(self, icon: IconSpec, foreground_spec: Sequence[tuple]):
+        """Stateful icon mapping is not supported for Tk builders.
+
+        This API is intended for TTK style building only. Raise a clear
+        error if accidentally invoked from the Tk builder.
+        """
+        raise NotImplementedError(
+            "map_stateful_icons is only supported for TTK styles via BootstyleBuilderBuilderTTk."
+        )

bootstack/style/bootstyle_builder_ttk.py

@@ -0,0 +1,354 @@
+from __future__ import annotations
+
+import threading
+from typing import Callable, Dict, Optional
+
+from typing_extensions import Any, ParamSpec, Protocol, TypeVar
+
+from bootstack.core.exceptions import BootstyleBuilderError
+from bootstack.style.bootstyle_builder_base import BootstyleBuilderBase
+from bootstack.style.element import Element, ElementImage
+from bootstack.style.theme_provider import ThemeProvider
+
+
+class BuilderCallable(Protocol):
+    def __call__(self, builder: BootstyleBuilderTTk, ttk_style: str, **options: Any) -> None:
+        ...
+
+
+F = TypeVar("F", bound=BuilderCallable)
+P = ParamSpec("P")
+R = TypeVar("R")
+
+from bootstack.style.token_maps import WIDGET_CLASS_MAP, WIDGET_NAME_MAP
+
+# Default variant name used when no variant is specified
+# Builders should register under both their specific name AND 'default'
+# Example:
+#   @BootstyleBuilder.register_builder('solid', 'TButton')
+#   @BootstyleBuilder.register_builder('default', 'TButton')
+#   def build_button_solid(builder, ttk_style, **options):
+#       ...
+DEFAULT_VARIANT = 'default'
+
+
+class BootstyleBuilderTTk(BootstyleBuilderBase):
+    """Builder manager with widget-specific style builder registry.
+
+    This class manages registration and invocation of style builder functions.
+    Builders are registered per-widget-class and variant.
+
+    Registry structure:
+        {
+            'TButton': {
+                'solid': builder_func,
+                'outline': builder_func,
+                ...
+            },
+            'TLabel': {
+                'solid': builder_func,
+                'inverse': builder_func,
+                ...
+            }
+        }
+    """
+
+    # Widget-specific builder registry: {widget_class: {variant: builder_func}}
+    _builder_registry: Dict[str, Dict[str, Callable]] = {}
+    _builder_lock = threading.Lock()
+    _builders_loaded = False  # Track if builders have been auto-imported
+
+    def __init__(
+            self, theme_provider: Optional[ThemeProvider] = None,
+            style_instance: Optional[Any] = None):
+        """Initialize the BootstyleBuilder.
+
+        Args:
+            theme_provider: Optional ThemeProvider instance (creates one if None)
+            style_instance: Optional Style instance (set later to avoid circular import)
+        """
+        super().__init__(theme_provider, style_instance)
+
+    def set_style_instance(self, style_instance: Any):
+        """Set the Style instance (avoids circular import in __init__).
+
+        Args:
+            style_instance: Style instance to use for configuration
+        """
+        self._style = style_instance
+
+    # provider, style, colors inherited from BootstyleBase
+
+    @classmethod
+    def register_builder(cls, variant: str, widget_class: str):
+        """Register a builder for a specific widget variant.
+
+        Args:
+            variant: Variant name (e.g., 'solid', 'outline', 'link')
+            widget_class: TTK widget class (e.g., 'TButton', 'TLabel')
+
+        Returns:
+            Decorator function
+
+        Raises:
+            BootstyleBuilderError: If variant or widget_class invalid
+
+        Examples:
+            >>> @BootstyleBuilderTTk.register_builder('outline', 'TButton')
+            ... def build_button_outline(builder, ttk_style, **options):
+            ...     # Builder implementation
+            ...     pass
+        """
+        if not isinstance(variant, str) or not variant:
+            raise BootstyleBuilderError("`variant` must be a non-empty string")
+
+        if not isinstance(widget_class, str) or not widget_class:
+            raise BootstyleBuilderError("`widget_class` must be a non-empty string")
+
+        def deco(func: F) -> F:
+            with cls._builder_lock:
+                if widget_class not in cls._builder_registry:
+                    cls._builder_registry[widget_class] = {}
+
+                if variant not in cls._builder_registry[widget_class]:
+                    cls._builder_registry[widget_class][variant] = func
+                else:
+                    # Warn about overwriting?
+                    cls._builder_registry[widget_class][variant] = func
+
+            return func
+
+        return deco
+
+    def call_builder(
+            self, widget_class: str, variant: str, ttk_style: str,
+            accent: Optional[str] = None, **options):
+        """Call a registered builder for a specific widget variant.
+
+        Args:
+            widget_class: TTK widget class (e.g., 'TButton')
+            variant: Variant name (e.g., 'outline')
+            ttk_style: Full TTK style name
+            accent: Optional accent token (passed directly to builder)
+            **options: Custom style options
+
+        Raises:
+            BootstyleBuilderError: If builder not found
+        """
+        # Ensure builders are loaded before accessing registry
+        BootstyleBuilderTTk._ensure_builders_loaded()
+
+        with BootstyleBuilderTTk._builder_lock:
+            widget_registry = BootstyleBuilderTTk._builder_registry.get(widget_class)
+
+            if not widget_registry:
+                raise BootstyleBuilderError(
+                    f"No builders registered for widget class '{widget_class}'"
+                )
+
+            builder_func = widget_registry.get(variant)
+
+            if not builder_func:
+                available = ', '.join(widget_registry.keys())
+                raise BootstyleBuilderError(
+                    f"Builder '{variant}' not found for widget class '{widget_class}'. "
+                    f"Available variants: {available}"
+                )
+
+            # Pass parsed accent directly to builder
+            # No need to pass variant - the builder itself is variant-specific
+            builder_func(self, ttk_style, accent=accent, **options)
+
+    @classmethod
+    def get_widget_class(cls, widget_name: str) -> str:
+        """Convert widget common name to TTK class name.
+
+        Args:
+            widget_name: Common widget name (e.g., 'button')
+
+        Returns:
+            TTK class name (e.g., 'TButton')
+
+        Raises:
+            ValueError: If widget name not recognized
+        """
+        if widget_name not in WIDGET_CLASS_MAP:
+            raise ValueError(
+                f"Unknown widget name: '{widget_name}'. "
+                f"Known names: {', '.join(WIDGET_CLASS_MAP.keys())}"
+            )
+        return WIDGET_CLASS_MAP[widget_name]
+
+    @classmethod
+    def get_widget_name(cls, widget_class: str) -> str:
+        """Convert TTK class name to common widget name.
+
+        Args:
+            widget_class: TTK class name (e.g., 'TButton')
+
+        Returns:
+            Common widget name (e.g., 'button')
+
+        Raises:
+            ValueError: If widget class not recognized
+        """
+        if widget_class not in WIDGET_NAME_MAP:
+            raise ValueError(
+                f"Unknown widget class: '{widget_class}'. "
+                f"Known classes: {', '.join(WIDGET_NAME_MAP.keys())}"
+            )
+        return WIDGET_NAME_MAP[widget_class]
+
+    @classmethod
+    def get_default_variant(cls, widget_class: str = None) -> str:
+        """Get the default variant name.
+
+        The default variant is 'default'. Builders should register under
+        both their specific variant name and 'default' to be used as the
+        default for their widget class.
+
+        Args:
+            widget_class: TTK widget class (unused, kept for compatibility)
+
+        Returns:
+            Default variant name ('default')
+
+        Examples:
+            >>> @BootstyleBuilderTTk.register_builder('solid', 'TButton')
+            ... @BootstyleBuilderTTk.register_builder('default', 'TButton')
+            ... def build_button_solid(builder, ttk_style, **options):
+            ...     pass
+        """
+        return DEFAULT_VARIANT
+
+    @classmethod
+    def get_registered_builders(cls, widget_class: str) -> list:
+        """Get list of registered builders for a widget class.
+
+        Args:
+            widget_class: TTK widget class
+
+        Returns:
+            List of variant names
+        """
+        cls._ensure_builders_loaded()
+        registry = cls._builder_registry.get(widget_class, {})
+        return list(registry.keys())
+
+    @classmethod
+    def get_all_registered_widgets(cls) -> list:
+        """Get list of all widget classes with registered builders.
+
+        Returns:
+            List of TTK widget class names
+        """
+        cls._ensure_builders_loaded()
+        return list(cls._builder_registry.keys())
+
+    @classmethod
+    def _ensure_builders_loaded(cls):
+        """Ensure builders module is loaded (lazy import).
+
+        This is called automatically when registry is accessed to ensure
+        all builder functions are registered before use.
+        """
+        # Fast path - no lock needed if already loaded
+        if cls._builders_loaded:
+            return
+
+        # Use a simple flag to prevent multiple imports
+        # We check WITHOUT holding the lock to avoid deadlock
+        if not cls._builders_loaded:
+            try:
+                # Import builders module WITHOUT holding the lock
+                # This allows the builders to register themselves (which needs the lock)
+                import bootstack.style.builders  # noqa: F401
+                cls._builders_loaded = True
+            except ImportError:
+                # Builders module doesn't exist yet, that's ok
+                cls._builders_loaded = True  # Set to avoid retrying
+            except Exception:
+                # Unexpected error, but set flag to avoid infinite retries
+                cls._builders_loaded = True
+
+    @classmethod
+    def has_builder(cls, widget_class: str, variant: str) -> bool:
+        """Check if a builder exists for widget class and variant.
+
+        Args:
+            widget_class: TTK widget class (e.g., 'TButton')
+            variant: Variant name (e.g., 'solid', 'outline')
+
+        Returns:
+            True if builder exists, False otherwise
+
+        Examples:
+            >>> BootstyleBuilderTTk.has_builder('TButton', 'solid')
+            True
+            >>> BootstyleBuilderTTk.has_builder('TButton', 'nonexistent')
+            False
+        """
+        cls._ensure_builders_loaded()
+        return variant in cls._builder_registry.get(widget_class, {})
+
+    def initialize_all_default_styles(self):
+        """Initialize all default widget styles.
+
+        This method should be called when a theme is loaded to ensure
+        all base widget styles are properly configured before any
+        bootstyle variants are created.
+
+        It iterates through all registered widget classes and calls
+        their 'default' builder (if registered) with no accent specified,
+        which creates the base widget style.
+        """
+        BootstyleBuilderTTk._ensure_builders_loaded()
+
+        from bootstack.style.bootstyle import generate_ttk_style_name
+
+        for widget_class in BootstyleBuilderTTk.get_all_registered_widgets():
+            # Check if widget has a default builder
+            if BootstyleBuilderTTk.has_builder(widget_class, DEFAULT_VARIANT):
+                try:
+                    # Generate the proper style name (e.g., 'Default.TFrame')
+                    ttk_style = generate_ttk_style_name(
+                        accent=None,
+                        variant=DEFAULT_VARIANT,
+                        widget_class=widget_class
+                    )
+
+                    # Call the default builder with the generated style name
+                    # and no accent (None), which creates the default style
+                    self.call_builder(
+                        widget_class=widget_class,
+                        variant=DEFAULT_VARIANT,
+                        ttk_style=ttk_style,
+                        accent=None
+                    )
+                except Exception:
+                    # Silently ignore errors to avoid breaking theme initialization
+                    # Individual builder errors shouldn't prevent other builders from running
+                    pass
+
+    def map_style(self, ttk_style: str, **options):
+        self.style.map(ttk_style, **options)
+
+    def configure_style(self, ttk_style, **kwargs):
+        self.style.configure(ttk_style, **kwargs)
+
+    def create_style_element_image(self, element: ElementImage):
+        name, args, kwargs = element.build()
+        try:
+            existing = set(self.style.element_names())
+        except Exception:
+            existing = set()
+        if name in existing:
+            # Element already exists; avoid duplicate creation error on theme rebuilds
+            return
+        self.style.element_create(name, "image", *args, **kwargs)
+
+    def create_style_layout(self, ttk_style: str, element: Element | list[Element]):
+        if isinstance(element, list):
+            self.style.layout(ttk_style, [e.spec() for e in element])
+        else:
+            self.style.layout(ttk_style, [element.spec()])

bootstack/style/builders/__init__.py

@@ -0,0 +1,51 @@
+"""Style builder functions for bootstack widgets.
+
+This package contains individual builder functions organized by widget type.
+Each builder is registered with the BootstyleBuilder registry using decorators.
+
+Builder modules are automatically imported to trigger registration.
+"""
+
+from __future__ import annotations
+
+from . import (
+    badge, button, checkbutton, combobox, entry, expander, frame, label, labelframe, menubutton, sidenav,
+    notebook, panedwindow, progressbar, radiobutton, scale, scrollbar, separator, sizegrip, spinbox, switch,
+    treeview, toolbutton, tooltip, field, buttongroup, listview, calendar, contextmenu, tabitem, menubar
+)
+
+# Import all builder modules to trigger registration
+
+__all__ = [
+    'badge',
+    'button',
+    'expander',
+    'frame',
+    'label',
+    'sidenav',
+    'radiobutton',
+    'checkbutton',
+    'switch',
+    'progressbar',
+    'scale',
+    'scrollbar',
+    'menubutton',
+    'entry',
+    'field',
+    'separator',
+    'combobox',
+    'labelframe',
+    'notebook',
+    'panedwindow',
+    'sizegrip',
+    'spinbox',
+    'treeview',
+    'toolbutton',
+    'tooltip',
+    'buttongroup',
+    'listview',
+    'calendar',
+    'contextmenu',
+    'menubar',
+    'tabitem'
+]

bootstack/style/builders/badge.py

@@ -0,0 +1,44 @@
+"""Badge style builders.
+
+This module contains style builders for ttk.Label widget badge variants.
+"""
+from bootstack.style.bootstyle_builder_ttk import BootstyleBuilderTTk
+from bootstack.style.element import Element, ElementImage
+from bootstack.style.utility import recolor_element_image
+
+
+@BootstyleBuilderTTk.register_builder('square', 'TBadge')
+def build_default_badge_style(b: BootstyleBuilderTTk, ttk_style: str, accent: str = None, **options):
+    build_badge(b, ttk_style, accent, 'square', **options)
+
+@BootstyleBuilderTTk.register_builder('pill', 'TBadge')
+def build_pill_badge_style(b: BootstyleBuilderTTk, ttk_style: str, accent: str = None, **options):
+    build_badge(b, ttk_style, accent, 'pill', **options)
+
+
+def build_badge(b: BootstyleBuilderTTk, ttk_style: str, accent: str = None, variant: str = 'square', **options):
+    """Create a badge style for the variant specified"""
+
+    surface_token = options.get('surface', 'content')
+    surface = b.color(surface_token)
+    normal = b.color(accent or 'primary')
+    foreground = b.on_color(normal)
+
+    badge_img = recolor_element_image(f'badge_{variant}', normal, surface, surface, surface)
+
+    b.create_style_element_image(ElementImage(f'{ttk_style}.border', badge_img.image, 
+                                              border=badge_img.meta.border, 
+                                              padding=badge_img.meta.padding, 
+                                              height=badge_img.meta.height,
+                                              sticky='nsew'))
+
+    b.create_style_layout(
+        ttk_style, Element(f"{ttk_style}.border", sticky="nsew").children(
+            [
+                Element("Label.padding", sticky="nsew").children(
+                    [
+                        Element("Label.label", sticky="ew")
+                    ])
+            ]))
+    
+    b.configure_style(ttk_style, background=surface, foreground=foreground, padding=(6, 0))