bootstack 0.1.0a1__py3-none-any.whl

bootstack/widgets/primitives/checkbutton.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any, Callable, Literal, Optional, TYPE_CHECKING, TypedDict
+
+from typing_extensions import Unpack
+
+from bootstack.core.mixins.ttk_state import TtkStateMixin
+from bootstack.core.mixins.widget import WidgetCapabilitiesMixin
+from bootstack.widgets.internal.wrapper_base import TTKWrapperBase
+from bootstack.widgets.mixins import IconMixin, LocalizationMixin, SignalMixin, TextSignalMixin
+from bootstack.widgets.mixins.configure_mixin import configure_delegate
+from bootstack.widgets.types import Master
+
+if TYPE_CHECKING:
+    from bootstack.core.signals import Signal
+
+
+class CheckButtonKwargs(TypedDict, total=False):
+    # Standard ttk.Checkbutton options
+    text: Any
+    command: Optional[Callable[[], Any]]
+    image: Any
+    icon: Any
+    icon_only: bool
+    compound: Literal['text', 'image', 'top', 'bottom', 'left', 'right', 'center', 'none'] | str
+    variable: Any
+    signal: Signal[Any]
+    value: Any
+    onvalue: Any
+    offvalue: Any
+    padding: Any
+    anchor: str
+    width: int
+    underline: int
+    state: Literal['normal', 'active', 'disabled', 'readonly'] | str
+    takefocus: Any
+    style: str
+    class_: str
+    cursor: str
+    name: str
+    textvariable: Any
+    textsignal: Signal[str]
+
+    # bootstack-specific extensions
+    bootstyle: str  # DEPRECATED: Use accent and variant instead
+    accent: str
+    variant: str
+    surface: str
+    style_options: dict[str, Any]
+    localize: bool | Literal['auto']
+
+
+class CheckButton(LocalizationMixin, SignalMixin, TextSignalMixin, IconMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Checkbutton):
+    """bootstack wrapper for `ttk.Checkbutton` with bootstyle and icon support."""
+
+    _ttk_base = ttk.Checkbutton
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[CheckButtonKwargs]) -> None:
+        """Create a themed bootstack Checkbutton.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            text (str): Text to display.
+            textvariable (Variable): Tk variable linked to the text.
+            textsignal (Signal[str]): Reactive Signal linked to the text (auto-synced with textvariable).
+            command (Callable): Callable invoked when the value toggles.
+            image (PhotoImage): Image to display.
+            icon (str | dict): Theme-aware icon spec handled by the style system.
+            icon_only (bool): If True, removes the additional padding reserved for text.
+            compound (str): Placement of the image relative to text.
+            variable (Variable): Linked variable controlling the on/off state.
+            localize (bool | Literal['auto']): Determines the widget's localization mode.
+            signal (Signal): Reactive Signal controlling the on/off state (auto-synced with variable).
+            value (Any): Initial state for the widget's associated variable (defaults to None when unset).
+            onvalue (Any): Value set in `variable` when selected.
+            offvalue (Any): Value set in `variable` when deselected.
+            padding (int | tuple): Extra space around the content.
+            anchor (str): Determines how the content is aligned in the container. Combination of 'n', 's', 'e', 'w', or 'center' (default).
+            width (int): Width of the control in characters.
+            underline (int): Index of character to underline in `text`.
+            state (str): Widget state.
+            takefocus (bool): Whether the widget participates in focus traversal.
+            style (str): Explicit ttk style name (overrides accent/variant).
+            accent (str): Accent token for styling, e.g. 'primary', 'success', 'danger'.
+            variant (str): Style variant, e.g. 'default', 'round', 'square'.
+            bootstyle (str): DEPRECATED - Use `accent` and `variant` instead.
+                Combined style tokens (e.g., 'primary', 'success').
+            surface (str): Optional surface token; otherwise inherited.
+            style_options (dict): Optional dict forwarded to the style builder.
+        """
+        signal_provided = 'signal' in kwargs
+        variable_provided = 'variable' in kwargs
+        initial_value = kwargs.pop('value', None)
+        kwargs.update(style_options=self._capture_style_options(['icon_only', 'icon', 'anchor'], kwargs))
+        super().__init__(master, **kwargs)
+        if initial_value is not None and not signal_provided and not variable_provided:
+            self.variable.set(initial_value)
+
+    def get(self) -> Any:
+        """Return the current value of the checkbutton."""
+        return self.variable.get()
+
+    def set(self, value: Any) -> None:
+        """Set the value of the checkbutton."""
+        self.variable.set(value)
+
+    @property
+    def value(self) -> Any:
+        """Get or set the checkbutton's value."""
+        return self.get()
+
+    @value.setter
+    def value(self, value: Any) -> None:
+        self.set(value)
+
+    @configure_delegate('value')
+    def _delegate_value(self, value=None):
+        """Get or set the value via configure."""
+        if value is None:
+            return self.get()
+        self.set(value)

bootstack/widgets/primitives/checktoggle.py

@@ -0,0 +1,53 @@
+from typing import Literal
+
+from bootstack.widgets.primitives.checkbutton import CheckButton
+from bootstack.widgets.types import Master
+
+
+class CheckToggle(CheckButton):
+    """bootstack wrapper for `ttk.Checkbutton` that renders with a ToolButton style"""
+
+    def __init__(self, master: Master = None, **kwargs):
+        """Create a themed bootstack CheckToggle.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            text (str): Text to display on the toggle.
+            textvariable (Variable): Tk variable linked to the text.
+            textsignal (Signal[str]): Reactive Signal linked to the text (auto-synced with textvariable).
+            command (Callable): Callable invoked when the toggle changes state.
+            image (PhotoImage): Image to display.
+            icon (str | dict): Theme-aware icon spec handled by the style system.
+            icon_only (bool): If True, removes the additional padding reserved for text.
+            compound (str): Placement of the image relative to text.
+            variable (Variable): Linked variable controlling the on/off state.
+            signal (Signal): Reactive Signal controlling the on/off state (auto-synced with variable).
+            value (Any): Initial state for the widget's associated variable (defaults to None when unset).
+            onvalue (Any): Value set in `variable` when selected.
+            offvalue (Any): Value set in `variable` when deselected.
+            padding (int | tuple): Extra space around the content.
+            anchor (str): Determines how the content is aligned in the container. Combination of 'n', 's', 'e', 'w', or 'center' (default).
+            density (str): The vertical and horizontal compactness of widget content, e.g. 'default', 'compact'.
+            width (int): Width of the control in characters.
+            underline (int): Index of character to underline in `text`.
+            state (str): Widget state ('normal', 'active', 'disabled', 'readonly').
+            takefocus (bool): Whether the widget participates in focus traversal.
+            accent (str): Accent token for styling, e.g. 'primary', 'success', 'danger'.
+            variant (str): Style variant (coerced to 'toolbutton').
+            surface (str): Optional surface token; otherwise inherited.
+            style_options (dict): Optional dict forwarded to the style builder.
+            localize (bool | Literal['auto']): Determines the widget's localization mode.
+        """
+        self._capture_density_option(kwargs)
+        kwargs.setdefault('class_', 'Toolbutton')
+        super().__init__(master, **kwargs)
+
+    @staticmethod
+    def _capture_density_option(kwargs: dict) -> None:
+        """Capture density from kwargs into style_options."""
+        density: Literal['default', 'compact'] | None = kwargs.pop('density', None)
+        if density is not None:
+            style_options = kwargs.setdefault('style_options', {})
+            style_options['density'] = density

bootstack/widgets/primitives/combobox.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any, Literal, TypedDict, 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.internal.wrapper_base import TTKWrapperBase
+from bootstack.widgets.types import Master
+from ..mixins import TextSignalMixin, configure_delegate
+
+if TYPE_CHECKING:
+    from bootstack.core.signals import Signal
+
+
+class ComboboxKwargs(TypedDict, total=False):
+    # Standard ttk.Combobox options
+    values: Any
+    textvariable: Any
+    textsignal: Signal[Any]
+    state: Literal['normal', 'readonly', 'disabled'] | str
+    width: int
+    height: int
+    postcommand: Any
+    justify: Any
+    exportselection: bool
+    xscrollcommand: Any
+    font: Any
+    foreground: str
+    background: str
+    style: str
+    class_: str
+    cursor: str
+    name: str
+
+    # bootstack-specific extensions
+    bootstyle: str  # DEPRECATED: Use accent and variant instead
+    accent: str
+    density: Literal['default', 'compact']
+    surface: str
+    style_options: dict[str, Any]
+
+
+class Combobox(TextSignalMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Combobox):
+    """bootstack wrapper for `ttk.Combobox` with bootstyle support."""
+
+    _ttk_base = ttk.Combobox
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[ComboboxKwargs]) -> None:
+        """Create a themed bootstack Combobox.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            values (list): Sequence of values to display.
+            textvariable (Variable): Tk variable linked to the selected value.
+            textsignal (Signal): Reactive Signal linked to the text (auto-synced with textvariable).
+            state (str): Widget state; 'readonly' restricts to list items.
+            width (int): Width in characters.
+            height (int): Maximum rows shown in the drop-down list.
+            postcommand (Callable): Callback executed before showing the drop-down.
+            justify (str): Text justification within the entry field.
+            exportselection (bool): Whether selection is exported to X clipboard.
+            xscrollcommand (Callable): Scroll callback for horizontal scrolling.
+            font (str | Font): Font for the entry field.
+            foreground (str): Text color.
+            background (str): Background color for the entry field.
+            style (str): Explicit ttk style name (overrides accent/variant).
+            accent (str): Accent token for styling, e.g. 'primary', 'danger', 'success'.
+            density (str): The vertical and horizontal compactness, e.g. 'default', 'compact'.
+            bootstyle (str): DEPRECATED - Use `accent` and `variant` instead.
+                Combined style tokens (e.g., 'primary').
+            surface (str): Optional surface token; otherwise inherited.
+            style_options (dict): Optional dict forwarded to the style builder.
+        """
+        # Store density for popdown positioning
+        if kwargs.get('density') == 'compact':
+            kwargs['font'] = 'caption'
+        kwargs.update(style_options=self._capture_style_options(['density'], kwargs))
+        super().__init__(master, **kwargs)
+
+        # Store original postcommand if provided
+        self._original_postcommand = kwargs.get('postcommand')
+
+        # Set up popdown styling (also bound to theme changes)
+        self._setup_postcommand()
+        self._subscribe_theme_changes()
+
+    @configure_delegate('density')
+    def _delegate_density(self, value=None):
+        if value is None:
+            return self.configure_style_options(value)
+        else:
+            if value == 'compact':
+                self.configure(font='caption')
+            else:
+                self.configure(font='body')
+            return self.configure_style_options(density=value)
+
+    def _setup_postcommand(self) -> None:
+        """Re-style the popdown each time it opens.
+
+        The popdown is created lazily on first open and reused. Re-styling on
+        every open ensures it picks up the current theme's colors, since the
+        embedded Tk listbox/scrollbar aren't rebuilt by the ttk style engine.
+        """
+
+        def on_popdown():
+            self._apply_popdown_style(create_if_missing=True)
+
+            if self._original_postcommand:
+                if callable(self._original_postcommand):
+                    self._original_postcommand()
+                else:
+                    self.tk.eval(str(self._original_postcommand))
+
+        self.configure(postcommand=on_popdown)
+
+    def _apply_popdown_style(self, create_if_missing: bool = False) -> None:
+        """Apply theme colors and density font to the embedded popdown.
+
+        Args:
+            create_if_missing: If True, force-create the popdown so we can
+                style it before it's mapped (used from the postcommand). If
+                False, no-op when the popdown doesn't exist yet (used from
+                the theme-change subscriber).
+        """
+        popdown_path = f"{self}.popdown"
+        try:
+            popdown_exists = bool(int(self.tk.eval(f"winfo exists {popdown_path}")))
+        except Exception:
+            return
+
+        if not popdown_exists:
+            if not create_if_missing:
+                return
+            try:
+                self.tk.eval(f"ttk::combobox::PopdownWindow {self}")
+            except Exception:
+                return
+
+        try:
+            from bootstack.style.bootstyle_builder_mixed import BootstyleBuilderMixed
+            BootstyleBuilderMixed().update_combobox_popdown_style(self)
+        except Exception:
+            pass
+
+        try:
+            density = self.configure_style_options('density') or 'default'
+            from bootstack.style.typography import get_font
+            font_token = 'caption' if density == 'compact' else 'body'
+            self.tk.call(f"{popdown_path}.f.l", "configure", "-font", str(get_font(font_token)))
+        except Exception:
+            pass
+
+    def _subscribe_theme_changes(self) -> None:
+        """Re-style any already-created popdown when the theme changes."""
+        from bootstack.core.publisher import Channel, Publisher
+        name = str(self)
+        Publisher.subscribe(name=name, func=self._apply_popdown_style, channel=Channel.STD)
+        self.bind('<Destroy>', lambda _e, n=name: Publisher.unsubscribe(n), '+')
+

bootstack/widgets/primitives/entry.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any, Literal, Optional, TypedDict, 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.internal.wrapper_base import TTKWrapperBase
+from bootstack.widgets.types import Master
+from ..mixins import TextSignalMixin, configure_delegate
+
+if TYPE_CHECKING:
+    from bootstack.core.signals import Signal
+
+
+class EntryKwargs(TypedDict, total=False):
+    # Standard ttk.Entry options
+    textvariable: Any
+    textsignal: Signal[str]
+    show: Any
+    width: int
+    exportselection: bool
+    justify: Any
+    validate: Any
+    validatecommand: Any
+    invalidcommand: Any
+    xscrollcommand: Any
+    font: Any
+    foreground: str
+    background: str
+    state: Literal['normal', 'disabled', 'readonly'] | str
+    takefocus: Any
+    style: str
+    class_: str
+    cursor: str
+    name: str
+
+    # bootstack-specific extensions
+    bootstyle: str  # DEPRECATED: Use accent and variant instead
+    accent: str
+    density: Literal['default', 'compact']
+    variant: str
+    surface: str
+    style_options: dict[str, Any]
+
+
+class Entry(TextSignalMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Entry):
+    """bootstack wrapper for `ttk.Entry` with bootstyle support."""
+
+    _ttk_base = ttk.Entry
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[EntryKwargs]) -> None:
+        """Create a themed bootstack Entry.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            textvariable (Variable): Tk variable linked to the entry text.
+            textsignal (Signal[str]): Reactive Signal linked to the entry text (auto-synced with textvariable).
+            show (str): Substitute character for masked input.
+            width (int): Width in characters.
+            exportselection (bool): Whether selection is exported to X clipboard.
+            justify (str): Text alignment inside the entry.
+            validate (str): Validation mode.
+            validatecommand (Callable): Validation callback.
+            invalidcommand (Callable): Callback executed on validation failure.
+            xscrollcommand (Callable): Horizontal scroll callback.
+            font (str | Font): Font for the entry text.
+            foreground (str): Text color.
+            background (str): Background color.
+            state (str): Widget state.
+            takefocus (bool): Whether the widget participates in focus traversal.
+            style (str): Explicit ttk style name (overrides accent/variant).
+            accent (str): Accent token for styling, e.g. 'primary', 'danger', 'success'.
+            variant (str): Style variant, e.g. 'default'.
+            density (str): The vertical and horizontal compactness, e.g. 'default', 'compact'.
+            bootstyle (str): DEPRECATED - Use `accent` and `variant` instead.
+                Combined style tokens (e.g., 'primary').
+            surface (str): Optional surface token; otherwise inherited.
+            style_options (dict): Optional dict forwarded to the style builder.
+        """
+        if kwargs.get('density') == 'compact':
+            kwargs['font'] = 'caption'
+        kwargs.update(style_options=self._capture_style_options(['density'], kwargs))
+        super().__init__(master, **kwargs)
+
+    @configure_delegate('density')
+    def _delegate_density(self, value=None):
+        if value is None:
+            return self.configure_style_options(value)
+        else:
+            if value == 'compact':
+                self.configure(font='caption')
+            else:
+                self.configure(font='body')
+            return self.configure_style_options(density=value)

bootstack/widgets/primitives/frame.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any, TypedDict
+
+from typing_extensions import Unpack
+
+from bootstack.core.mixins.ttk_state import TtkStateMixin
+from bootstack.core.mixins.widget import WidgetCapabilitiesMixin
+from bootstack.widgets.internal.wrapper_base import TTKWrapperBase
+from bootstack.widgets.types import Master
+from bootstack.style.style import get_style
+from bootstack.style.bootstyle_builder_tk import BootstyleBuilderBuilderTk
+from ..mixins import configure_delegate
+
+
+class FrameKwargs(TypedDict, total=False):
+    # Standard ttk.Frame options
+    padding: Any
+    width: int
+    height: int
+    style: str
+    cursor: str
+    name: str
+    takefocus: bool
+    class_: str
+
+    # bootstack-specific extensions
+    accent: str
+    variant: str
+    surface: str
+    input_background: str
+    show_border: bool
+    style_options: dict[str, Any]
+    bootstyle: str  # DEPRECATED: Use accent and variant instead
+
+
+class Frame(TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Frame):
+    """bootstack wrapper for `ttk.Frame` with bootstyle support."""
+
+    _ttk_base = ttk.Frame
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[FrameKwargs]) -> None:
+        """Create a themed bootstack Frame.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            padding (int | tuple): Extra padding inside the frame.
+            relief (str): Border style.
+            borderwidth (int): Border width.
+            width (int): Requested width in pixels.
+            height (int): Requested height in pixels.
+            takefocus (bool): Widget accepts focus during keyboard traversal.
+            style (str): Explicit ttk style name (overrides accent/variant).
+            accent (str): Accent token for styling, e.g. 'primary', 'secondary', 'success'.
+            variant (str): Style variant (if applicable).
+            bootstyle (str): DEPRECATED - Use `accent` and `variant` instead.
+                Combined style tokens (e.g., 'secondary').
+            surface (str): Optional surface token; otherwise inherited.
+            input_background (str): Surface token used as the fill color for all input
+                widgets (Entry, Combobox, Spinbox, Field) inside this container. Cascades
+                to descendants the same way `surface` does. Input foreground, border,
+                and focus-ring colors are all derived from this fill so contrast is always
+                correct. Defaults to `'content'` (the app background), which keeps
+                inputs visually distinct regardless of the container surface. Override
+                with any surface token (e.g. `'card'`) to match the container.
+            show_border (bool): Draw a border around the frame.
+            style_options (dict): Optional dict forwarded to the style builder.
+        """
+        kwargs.update(style_options=self._capture_style_options(['show_border'], kwargs))
+        super().__init__(master, **kwargs)
+
+    def configure_style_options(self, value=None, **kwargs):
+        """Set style options and refresh descendant surfaces if needed."""
+        old_surface = getattr(self, "_surface", "background")
+        old_input_bg = getattr(self, "_input_background", None)
+        result = super().configure_style_options(value, **kwargs)
+        if value is None:
+            if "surface" in kwargs:
+                new_surface = getattr(self, "_surface", "background")
+                if old_surface != new_surface:
+                    self.rebuild_style()
+                    self._refresh_descendant_surfaces(old_surface, new_surface)
+            if "input_background" in kwargs:
+                new_input_bg = getattr(self, "_input_background", None)
+                if old_input_bg != new_input_bg:
+                    self._refresh_descendant_input_backgrounds(old_input_bg, new_input_bg)
+        return result
+
+    @configure_delegate("bootstyle")
+    def _delegate_bootstyle(self, value: Any = None):
+        old_surface = getattr(self, "_surface", "background")
+        result = super()._delegate_bootstyle(value)
+        new_surface = getattr(self, "_surface", "background")
+        if value is not None and old_surface != new_surface:
+            self._refresh_descendant_surfaces(old_surface, new_surface)
+        return result
+
+    def _refresh_descendant_surfaces(self, old_surface: str, new_surface: str) -> None:
+        if old_surface == new_surface:
+            return
+
+        style = get_style()
+        builder_tk = BootstyleBuilderBuilderTk(
+            theme_provider=style.theme_provider if style else None,
+            style_instance=style,
+        )
+
+        for child in self._iter_descendants():
+            try:
+                child_surface = getattr(child, "_surface", None)
+            except Exception:
+                child_surface = None
+
+            explicit_surface = None
+            try:
+                explicit_surface = getattr(child, "_style_options", {}).get("surface")
+            except Exception:
+                explicit_surface = None
+
+            if explicit_surface and explicit_surface != old_surface:
+                continue
+
+            if child_surface != old_surface:
+                continue
+
+            try:
+                setattr(child, "_surface", new_surface)
+            except Exception:
+                continue
+
+            if hasattr(child, "rebuild_style"):
+                try:
+                    child.rebuild_style()
+                except Exception:
+                    pass
+            else:
+                try:
+                    builder_tk.call_builder(child, surface=new_surface)
+                except Exception:
+                    pass
+
+    def _refresh_descendant_input_backgrounds(self, old_bg: str | None, new_bg: str | None) -> None:
+        if old_bg == new_bg:
+            return
+
+        style = get_style()
+        builder_tk = BootstyleBuilderBuilderTk(
+            theme_provider=style.theme_provider if style else None,
+            style_instance=style,
+        )
+
+        for child in self._iter_descendants():
+            try:
+                child_input_bg = getattr(child, "_input_background", None)
+            except Exception:
+                child_input_bg = None
+
+            explicit_input_bg = None
+            try:
+                explicit_input_bg = getattr(child, "_style_options", {}).get("input_background")
+            except Exception:
+                explicit_input_bg = None
+
+            if explicit_input_bg and explicit_input_bg != old_bg:
+                continue
+
+            if child_input_bg != old_bg:
+                continue
+
+            try:
+                setattr(child, "_input_background", new_bg)
+            except Exception:
+                continue
+
+            if hasattr(child, "rebuild_style"):
+                try:
+                    child.rebuild_style()
+                except Exception:
+                    pass
+            else:
+                try:
+                    builder_tk.call_builder(child, input_background=new_bg)
+                except Exception:
+                    pass
+
+    def _iter_descendants(self):
+        stack = list(self.winfo_children())
+        while stack:
+            widget = stack.pop()
+            yield widget
+            try:
+                stack.extend(widget.winfo_children())
+            except Exception:
+                pass
+
+    @configure_delegate('show_border')
+    def _delegate_show_border(self, value=None):
+        if value is not None:
+            return self.configure_style_options('show_border')
+        else:
+            self.configure_style_options(show_border=True)
+            return self.rebuild_style()
+