bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_impl/primitives/badge.py

@@ -0,0 +1,45 @@
+from typing_extensions import Unpack
+from bootstack.widgets._impl.primitives.label import Label, LabelKwargs
+from bootstack.widgets.types import Master
+
+
+class Badge(Label):
+    """bootstack wrapper for `ttk.Label` that renders with a badge style."""
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[LabelKwargs]):
+        """Create a themed bootstack Badge.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Note:
+            Badge is text-only by design. The TBadge ttk style layout omits the
+            image element, so `image=`, `icon=`, `icon_only=`, and `compound=`
+            are silently dropped at render time even though Label accepts them.
+
+        Other Parameters:
+            text: Text to display on the badge.
+            anchor: Alignment of the badge content within its area.
+            justify: How to justify multiple lines of text.
+            localize: Determines the widget's localization mode.
+            value_format: Format specification for the badge value.
+            padding: Extra space around the badge content.
+            width: Width of the badge in characters.
+            wraplength: Maximum width before wrapping text.
+            font: Font for the badge text.
+            foreground: Text color.
+            background: Background color.
+            relief: Border style.
+            state: Widget state.
+            takefocus: Whether the widget participates in focus traversal.
+            style: Explicit ttk style name (overrides accent/variant).
+            accent: Accent token for styling, e.g. 'primary', 'success', 'danger'.
+            variant: Shape of badge. 'pill' or 'square' (default).
+            surface: Optional surface token; otherwise inherited.
+            style_options: Optional dict forwarded to the style builder.
+        """
+        kwargs.setdefault('ttk_class', 'TBadge')
+        kwargs.setdefault('anchor', 'center')
+        kwargs.setdefault('font', '-size 8')
+        kwargs.setdefault('variant', 'square')
+        super().__init__(master=master, **kwargs)

bootstack/widgets/_impl/primitives/button.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any, Callable, Literal, TYPE_CHECKING
+from typing_extensions import Unpack
+
+from bootstack._core.mixins.ttk_state import TtkStateMixin
+from bootstack._core.mixins.widget import WidgetCapabilitiesMixin
+from bootstack.widgets._impl._internal.wrapper_base import TTKWrapperBase
+from bootstack.widgets._impl.mixins import IconMixin, TextSignalMixin, LocalizationMixin
+from bootstack.widgets.types import Master, StyledKwargs, Anchor, CompoundMode, WidgetState, WidgetDensity
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+
+class ButtonKwargs(StyledKwargs, total=False):
+    # Standard ttk.Button options
+    text: Any
+    command: Callable[[], Any] | None
+    image: Any
+    icon: Any
+    icon_only: bool
+    anchor: Anchor
+    compound: CompoundMode
+    padding: Any
+    width: int
+    underline: int
+    state: WidgetState
+    localize: bool | Literal['auto']
+    default: Any
+    textvariable: Any
+    textsignal: Signal[str]
+
+    # bootstack-specific extensions
+    density: WidgetDensity
+
+
+class Button(LocalizationMixin, TextSignalMixin, IconMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Button):
+    """bootstack wrapper for `ttk.Button` with themed styling and icon support.
+    """
+    _ttk_base = ttk.Button
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[ButtonKwargs]) -> None:
+        """Create a themed bootstack Button.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            text: Text to display on the button.
+            textvariable: Tk variable linked to the button text.
+                See [tkinter Variables](https://docs.python.org/3/library/tkinter.html#tkinter-variables).
+            textsignal: Reactive Signal linked to the button text (auto-synced with textvariable).
+            command: Callable invoked when the button is pressed.
+            image: Image to display on the button.
+            icon: Optional icon spec integrated via the style system.
+            icon_only: If true, removes the extra padding reserved for the text labels.
+            compound: Placement of the image relative to text (e.g., 'left').
+            padding: Extra space around the button content.
+            anchor: Determines how the content is aligned in the container. Combination of 'n', 's', 'e', 'w', or 'center' (default).
+            localize: Determines the widgets localization mode.
+            width: Width of the button in characters.
+            underline: Index of the character to underline in `text`.
+            state: Widget state — 'normal', 'active', 'disabled', or 'readonly'.
+            takefocus: Whether the widget accepts focus during traversal.
+            style: Explicit ttk style name to apply (overrides accent/variant).
+            accent: Accent token for styling, e.g. 'primary', 'danger', 'success'.
+            variant: Style variant, e.g. 'solid', 'outline', 'link', 'text'. Defaults to 'solid'.
+            density: Widget density — 'default' or 'compact'.
+            surface: Optional surface token to use for this button; if not provided, surface color is inherited from the parent.
+            style_options: Optional dict forwarded to the style builder.
+        """
+        kwargs.setdefault('variant', 'solid')
+        kwargs.update(style_options=self._capture_style_options(['icon_only', 'icon', 'anchor', 'density'], kwargs))
+        super().__init__(master, **kwargs)

bootstack/widgets/_impl/primitives/card.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Any
+
+from typing_extensions import Unpack
+
+from bootstack.widgets._impl.primitives.frame import Frame
+from bootstack.widgets.types import Master, StyledKwargs
+
+
+class CardKwargs(StyledKwargs, total=False):
+    # Standard ttk.Frame options
+    padding: Any
+    width: int
+    height: int
+
+    # bootstack-specific extensions
+    show_border: bool
+
+
+class Card(Frame):
+    """A frame with card styling"""
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[CardKwargs]) -> None:
+        """Create a themed Card container.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            padding: Extra padding inside the card. Default 16.
+            width: Requested width in pixels.
+            height: Requested height in pixels.
+            takefocus: Widget accepts focus during keyboard traversal.
+            style: Explicit ttk style name (overrides accent/variant).
+            accent: Accent/color token for the card. Default 'card'.
+            surface: Surface token for the parent background.
+            show_border: Draw a border around the card. Default True.
+            style_options: Optional dict forwarded to the style builder.
+        """
+        kwargs.setdefault('accent', 'card')
+        kwargs.setdefault('show_border', True)
+        kwargs.setdefault('padding', 16)
+        kwargs.setdefault('variant', 'card')
+        super().__init__(master, **kwargs)

bootstack/widgets/_impl/primitives/checkbutton.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any, Callable, Literal, TYPE_CHECKING
+
+from typing_extensions import Unpack
+
+from bootstack._core.mixins.ttk_state import TtkStateMixin
+from bootstack._core.mixins.widget import WidgetCapabilitiesMixin
+from bootstack.widgets._impl._internal.wrapper_base import TTKWrapperBase
+from bootstack.widgets._impl.mixins import IconMixin, LocalizationMixin, SignalMixin, TextSignalMixin
+from bootstack.widgets._impl.mixins.configure_mixin import configure_delegate
+from bootstack.widgets.types import Master, StyledKwargs, Anchor, CompoundMode, WidgetState
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+
+class CheckButtonKwargs(StyledKwargs, total=False):
+    # Standard ttk.Checkbutton options
+    text: Any
+    command: Callable[[], Any] | None
+    image: Any
+    icon: Any
+    on_icon: Any
+    off_icon: Any
+    icon_only: bool
+    show_indicator: bool
+    compound: CompoundMode
+    variable: Any
+    signal: Signal[Any]
+    value: Any
+    onvalue: Any
+    offvalue: Any
+    padding: Any
+    anchor: Anchor
+    width: int
+    underline: int
+    state: WidgetState
+    textvariable: Any
+    textsignal: Signal[str]
+
+    # bootstack-specific extensions
+    localize: bool | Literal['auto']
+
+
+class CheckButton(LocalizationMixin, SignalMixin, TextSignalMixin, IconMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Checkbutton):
+    """bootstack wrapper for `ttk.Checkbutton` with themed styling 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: Text to display.
+            textvariable: Tk variable linked to the text.
+                See [tkinter Variables](https://docs.python.org/3/library/tkinter.html#tkinter-variables).
+            textsignal: Reactive Signal linked to the text (auto-synced with textvariable).
+            command: Callable invoked when the value toggles.
+            image: Image to display.
+            icon: Icon shown in the label area for all states. Color shifts
+                from foreground (unselected) to accent (selected) automatically.
+            on_icon: Icon shown in the label area when the button is selected.
+                Shortcut for `state=[("selected", name)]` inside a full icon spec.
+            off_icon: Icon shown in the label area when the button is unselected.
+                Used as the base icon when `on_icon` is also provided.
+            icon_only: If True, removes the additional padding reserved for text.
+            show_indicator: Whether to show the standard checkbox indicator. Defaults
+                to True. Set to False to hide the indicator (e.g. when using icons alone).
+            compound: Placement of the image relative to text.
+            variable: Linked variable controlling the on/off state.
+                See [tkinter Variables](https://docs.python.org/3/library/tkinter.html#tkinter-variables).
+            localize: Determines the widget's localization mode.
+            signal: Reactive Signal controlling the on/off state (auto-synced with variable).
+            value: Initial state for the widget's associated variable (defaults to None when unset).
+            onvalue: Value set in `variable` when selected.
+            offvalue: Value set in `variable` when deselected.
+            padding: Extra space around the content.
+            anchor: Determines how the content is aligned in the container. Combination of 'n', 's', 'e', 'w', or 'center' (default).
+            width: Width of the control in characters.
+            underline: Index of character to underline in `text`.
+            state: Widget state.
+            takefocus: Whether the widget participates in focus traversal.
+            style: Explicit ttk style name (overrides accent/variant).
+            accent: Accent token for styling, e.g. 'primary', 'success', 'danger'.
+            variant: Style variant, e.g. 'default', 'round', 'square'.
+            surface: Optional surface token; otherwise inherited.
+            style_options: 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', 'on_icon', 'off_icon', 'show_indicator', '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/_impl/primitives/checktoggle.py

@@ -0,0 +1,62 @@
+from typing import Literal
+
+from typing_extensions import Unpack
+
+from bootstack.widgets._impl.primitives.checkbutton import CheckButton, CheckButtonKwargs
+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: Unpack[CheckButtonKwargs]) -> None:
+        """Create a themed bootstack CheckToggle.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            text: Text to display on the toggle.
+            textvariable: Tk variable linked to the text.
+                See [tkinter Variables](https://docs.python.org/3/library/tkinter.html#tkinter-variables).
+            textsignal: Reactive Signal linked to the text (auto-synced with textvariable).
+            command: Callable invoked when the toggle changes state.
+            image: Image to display.
+            icon: Icon shown in the label area for all states. Color shifts
+                with the button's pressed/selected state automatically.
+            on_icon: Icon shown when the toggle is selected (on). Shortcut
+                for `state=[("selected", name)]` inside a full icon spec.
+            off_icon: Icon shown when the toggle is unselected (off). Used
+                as the base icon when `on_icon` is also provided.
+            icon_only: If True, removes the additional padding reserved for text.
+            compound: Placement of the image relative to text.
+            variable: Linked variable controlling the on/off state.
+                See [tkinter Variables](https://docs.python.org/3/library/tkinter.html#tkinter-variables).
+            signal: Reactive Signal controlling the on/off state (auto-synced with variable).
+            value: Initial state for the widget's associated variable (defaults to None when unset).
+            onvalue: Value set in `variable` when selected.
+            offvalue: Value set in `variable` when deselected.
+            padding: Extra space around the content.
+            anchor: Determines how the content is aligned in the container. Combination of 'n', 's', 'e', 'w', or 'center' (default).
+            density: The vertical and horizontal compactness of widget content, e.g. 'default', 'compact'.
+            width: Width of the control in characters.
+            underline: Index of character to underline in `text`.
+            state: Widget state ('normal', 'active', 'disabled', 'readonly').
+            takefocus: Whether the widget participates in focus traversal.
+            accent: Accent token for styling, e.g. 'primary', 'success', 'danger'.
+            variant: Style variant (coerced to 'toolbutton').
+            surface: Optional surface token; otherwise inherited.
+            style_options: Optional dict forwarded to the style builder.
+            localize: 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/_impl/primitives/combobox.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any, TYPE_CHECKING
+
+from typing_extensions import Unpack
+
+from bootstack._core.mixins.ttk_state import TtkStateMixin
+from bootstack._core.mixins.widget import WidgetCapabilitiesMixin
+from bootstack.widgets._impl._internal.wrapper_base import TTKWrapperBase
+from bootstack.widgets.types import Master, StyledKwargs, Justify, WidgetState, WidgetDensity
+from ..mixins import TextSignalMixin, configure_delegate
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+
+class ComboboxKwargs(StyledKwargs, total=False):
+    # Standard ttk.Combobox options
+    values: Any
+    textvariable: Any
+    textsignal: Signal[Any]
+    state: WidgetState
+    width: int
+    height: int
+    postcommand: Any
+    justify: Justify
+    exportselection: bool
+    xscrollcommand: Any
+    font: Any
+    foreground: str
+    background: str
+
+    # bootstack-specific extensions
+    density: WidgetDensity
+
+
+class Combobox(TextSignalMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Combobox):
+    """bootstack wrapper for `ttk.Combobox` with themed styling 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: Sequence of values to display.
+            textvariable: Tk variable linked to the selected value.
+                See [tkinter Variables](https://docs.python.org/3/library/tkinter.html#tkinter-variables).
+            textsignal: Reactive Signal linked to the text (auto-synced with textvariable).
+            state: Widget state; 'readonly' restricts to list items.
+            width: Width in characters.
+            height: Maximum rows shown in the drop-down list.
+            postcommand: Callback executed before showing the drop-down.
+            justify: Text justification within the entry field.
+            exportselection: Whether selection is exported to X clipboard.
+            xscrollcommand: Scroll callback for horizontal scrolling.
+            font: Font for the entry field.
+            foreground: Text color.
+            background: Background color for the entry field.
+            style: Explicit ttk style name (overrides accent/variant).
+            accent: Accent token for styling, e.g. 'primary', 'danger', 'success'.
+            density: Vertical and horizontal compactness, e.g. 'default', 'compact'.
+            surface: Optional surface token; otherwise inherited.
+            style_options: 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. A theme change re-styles an already-open
+        # popdown through the unified theme walk (`_bs_apply_theme`).
+        self._setup_postcommand()
+
+    @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, **kwargs) -> 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.style_builder_mixed import StyleBuilderMixed
+            StyleBuilderMixed().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 _bs_apply_theme(self) -> None:
+        """Unified theme-walk hook — re-style an already-open popdown.
+
+        The ttk style engine handles the entry itself; this re-colors the
+        embedded Tk listbox/scrollbar of the popdown if one has been created.
+        """
+        self._apply_popdown_style()

bootstack/widgets/_impl/primitives/entry.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any, TYPE_CHECKING
+from typing_extensions import Unpack
+
+from bootstack._core.mixins.ttk_state import TtkStateMixin
+from bootstack._core.mixins.widget import WidgetCapabilitiesMixin
+from bootstack.widgets._impl._internal.wrapper_base import TTKWrapperBase
+from bootstack.widgets.types import Master, StyledKwargs, Justify, WidgetState, WidgetDensity
+from ..mixins import TextSignalMixin, configure_delegate
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+
+class EntryKwargs(StyledKwargs, total=False):
+    # Standard ttk.Entry options
+    textvariable: Any
+    textsignal: Signal[str]
+    show: Any
+    width: int
+    exportselection: bool
+    justify: Justify
+    validate: Any
+    validatecommand: Any
+    invalidcommand: Any
+    xscrollcommand: Any
+    font: Any
+    foreground: str
+    background: str
+    state: WidgetState
+
+    # bootstack-specific extensions
+    density: WidgetDensity
+
+
+class Entry(TextSignalMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Entry):
+    """bootstack wrapper for `ttk.Entry` with themed styling 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: Tk variable linked to the entry text.
+                See [tkinter Variables](https://docs.python.org/3/library/tkinter.html#tkinter-variables).
+            textsignal: Reactive Signal linked to the entry text (auto-synced with textvariable).
+            show: Substitute character for masked input.
+            width: Width in characters.
+            exportselection: Whether selection is exported to X clipboard.
+            justify: Text alignment inside the entry.
+            validate: Validation mode.
+            validatecommand: Validation callback.
+            invalidcommand: Callback executed on validation failure.
+            xscrollcommand: Horizontal scroll callback.
+            font: Font for the entry text.
+            foreground: Text color.
+            background: Background color.
+            state: Widget state.
+            takefocus: Whether the widget participates in focus traversal.
+            style: Explicit ttk style name (overrides accent/variant).
+            accent: Accent token for styling, e.g. 'primary', 'danger', 'success'.
+            variant: Style variant, e.g. 'default'.
+            density: Vertical and horizontal compactness, e.g. 'default', 'compact'.
+            surface: Optional surface token; otherwise inherited.
+            style_options: 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)