bootstack 0.1.0a1__py3-none-any.whl

bootstack/widgets/primitives/radiobutton.py

@@ -0,0 +1,115 @@
+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 RadioButtonKwargs(TypedDict, total=False):
+    # Standard ttk.Radiobutton 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
+    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 RadioButton(LocalizationMixin, SignalMixin, TextSignalMixin, IconMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Radiobutton):
+    """bootstack wrapper for `ttk.Radiobutton` with bootstyle and icon support."""
+
+    _ttk_base = ttk.Radiobutton
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[RadioButtonKwargs]) -> None:
+        """Create a themed bootstack Radiobutton.
+
+        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 is selected.
+            image (PhotoImage): Image to display.
+            icon (str | dict): Theme-aware icon spec handled by the style system.
+            icon_only (bool): Removes the additional padding added for label.
+            compound (str): Placement of the image relative to text.
+            variable (Variable): Linked Tk variable that receives the selected value.
+            signal (Signal): Reactive Signal that receives the selected value (auto-synced with variable).
+            value (Any): The value assigned to `variable` when this radio is selected.
+            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'.
+            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.
+            localize (bool | Literal['auto']): Determines the widget's localization mode.
+        """
+        kwargs.update(style_options=self._capture_style_options(['icon_only', 'icon', 'anchor'], kwargs))
+        super().__init__(master, **kwargs)
+
+    def get(self) -> Any:
+        """Return the current selected value."""
+        return self.variable.get()
+
+    def set(self, value: Any) -> None:
+        """Set the selected value."""
+        self.variable.set(value)
+
+    @property
+    def value(self) -> Any:
+        """Get or set the radiobutton's selected 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/radiotoggle.py

@@ -0,0 +1,50 @@
+from typing import Literal
+
+from bootstack.widgets.primitives.radiobutton import RadioButton
+from bootstack.widgets.types import Master
+
+
+class RadioToggle(RadioButton):
+    """bootstack wrapper for `ttk.Radiobutton` that renders with a toggle badge style."""
+
+    def __init__(self, master: Master = None, **kwargs):
+        """Create a themed bootstack RadioToggle.
+
+        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 is selected.
+            image (PhotoImage): Image to display.
+            icon (str | dict): Theme-aware icon spec handled by the style system.
+            icon_only (bool): Removes the additional padding added for label text.
+            compound (str): Placement of the image relative to text.
+            variable (Variable): Linked Tk variable that receives the selected value.
+            signal (Signal): Reactive Signal that receives the selected value (auto-synced with variable).
+            value (Any): The value assigned to `variable` when this radio is selected.
+            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'.
+            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('ttk_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/scale.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any, 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.mixins.configure_mixin import configure_delegate
+from bootstack.widgets.types import Master
+from ..mixins import SignalMixin
+
+if TYPE_CHECKING:
+    from bootstack.core.signals import Signal
+
+
+class ScaleKwargs(TypedDict, total=False):
+    # Standard ttk.Scale options
+    from_: float
+    to: float
+    value: float
+    variable: Any
+    signal: Signal[Any]
+    orient: Any
+    length: Any
+    command: Any
+    takefocus: Any
+    style: str
+    class_: str
+    cursor: str
+    name: str
+
+    # bootstack-specific extensions
+    bootstyle: str  # DEPRECATED: Use accent and variant instead
+    accent: str
+    surface: str
+    style_options: dict[str, Any]
+
+
+class Scale(SignalMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Scale):
+    """bootstack wrapper for `ttk.Scale` with bootstyle support."""
+
+    _ttk_base = ttk.Scale
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[ScaleKwargs]) -> None:
+        """Create a themed bootstack Scale.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            from_ (float): Minimum value.
+            to (float): Maximum value.
+            value (float): Initial value.
+            variable (Variable): Tk variable linked to the value.
+            signal (Signal): Reactive Signal linked to the value (auto-synced with variable).
+            orient (str): Orientation of the scale ('horizontal' or 'vertical').
+            length (int): Scale length in pixels.
+            command (Callable): Callback on value change.
+            takefocus (bool): Whether the widget participates in focus traversal.
+            accent (str): Accent token for styling, e.g. 'primary', 'success', 'danger'.
+            bootstyle (str): DEPRECATED - Use `accent` instead.
+            surface (str): Optional surface token; otherwise inherited.
+            style_options (dict): Optional dict forwarded to the style builder.
+        """
+        super().__init__(master, **kwargs)
+
+    @property
+    def value(self) -> float:
+        """Get or set the scale's current value."""
+        return self.get()
+
+    @value.setter
+    def value(self, value: float) -> 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/scrollbar.py

@@ -0,0 +1,56 @@
+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
+
+
+class ScrollbarKwargs(TypedDict, total=False):
+    # Standard ttk.Scrollbar options
+    orient: Any
+    command: Any
+    takefocus: Any
+    style: str
+    class_: str
+    cursor: str
+    name: str
+
+    # bootstack-specific extensions
+    bootstyle: str  # DEPRECATED: Use accent and variant instead
+    accent: str
+    variant: str
+    surface: str
+    style_options: dict[str, Any]
+
+
+class Scrollbar(TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Scrollbar):
+    """bootstack wrapper for `ttk.Scrollbar` with bootstyle support."""
+
+    _ttk_base = ttk.Scrollbar
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[ScrollbarKwargs]) -> None:
+        """Create a themed bootstack Scrollbar.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            orient (str): Orientation of the scrollbar ('horizontal' or 'vertical').
+            command (Callable): Scroll command callback.
+            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', 'round', 'square'.
+            bootstyle (str): DEPRECATED - Use `accent` and `variant` instead.
+                Combined style tokens (e.g., 'primary', 'danger-square').
+            surface (str): Optional surface token; otherwise inherited.
+            style_options (dict): Optional dict forwarded to the style builder.
+        """
+        super().__init__(master, **kwargs)
+
+

bootstack/widgets/primitives/separator.py

@@ -0,0 +1,56 @@
+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
+
+
+class SeparatorKwargs(TypedDict, total=False):
+    # Standard ttk.Separator options
+    orient: Any
+    style: str
+    class_: str
+    cursor: str
+    name: str
+
+    # bootstack-specific extensions
+    bootstyle: str  # DEPRECATED: Use accent and variant instead
+    accent: str
+    surface: str
+    thickness: int
+    length: int
+    style_options: dict[str, Any]
+
+
+class Separator(TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Separator):
+    """bootstack wrapper for `ttk.Separator` with bootstyle support."""
+
+    _ttk_base = ttk.Separator
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[SeparatorKwargs]) -> None:
+        """Create a themed bootstack Separator.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            orient (str): Orientation of the separator ('horizontal' or 'vertical').
+            style (str): Explicit ttk style name (overrides accent/variant).
+            accent (str): Accent token for styling, e.g. 'primary', 'secondary' otherwise derived from inherited surface.
+            bootstyle (str): DEPRECATED - Use `accent` and `variant` instead.
+                Combined style tokens.
+            surface (str): Optional surface token; otherwise inherited.
+            thickness (int): Thickness of the separator.
+            length (int): Fixed length of the separator in pixels. If None,
+                stretches to fill available space.
+            style_options (dict): Optional dict forwarded to the style builder.
+        """
+        kwargs.update(style_options=self._capture_style_options(['thickness', 'length'], kwargs))
+        super().__init__(master, **kwargs)
+
+

bootstack/widgets/primitives/sizegrip.py

@@ -0,0 +1,47 @@
+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
+
+
+class SizeGripKwargs(TypedDict, total=False):
+    # Standard ttk.Sizegrip options
+    style: str
+    class_: str
+    cursor: str
+    name: str
+
+    # bootstack-specific extensions
+    bootstyle: str  # DEPRECATED: Use accent and variant instead
+    accent: str
+    surface: str
+    style_options: dict[str, Any]
+
+
+class SizeGrip(TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Sizegrip):
+    """bootstack wrapper for `ttk.Sizegrip` with bootstyle support."""
+
+    _ttk_base = ttk.Sizegrip
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[SizeGripKwargs]) -> None:
+        """Create a themed bootstack Sizegrip.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            style (str): Explicit ttk style name (overrides accent/variant).
+            accent (str): Accent token for styling.
+            bootstyle (str): DEPRECATED - Use `accent` instead.
+            surface (str): Optional surface token; otherwise inherited.
+            style_options (dict): Optional dict forwarded to the style builder.
+        """
+        super().__init__(master, **kwargs)
+
+

bootstack/widgets/primitives/spinbox.py

@@ -0,0 +1,91 @@
+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 SpinboxKwargs(TypedDict, total=False):
+    # Standard ttk.Spinbox options
+    from_: float
+    to: float
+    increment: float
+    values: Any
+    wrap: bool
+    command: Any
+    font: Any
+    textvariable: Any
+    textsignal: Signal[Any]
+    format: str
+    width: int
+    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']
+    surface: str
+    style_options: dict[str, Any]
+
+
+class Spinbox(TextSignalMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Spinbox):
+    """bootstack wrapper for `ttk.Spinbox` with bootstyle support."""
+
+    _ttk_base = ttk.Spinbox
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[SpinboxKwargs]) -> None:
+        """Create a themed bootstack Spinbox.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            from_ (float): Minimum value.
+            to (float): Maximum value.
+            increment (float): Step size between values.
+            values (list): Sequence of values to cycle through.
+            wrap (bool): Whether to wrap between min/max.
+            command (Callable): Callback when the value changes.
+            textvariable (Variable): Tk variable linked to the entry text.
+            textsignal (Signal): Reactive Signal linked to the text (auto-synced with textvariable).
+            format (str): Display format string.
+            width (int): Widget width in characters.
+            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'.
+            density (str): The vertical and horizontal compactness, e.g. 'default', 'compact'.
+            bootstyle (str): DEPRECATED - Use `accent` instead.
+            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/switch.py

@@ -0,0 +1,41 @@
+from bootstack.widgets.primitives.checkbutton import CheckButton
+from bootstack.widgets.types import Master
+
+
+class Switch(CheckButton):
+    """bootstack wrapper for `ttk.Checkbutton` that renders with a Switch style"""
+
+    def __init__(self, master: Master = None, **kwargs):
+        """Create a themed bootstack Switch.
+
+        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).
+            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'.
+            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.
+        """
+        if 'bootstyle' not in kwargs:
+            kwargs['variant'] = 'switch'
+        super().__init__(master, **kwargs)

bootstack/widgets/primitives/treeview.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from tkinter import ttk
+from typing import Any, Literal, 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
+
+
+class TreeViewKwargs(TypedDict, total=False):
+    # Standard ttk.Treeview options
+    columns: Any
+    displaycolumns: Any
+    show: Literal['tree', 'headings', '']
+    height: int
+    padding: Any
+    selectmode: Literal['browse','extended','none'] | str
+    style: str
+    class_: str
+    cursor: str
+    name: str
+
+    # bootstack-specific extensions
+    surface: str
+    density: Literal['default', 'compact']
+    border_color: str
+    show_border: bool
+    select_background: str
+    header_background: str
+    style_options: dict[str, Any]
+
+
+class TreeView(TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Treeview):
+    """bootstack wrapper for `ttk.Treeview` with bootstyle support."""
+
+    _ttk_base = ttk.Treeview
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[TreeViewKwargs]) -> None:
+        """Create a themed bootstack Treeview.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            columns (list): Sequence of column identifiers.
+            displaycolumns (list | str): Subset and order of columns to display.
+            show (str): Which parts to display (e.g., 'tree', 'headings').
+            height (int): Number of rows to display.
+            padding (int | tuple): Extra padding around the widget.
+            selectmode (str): Selection mode ('browse', 'extended', 'none').
+            style (str): Explicit ttk style name.
+            surface (str): Optional surface token; otherwise inherited.
+            density (str): The compactness of widget content ('default' or 'compact').
+            border_color (str): The color of the border around the table.
+            show_border (bool): Whether to show a border around the table.
+            open_icon (str | dict): The icon used for open state.
+            close_icon (str | dict): The icon used for close state.
+            select_background (str): A semantic color token used to set selection background color.
+            header_background (str): A semantic color token used to set the header background color.
+            style_options (dict): Optional dict forwarded to the style builder.
+        """
+        kwargs.update(style_options=self._capture_style_options([
+            'density',
+            'border_color',
+            'show_border',
+            'open_icon',
+            'close_icon',
+            'select_background',
+            'header_background'
+        ],
+            kwargs))
+        super().__init__(master, **kwargs)
+
+

bootstack/widgets/types.py

@@ -0,0 +1,20 @@
+"""Common type aliases for bootstack widgets.
+
+This module provides centralized type definitions used across all widget modules
+to ensure consistency and reduce import boilerplate.
+"""
+
+from __future__ import annotations
+
+import tkinter
+from typing import Any, Callable, Optional, Union
+
+# Master widget type - used for the `master` parameter in all widget constructors
+Master = Optional[tkinter.Misc]
+
+# Callback types
+EventCallback = Callable[[tkinter.Event], None]
+CommandCallback = Callable[[], Any]
+
+# Common parameter types
+WidgetKwargs = dict[str, Any]