bootstack 0.1.0a1__py3-none-any.whl

bootstack/widgets/primitives/optionmenu.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from tkinter import StringVar
+from typing import Any, Callable, Literal, Optional, TYPE_CHECKING, TypedDict
+
+from typing_extensions import Unpack
+
+from bootstack.widgets.composites.contextmenu import ContextMenu, ContextMenuItem
+from bootstack.widgets.primitives.menubutton import MenuButton
+from bootstack.widgets.mixins import configure_delegate
+from bootstack.widgets.types import Master
+
+if TYPE_CHECKING:
+    from bootstack.core.signals import Signal
+
+
+class OptionMenuKwargs(TypedDict, total=False):
+    command: Optional[Callable[[], Any]]
+    image: Any
+    icon: Any
+    icon_only: bool
+    compound: Literal['text', 'image', 'top', 'bottom', 'left', 'right', 'center', 'none'] | str
+    padding: Any
+    width: int
+    underline: int
+    state: Literal['normal', 'active', 'disabled', 'readonly'] | str
+    takefocus: Any
+    style: str
+    class_: str
+    cursor: str
+    default: Any
+    name: str
+    textvariable: Any
+    textsignal: Signal[str]
+    bootstyle: str  # DEPRECATED: Use accent and variant instead
+    accent: str
+    variant: str
+    surface: str
+    style_options: dict[str, Any]
+    show_dropdown_button: bool
+    dropdown_button_icon: str | dict
+
+
+class OptionMenu(MenuButton):
+    """A single-selection dropdown menu backed by a ContextMenu.
+
+    Renders as a `MenuButton` with a chevron icon. Clicking the button opens
+    a popup menu containing the provided options as radiobutton items. Selecting
+    an item updates the displayed text and fires a `<<Change>>` event.
+
+    !!! note "Events"
+        - `<<Change>>`: Fired when the selected value changes.
+          `event.data = {'value': Any}`
+    """
+
+    def __init__(
+            self,
+            master: Master = None,
+            value: Any = None,
+            options: list[Any] = None,
+            **kwargs: Unpack[OptionMenuKwargs],
+    ):
+        """Create an OptionMenu backed by a ContextMenu.
+
+        !!! note "Events"
+            - `<<Change>>`: Fired when the selected value changes. `event.data = {'value': Any}`
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            value: Initial selected value.
+            options (list): List of values to populate the menu.
+
+        Other Parameters:
+            command (Callable): Callback invoked when the value changes via menu selection.
+            image (PhotoImage): Tk image to display.
+            icon (str | dict): Bootstyle icon spec for the label content.
+            icon_only (bool): Whether to reserve label padding when showing only an icon.
+            compound (str): Placement of image relative to text.
+            padding (int | tuple): Extra padding around the menubutton content.
+            width (int): Width of the menubutton.
+            underline (int): Index of underlined character in text.
+            state (str): Widget state ('normal', 'active', 'disabled', 'readonly').
+            takefocus (bool): Participation in focus traversal.
+            style (str): Explicit ttk style name (overrides accent/variant).
+            textvariable (Variable): Existing Tk variable to bind; new StringVar created if omitted.
+            textsignal (Signal[str]): Signal bound to the textvariable.
+            accent (str): Accent token for styling, e.g. 'primary', 'danger', 'success'.
+            variant (str): Style variant, e.g. 'solid', 'outline'.
+            bootstyle (str): DEPRECATED - Use `accent` and `variant` instead.
+                Combined style tokens (e.g., 'primary-outline').
+            surface (str): Surface token for style.
+            style_options (dict): Dict forwarded to the style builder (e.g., icon_only, surface).
+            show_dropdown_button (bool): Toggle visibility of the dropdown chevron.
+            dropdown_button_icon (str | dict): Icon name for the chevron; defaults to 'caret-down-fill'.
+        """
+        style_options = kwargs.pop('style_options', {})
+        style_options.update(
+            self._capture_style_options(
+                options=['icon_only', 'icon', 'show_dropdown_button', 'dropdown_button_icon'],
+                source=kwargs
+            )
+        )
+
+        self._bind_id = None
+        self._menu_options = options if options is not None else []
+
+        # Store the textvariable if provided, or create a new one
+        self._textvariable = kwargs.pop('textvariable', None)
+        if self._textvariable is None:
+            self._textvariable = StringVar(value=str(value) if value is not None else "")
+
+        super().__init__(master, text=value, **kwargs)
+
+        # Configure the menubutton to use the textvariable
+        self.configure(textvariable=self._textvariable)
+
+        # Bind signal to change event
+        self._bind_id = self._bind_change_event()
+
+        # Create menu items that update the shared variable
+        self._context_menu = self._build_context_menu()
+
+        # Bind menu display to button events
+        self.bind('<Button-1>', lambda _: self.show_menu(), add="+")
+        self.bind('<Return>', lambda _: self.show_menu(), add="+")
+        self.bind('<KP_Enter>', lambda _: self.show_menu(), add="+")
+
+    def _bind_change_event(self):
+        """(Re)bind textsignal to emit <<Change>> Tk events."""
+        if self._bind_id is not None:
+            self.textsignal.unsubscribe(self._bind_id)
+        return self.textsignal.subscribe(lambda v: self.event_generate('<<Change>>', data={"value": v}))
+
+    def _build_context_menu(self):
+        # Affordance baked into the button image (focus ring + border line in
+        # source-px); aligning the menu's left edge to it matches the visible
+        # button border the same way the combobox popdown does.
+        from bootstack.style.bootstyle_builder_base import BootstyleBuilderBase
+        offset_x = BootstyleBuilderBase.scale_from_source(10)
+
+        density = self.configure_style_options('density') or 'default'
+
+        menu_items = [
+            ContextMenuItem(
+                type="radiobutton",
+                text=str(item),
+                variable=self._textvariable,
+                value=str(item)
+            )
+            for item in self._menu_options
+        ]
+        return ContextMenu(
+            self, target=self, items=menu_items,
+            anchor="nw", attach="sw",
+            offset=(offset_x, 0),
+            density=density,
+            # OptionMenu drives activation via `show_menu` (left-click,
+            # Return/KP_Enter), not ContextMenu's auto-trigger.
+            trigger=None,
+        )
+
+    def show_menu(self):
+        """Show the dropdown menu unless disabled or readonly."""
+        if not self.instate(("!disabled", "!readonly")):
+            return
+        # Match the menu's minimum width to the visible button width so the
+        # dropdown never renders narrower than its trigger.
+        from bootstack.style.bootstyle_builder_base import BootstyleBuilderBase
+        affordance = BootstyleBuilderBase.scale_from_source(10)
+        target_w = self.winfo_width() - 2 * affordance
+        if target_w > 0:
+            self._context_menu.configure(minwidth=max(150, target_w))
+        self._context_menu.show()
+
+    def get(self) -> str:
+        """Return the current value."""
+        return self._textvariable.get()
+
+    def set(self, value: Any) -> None:
+        """Set the current value (coerced to string)."""
+        self._textvariable.set(str(value))
+
+    @property
+    def value(self) -> str:
+        """Get or set the current value."""
+        return self.get()
+
+    @value.setter
+    def value(self, value: Any) -> None:
+        self.set(value)
+
+    def on_changed(self, callback: Callable) -> str:
+        """Bind to `<<Change>>`. Callback receives `event.data = {'value': Any}`."""
+        return self.bind('<<Change>>', callback, add="+")
+
+    def off_changed(self, bind_id: str | None = None) -> None:
+        """Unbind from `<<Change>>`."""
+        self.unbind('<<Change>>', bind_id)
+
+    @configure_delegate('options')
+    def _delegate_options(self, value=None):
+        """Get or set the menu options list."""
+        if value is None:
+            return self._menu_options
+        else:
+            self._menu_options = value
+            if self._context_menu:
+                self._context_menu.destroy()
+            self._context_menu = self._build_context_menu()
+        return None
+
+    @configure_delegate('value')
+    def _delegate_value(self, value):
+        """Get or set the current value."""
+        if value is None:
+            return self.value
+        else:
+            self.value = value
+        return None
+
+    @configure_delegate('textsignal')
+    def _delegate_textsignal(self, value=None):
+        """Get or set the textsignal binding."""
+        if value is None:
+            return super()._delegate_textsignal()
+        else:
+            super()._delegate_textsignal(value)
+            self._bind_change_event()
+        return None
+
+    @configure_delegate('show_dropdown_button')
+    def _delegate_show_dropdown_button(self, value=None):
+        """Get or set visibility of the dropdown chevron."""
+        if value is None:
+            return self.configure_style_options('show_dropdown_button')
+        else:
+            self.configure_style_options(show_dropdown_button=value)
+            return self.rebuild_style()
+
+    @configure_delegate('dropdown_button_icon')
+    def _delegate_dropdown_button_icon(self, value):
+        """Get or set the dropdown chevron icon name."""
+        if value is None:
+            return self.configure_style_options('dropdown_button_icon')
+        else:
+            self.configure_style_options(dropdown_button_icon=value)
+            return self.rebuild_style()
+

bootstack/widgets/primitives/packframe.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import tkinter as tk
+from typing import Literal, Optional, Any
+
+from bootstack.widgets.primitives.frame import Frame
+from bootstack.widgets.mixins.configure_mixin import configure_delegate
+from bootstack.widgets.types import Master
+
+Direction = Literal["vertical", "horizontal", "row", "column", "row-reverse", "column-reverse"]
+Fill = Literal["none", "x", "y", "both"]
+Side = Literal["top", "bottom", "left", "right"]
+Anchor = Literal["n", "ne", "e", "se", "s", "sw", "w", "nw", "center"]
+
+
+class PackFrame(Frame):
+    """A Frame with simplified pack-based layout management.
+
+    PackFrame extends the bootstack Frame with automatic pack-based
+    layout management, including support for direction, gap spacing,
+    and default fill/expand behavior.
+
+    Children packed into this frame automatically receive the frame's
+    default layout options. Simply use the standard `pack()` method
+    on child widgets — no special `add()` method is needed.
+
+    Example:
+        ```python
+        frame = PackFrame(direction="vertical", gap=10, fill_items="x")
+        Label(frame, text="First").pack()
+        Label(frame, text="Second").pack()
+        Button(frame, text="Click").pack(expand=True)  # override default
+        ```
+    """
+
+    SIDE_MAP: dict[Direction, Side] = {
+        "vertical": "top",
+        "column": "top",
+        "column-reverse": "bottom",
+        "horizontal": "left",
+        "row": "left",
+        "row-reverse": "right",
+    }
+
+    def __init__(
+        self,
+        master: Master = None,
+        *,
+        direction: Direction = "vertical",
+        gap: int = 0,
+        fill_items: Optional[Fill] = None,
+        expand_items: Optional[bool] = None,
+        anchor_items: Optional[Anchor] = None,
+        propagate: Optional[bool] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Create a PackFrame with automatic pack-based layout.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            direction: Layout direction — `'vertical'`, `'horizontal'`,
+                `'row'`, `'column'`, `'row-reverse'`, or `'column-reverse'`.
+                Defaults to `'vertical'`.
+            gap: Spacing between children in pixels. Defaults to 0.
+            fill_items: Default `fill` option for children
+                (`'none'`, `'x'`, `'y'`, or `'both'`). If None, no default fill
+                is applied.
+            expand_items: Default `expand` option for children. If None, no
+                default expand is applied.
+            anchor_items: Default `anchor` for children. If None, no default
+                anchor is applied.
+            propagate: If False, the frame will not resize to fit its contents.
+                Defaults to None (Tk default behaviour).
+            **kwargs: Additional keyword arguments forwarded to `Frame`.
+        """
+        super().__init__(master, **kwargs)
+
+        self._direction = direction
+        self._gap = gap
+        self._default_fill = fill_items
+        self._default_expand = expand_items
+        self._default_anchor = anchor_items
+
+        # Ordered list of (widget, user_options) tuples for gap tracking
+        self._managed: list[tuple[tk.Widget, dict[str, Any]]] = []
+
+        if propagate is not None:
+            self.pack_propagate(propagate)
+
+    @property
+    def _side(self) -> Side:
+        """Get the pack side based on direction."""
+        return self.SIDE_MAP.get(self._direction, "top")
+
+    @configure_delegate('direction')
+    def _delegate_direction(self, value=None) -> Direction:
+        """Get or set the layout direction."""
+        if value is None:
+            return self._direction
+        self._direction = value
+        # Repack all widgets with new direction
+        self._repack_all()
+
+    @configure_delegate('gap')
+    def _delegate_gap(self, value=None) -> int:
+        """Get or set the gap between children."""
+        if value is None:
+            return self._gap
+        self._gap = value
+        # Repack all widgets with new gap
+        self._repack_all()
+
+    def _compute_gap(self, index: int) -> dict[str, Any]:
+        """Compute padding for gap based on position and direction."""
+        if index == 0 or self._gap == 0:
+            return {}
+
+        if self._direction in ("vertical", "column"):
+            return {"pady": (self._gap, 0)}
+        elif self._direction == "column-reverse":
+            return {"pady": (0, self._gap)}
+        elif self._direction in ("horizontal", "row"):
+            return {"padx": (self._gap, 0)}
+        elif self._direction == "row-reverse":
+            return {"padx": (0, self._gap)}
+        return {}
+
+    def _build_options(self, index: int, user_options: dict[str, Any]) -> dict[str, Any]:
+        """Build final pack options by merging defaults with user options."""
+        options: dict[str, Any] = {"in_": self, "side": self._side}
+
+        # Apply gap based on position
+        options.update(self._compute_gap(index))
+
+        # Apply container-level defaults
+        if self._default_fill is not None:
+            options["fill"] = self._default_fill
+        if self._default_expand is not None:
+            options["expand"] = self._default_expand
+        if self._default_anchor is not None:
+            options["anchor"] = self._default_anchor
+
+        # User options override everything
+        options.update(user_options)
+        return options
+
+    def _repack_all(self) -> None:
+        """Unpack and repack all widgets to maintain correct order and gaps."""
+        # Unpack all
+        for widget, _ in self._managed:
+            tk.Pack.forget(widget)
+
+        # Repack in order
+        for i, (widget, user_options) in enumerate(self._managed):
+            options = self._build_options(i, user_options)
+            tk.Pack.configure(widget, **options)
+
+    def _find_widget_index(self, widget: tk.Widget) -> int:
+        """Find index of widget in managed list, return -1 if not found."""
+        for i, (w, _) in enumerate(self._managed):
+            if w is widget:
+                return i
+        return -1
+
+    def _find_insert_index(self, before: tk.Widget = None, after: tk.Widget = None) -> int:
+        """Determine insertion index based on before/after options."""
+        if before is not None:
+            idx = self._find_widget_index(before)
+            if idx >= 0:
+                return idx
+        if after is not None:
+            idx = self._find_widget_index(after)
+            if idx >= 0:
+                return idx + 1
+        return len(self._managed)
+
+    # -------------------------------------------------------------------------
+    # Hook methods called by PackMixin
+    # -------------------------------------------------------------------------
+
+    def _on_child_pack(self, widget: tk.Widget, **options: Any) -> None:
+        """Hook called when a child widget calls pack().
+
+        Applies frame defaults, handles gap spacing, and tracks the widget.
+        """
+        # Check if widget is already managed (reconfigure case)
+        existing_idx = self._find_widget_index(widget)
+
+        # Determine insertion position from before/after
+        before = options.pop("before", None)
+        after = options.pop("after", None)
+
+        if existing_idx >= 0:
+            # Widget already managed - update its options
+            self._managed[existing_idx] = (widget, options)
+            self._repack_all()
+        else:
+            # New widget - find insertion point
+            insert_idx = self._find_insert_index(before, after)
+
+            if insert_idx < len(self._managed):
+                # Inserting in the middle - need to repack all
+                self._managed.insert(insert_idx, (widget, options))
+                self._repack_all()
+            else:
+                # Appending at the end - just pack it
+                pack_options = self._build_options(len(self._managed), options)
+                tk.Pack.configure(widget, **pack_options)
+                self._managed.append((widget, options))
+
+    def _on_child_pack_forget(self, widget: tk.Widget) -> None:
+        """Hook called when a child widget calls pack_forget().
+
+        Removes widget from tracking and repacks remaining widgets if needed.
+        """
+        idx = self._find_widget_index(widget)
+        if idx < 0:
+            # Not managed by us, just forget it normally
+            tk.Pack.forget(widget)
+            return
+
+        # Remove from our tracking
+        tk.Pack.forget(widget)
+        self._managed.pop(idx)
+
+        # Only repack if we removed something that affects gaps (not the last item)
+        if idx < len(self._managed):
+            self._repack_all()

bootstack/widgets/primitives/panedwindow.py

@@ -0,0 +1,58 @@
+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 PanedWindowKwargs(TypedDict, total=False):
+    # Standard ttk.Panedwindow options
+    orient: Any
+    padding: Any
+    width: int
+    height: int
+    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 PanedWindow(TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.PanedWindow):
+    """bootstack wrapper for `ttk.Panedwindow` with bootstyle support."""
+
+    _ttk_base = ttk.Panedwindow
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[PanedWindowKwargs]) -> None:
+        """Create a themed bootstack Panedwindow.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            orient (str): Orientation of panes ('horizontal' or 'vertical').
+            padding (int | tuple): Extra internal padding.
+            width (int): Requested width in pixels.
+            height (int): Requested height in pixels.
+            style (str): Explicit ttk style name (overrides accent/variant).
+            accent (str): Accent token for styling, e.g. 'primary', 'secondary'.
+            variant (str): Style variant (if applicable).
+            bootstyle (str): DEPRECATED - Use `accent` and `variant` instead.
+                Combined style tokens.
+            surface (str): Optional surface token; otherwise inherited.
+            style_options (dict): Optional dict forwarded to the style builder.
+        """
+        super().__init__(master, **kwargs)
+
+

bootstack/widgets/primitives/progressbar.py

@@ -0,0 +1,95 @@
+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.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 ProgressbarKwargs(TypedDict, total=False):
+    # Standard ttk.Progressbar options
+    mode: Literal['determinate', 'indeterminate'] | str
+    orient: Any
+    length: Any
+    maximum: float
+    value: float
+    variable: Any
+    signal: Signal[Any]
+    phase: int
+    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 Progressbar(SignalMixin, TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, ttk.Progressbar):
+    """bootstack wrapper for `ttk.Progressbar` with bootstyle support."""
+
+    _ttk_base = ttk.Progressbar
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[ProgressbarKwargs]) -> None:
+        """Create a themed bootstack Progressbar.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            mode (str): Progress mode ('determinate' or 'indeterminate').
+            orient (str): Orientation of the bar ('horizontal' or 'vertical').
+            length (int): Requested length of the progress bar in pixels.
+            maximum (float): Maximum value.
+            value (float): Current value.
+            variable (Variable): Tk variable linked to the value.
+            signal (Signal): Reactive Signal linked to the value (auto-synced with variable).
+            phase (int): Animation phase for indeterminate mode.
+            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', 'striped', 'thin'.
+            bootstyle (str): DEPRECATED - Use `accent` and `variant` instead.
+                Combined style tokens (e.g., 'success', 'striped').
+            surface (str): Optional surface token; otherwise inherited.
+            style_options (dict): Optional dict forwarded to the style builder.
+        """
+        super().__init__(master, **kwargs)
+
+    def get(self) -> float:
+        """Return the current progress value."""
+        return self.cget('value')
+
+    def set(self, value: float) -> None:
+        """Set the progress value."""
+        self.configure(value=value)
+
+    @property
+    def value(self) -> float:
+        """Get or set the progress 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)
+
+