bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/radiogroup.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import tkinter
+from typing import overload, Any, Callable, Literal, TYPE_CHECKING
+
+from bootstack.widgets._impl.composites.radiogroup import RadioGroup as _InternalRadioGroup
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets._core.selection_group import SelectionGroupMixin
+from bootstack.widgets._core.options import normalize_options, option_display
+from bootstack.widgets._core.events import register_widget_events
+from bootstack.events import Subscription, ChangeEvent
+from bootstack.streams import Stream
+from bootstack.widgets.types import AccentToken, Event, Option, Orient
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+_RADIOGROUP_EVENTS: dict[str, str] = {
+    "change": "<<Change>>",
+}
+
+
+class RadioGroup(SelectionGroupMixin, PublicWidgetBase):
+    """A group of mutually exclusive radio buttons.
+
+    Exactly one option can be selected at a time. Options are supplied at
+    construction via `options=` and can be added or removed at runtime
+    using `add()` and `remove()`.
+
+    Args:
+        options: Choices for the group. Each item is a plain string (text and
+            value are the same), a `(text, value)` tuple, or a
+            `{'text': ..., 'value': ...}` dict — e.g. `["S", "M", "L"]` or
+            `[("Small", "s"), ("Medium", "m"), ("Large", "l")]`. A dict option
+            may also carry `'icon'` (a glyph rendered beside the label) and
+            `'disabled'` (when `True` the option is dimmed and cannot be
+            selected); any other keys ride along as carried data on `selection`.
+            An option with an `'icon'` and no text — e.g.
+            `{'icon': 'star', 'value': 's'}` — renders as an icon-only button.
+        signal: Reactive `Signal` holding the selected value. When
+            provided, `value=` is ignored — seed the Signal directly.
+        value: Initially selected value. Ignored when `signal=` is passed.
+        orient: Layout direction. Default `'horizontal'`.
+        title: Optional label rendered above the button group.
+        accent: Accent token applied to all buttons.
+        disabled: If `True`, all buttons are non-interactive and dimmed.
+            Defaults to `False`.
+        localize: Whether option labels (and the `title`) are translated through
+            the catalog — `True`, `False`, or `'auto'` (translate when a
+            translation is registered, otherwise show the literal). Defaults to
+            the app's `localize_mode`. Set `False` to keep proper nouns
+            untranslated; override a single option with its `localize` key.
+        parent: Explicit parent widget. If omitted, the current
+            context-stack container is used.
+        **kwargs: Layout placement options applied by the parent container —
+            `fill`, `expand`, `anchor`, `margin`, `row`, `column`, `sticky`.
+            See :doc:`/tasks/layout`.
+    """
+
+    def __init__(
+        self,
+        options: list[Option] | None = None,
+        *,
+        signal: "Signal | None" = None,
+        value: Any = None,
+        orient: Orient = "horizontal",
+        title: str | None = None,
+        accent: AccentToken | str | None = None,
+        disabled: bool = False,
+        localize: bool | Literal['auto'] | None = None,
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        self._localize = localize
+        self._parent = self._resolve_parent(parent)
+        layout_kw = self._split_layout_kwargs(kwargs)
+
+        tk_master = self._parent._child_master() if self._parent else None
+
+        internal_kwargs: dict[str, Any] = {"orient": orient}
+        if signal is not None:
+            internal_kwargs["signal"] = signal
+        if value is not None:
+            internal_kwargs["value"] = value
+        if title is not None:
+            internal_kwargs["text"] = title
+        if accent is not None:
+            internal_kwargs["accent"] = accent
+        if disabled:
+            internal_kwargs["state"] = "disabled"
+        if localize is not None:
+            internal_kwargs["localize"] = localize
+
+        self._internal = _InternalRadioGroup(tk_master, **internal_kwargs)
+
+        # Populate options passed at construction; keep the records (the data
+        # bag) so `selection` can return each option's full dict.
+        records = normalize_options(options)
+        self._set_option_records(records)
+        for record in records:
+            icon, disabled = option_display(record)
+            add_kwargs, _ = self._option_render(icon, disabled, record.text)
+            item_localize = self._resolve_localize(record)
+            if item_localize is not None:
+                add_kwargs["localize"] = item_localize
+            self._internal.add(text=record.text, value=record.value, **add_kwargs)
+
+        # Trace the signal so <<Change>> fires on the internal Frame whenever
+        # the value changes — this lets on_change() use standard Subscription binding.
+        self._prev_value = self._internal.signal()
+
+        def _on_value_change(new_value: Any) -> None:
+            try:
+                prev, self._prev_value = self._prev_value, new_value
+                self._internal.event_generate(
+                    "<<Change>>", data=ChangeEvent(value=new_value, prev_value=prev)
+                )
+            except tkinter.TclError:
+                pass
+
+        self._trace_id = self._internal.signal.subscribe(_on_value_change)
+        self._attach_to_parent(layout_kw)
+
+    # ----- Properties -----
+
+    @property
+    def value(self) -> Any:
+        """The currently selected value, or `None` if nothing is selected."""
+        return self._internal.value
+
+    @value.setter
+    def value(self, v: Any) -> None:
+        self._internal.value = v
+
+    @property
+    def text(self) -> str | None:
+        """The label of the selected option, or `None` if nothing is selected.
+
+        Read-only; the display complement of `value` (the selection's value).
+        """
+        return self._internal.text_for(self._internal.value)
+
+    @property
+    def selection(self) -> dict | None:
+        """The selected option as a full record dict — the data bag — or `None`.
+
+        `{'text': ..., 'value': ..., ...any extra keys}`, indexed by key like any
+        record. Read-only.
+        """
+        return self._record_dict_for(self._internal.value)
+
+    @property
+    def disabled(self) -> bool:
+        """Whether all buttons in the group are non-interactive."""
+        return self._internal._state == "disabled"
+
+    @disabled.setter
+    def disabled(self, v: bool) -> None:
+        self._internal.configure(state="disabled" if v else "normal")
+
+    @property
+    def title(self) -> str | None:
+        """The label rendered above the group. Assigning to it updates it live.
+
+        Set to `None` (or `''`) to remove the label entirely.
+        """
+        return self._internal.cget("text") or None
+
+    @title.setter
+    def title(self, value: str | None) -> None:
+        self._internal.configure(text=value or "")
+
+    # ----- Methods -----
+
+    def add(
+        self,
+        label: str,
+        value: Any | None = None,
+        *,
+        icon: Any = None,
+        disabled: bool = False,
+        localize: bool | Literal['auto'] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Add a radio button to the group at runtime.
+
+        Args:
+            label: Display text for the button. Pass `''` with an `icon` for an
+                icon-only button.
+            value: Value assigned when this button is selected. Defaults to `label`.
+            icon: Optional icon spec rendered beside the label (alone when
+                `label` is blank).
+            disabled: If `True`, the option is dimmed and cannot be selected.
+            localize: Translation mode for this option's label, overriding the
+                group's `localize=`. Defaults to the group setting.
+        """
+        resolved = value if value is not None else label
+        add_kwargs, extras = self._option_render(icon, disabled, label)
+        item_localize = self._resolve_localize(override=localize)
+        if item_localize is not None:
+            add_kwargs["localize"] = item_localize
+        if localize is not None:
+            extras["localize"] = localize
+        self._internal.add(text=label, value=resolved, **add_kwargs, **kwargs)
+        self._add_option_record(label, resolved, extras)
+
+    # ----- Event shorthands -----
+
+    @overload
+    def on_change(self) -> Stream: ...
+    @overload
+    def on_change(self, handler: Callable[[ChangeEvent], Any]) -> Subscription: ...
+    def on_change(self, handler: Callable[[ChangeEvent], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired whenever the selection changes.
+
+        Args:
+            handler: Called with a :class:`~bootstack.events.ChangeEvent`; the
+                selected value is also available via `group.value`. Omit to get
+                a composable :class:`~bootstack.streams.Stream` instead.
+
+        Returns:
+            A cancellable :class:`~bootstack.events.Subscription` when a
+            handler is given, otherwise a :class:`~bootstack.streams.Stream`.
+        """
+        return self.on("change", handler)
+
+
+register_widget_events(RadioGroup, _RADIOGROUP_EVENTS)

bootstack/widgets/scrollbar.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from bootstack.widgets._impl.primitives.scrollbar import Scrollbar as _InternalScrollbar
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets.types import AccentToken, Orient, ScrollbarVariant
+
+
+class Scrollbar(PublicWidgetBase):
+    """A themed scrollbar — horizontal or vertical.
+
+    Most users will never instantiate `Scrollbar` directly; scrollable
+    containers wire scrollbars automatically. Use this when you need an
+    explicit, manually managed scrollbar.
+
+    Args:
+        orient: `'vertical'` (default) or `'horizontal'`.
+        on_scroll: Callback invoked on scroll actions. Receives the scroll
+            arguments — `(fraction,)` for a move, or `(first, last)` for a drag.
+        accent: Accent token for styling.
+        variant: Scrollbar style — `'default'` (standard rounded bar) or
+            `'thin'` (slim square bar).
+        parent: Override the context-stack parent.
+        **kwargs: Layout placement options applied by the parent container —
+            `fill`, `expand`, `anchor`, `margin`, `row`, `column`, `sticky`.
+            See :doc:`/tasks/layout`.
+    """
+
+    def __init__(
+        self,
+        orient: Orient = "vertical",
+        *,
+        on_scroll: Callable | None = None,
+        accent: AccentToken | str | None = None,
+        variant: ScrollbarVariant = "default",
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        self._parent = self._resolve_parent(parent)
+        layout_kw = self._split_layout_kwargs(kwargs)
+
+        tk_master = self._parent._child_master() if self._parent else None
+
+        internal_kwargs: dict[str, Any] = {"orient": orient}
+        if on_scroll is not None:
+            internal_kwargs["command"] = on_scroll
+        if accent is not None:
+            internal_kwargs["accent"] = accent
+        if variant is not None:
+            internal_kwargs["variant"] = variant
+        # **kwargs is layout-only (split out above) — not forwarded to the internal.
+
+        self._internal = _InternalScrollbar(tk_master, **internal_kwargs)
+        self._attach_to_parent(layout_kw)
+
+    @property
+    def position(self) -> tuple[float, float]:
+        """Current scroll position as a `(first, last)` fraction pair."""
+        return self._internal.get()
+
+    @position.setter
+    def position(self, value: tuple[float, float]) -> None:
+        self._internal.set(*value)

bootstack/widgets/scrollview.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+from typing import overload, Any, Callable, Literal
+
+from bootstack.widgets._impl.composites.scrollview import ScrollView as _InternalScrollView
+from bootstack.widgets._impl.primitives.flexframe import FlexFrame
+from bootstack.widgets._core.base import adapt_handler
+from bootstack.widgets._core.container import FlexContainer
+from bootstack.events import ScrollEvent, Subscription
+from bootstack.streams import Stream
+from bootstack.widgets.types import Padding, ScrollbarVariant
+
+
+class ScrollView(FlexContainer):
+    """A canvas-based scrollable container.
+
+    Place children inside the context block; they are laid out vertically
+    inside the scrollable area. Mouse-wheel scrolling is automatically
+    enabled for all descendants.
+
+    Args:
+        scroll_direction: Which axis to scroll. Defaults to `'both'`.
+        scrollbar_visibility: When scrollbars appear — `'always'` (default),
+            `'never'`, `'hover'` (appears on mouse enter), or `'scroll'`
+            (auto-hides after `autohide_delay` ms of inactivity).
+        scrollbar_variant: Scrollbar style — `'default'` (standard rounded bar)
+            or `'thin'` (slim square bar).
+        autohide_delay: Milliseconds before scrollbars hide in `'scroll'` mode.
+            Defaults to `1000`.
+        height: Fixed height of the viewport in pixels. When set, the
+            canvas is pinned to this height regardless of content size.
+            Required for vertical scrolling unless the parent already
+            constrains the height. Defaults to `None`.
+        width: Fixed width of the viewport in pixels. Pins the canvas
+            width, similar to `height=`. Defaults to `None`.
+        show_border: Draw a 1 px border around the ScrollView frame.
+            Defaults to `False`.
+        padding: Space in pixels between the border and the canvas.
+            Defaults to `None` (no padding).
+        parent: Override the context-stack parent.
+        **kwargs: Layout placement options applied by the parent container —
+            `fill`, `expand`, `anchor`, `margin`, `row`, `column`, `sticky`.
+            See :doc:`/tasks/layout`.
+    """
+
+    def __init__(
+        self,
+        *,
+        scroll_direction: Literal["vertical", "horizontal", "both"] = "both",
+        scrollbar_visibility: Literal["always", "never", "hover", "scroll"] = "always",
+        scrollbar_variant: ScrollbarVariant = "default",
+        autohide_delay: int = 1000,
+        height: int | None = None,
+        width: int | None = None,
+        show_border: bool = False,
+        padding: Padding | None = None,
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        self._parent = self._resolve_parent(parent)
+        layout_kw = self._split_layout_kwargs(kwargs)
+        tk_master = self._parent._child_master() if self._parent else None
+
+        internal_kwargs: dict[str, Any] = {
+            "scroll_direction": scroll_direction,
+            "scrollbar_visibility": scrollbar_visibility,
+            "scrollbar_variant": scrollbar_variant,
+            "autohide_delay": autohide_delay,
+        }
+        if height is not None:
+            internal_kwargs["height"] = height
+        if width is not None:
+            internal_kwargs["width"] = width
+        if show_border:
+            internal_kwargs["show_border"] = True
+        if padding is not None:
+            internal_kwargs["padding"] = padding
+
+        self._internal = _InternalScrollView(tk_master, **internal_kwargs)
+        # The scrollable content is a vertical flex frame inside the canvas, so
+        # children flow with the Row/Column vocabulary (grow / horizontal /
+        # vertical). It stretches children across the width by default — a scroll
+        # area fills its viewport width and scrolls overflow vertically — so
+        # content does not sit narrow against the left edge.
+        self._content_frame = FlexFrame(
+            self._internal.canvas, direction="vertical", horizontal_items="stretch"
+        )
+        self._internal.add(self._content_frame)
+        self._attach_to_parent(layout_kw)
+
+    @property
+    def _flex_frame(self) -> Any:
+        return self._content_frame
+
+    # ----- Scrolling -----
+
+    def enable_scrolling(self) -> None:
+        """Enable mouse-wheel scrolling on the canvas and all children."""
+        self._internal.enable_scrolling()
+
+    def disable_scrolling(self) -> None:
+        """Disable mouse-wheel scrolling on the canvas and all children."""
+        self._internal.disable_scrolling()
+
+    def refresh_bindings(self) -> None:
+        """Refresh scroll bindings after dynamically adding many children."""
+        self._internal.refresh_bindings()
+
+    def scroll_to_top(self) -> None:
+        """Scroll to the top of the content."""
+        self._internal.yview_moveto(0.0)
+
+    def scroll_to_bottom(self) -> None:
+        """Scroll to the bottom of the content."""
+        self._internal.yview_moveto(1.0)
+
+    def scroll_to_left(self) -> None:
+        """Scroll to the left edge of the content."""
+        self._internal.xview_moveto(0.0)
+
+    def scroll_to_right(self) -> None:
+        """Scroll to the right edge of the content."""
+        self._internal.xview_moveto(1.0)
+
+    def yview_moveto(self, fraction: float) -> None:
+        """Scroll to a vertical position.
+
+        Args:
+            fraction: 0.0 (top) to 1.0 (bottom).
+        """
+        self._internal.yview_moveto(fraction)
+
+    def xview_moveto(self, fraction: float) -> None:
+        """Scroll to a horizontal position.
+
+        Args:
+            fraction: 0.0 (left) to 1.0 (right).
+        """
+        self._internal.xview_moveto(fraction)
+
+    @property
+    def scroll_position(self) -> tuple[float, float]:
+        """Current scroll position as `(y, x)` fractions.
+
+        Each value is the fraction of the content that lies above (`y`) or to the
+        left (`x`) of the viewport's top-left corner. `(0.0, 0.0)` means scrolled
+        fully to the top-left. As you scroll toward the end the value grows toward
+        `1.0` but does not reach it while content fills the viewport (it tops out
+        at roughly `1.0` minus the visible fraction) — only an axis whose content
+        is shorter than the viewport reads `0.0`. Read this inside an `on_scroll`
+        handler to get the new position:
+
+            sv.on_scroll(lambda e: print(e.y, e.x))
+        """
+        return self._internal.scroll_position
+
+    # ----- Events -----
+
+    @overload
+    def on_scroll(self) -> Stream: ...
+    @overload
+    def on_scroll(self, handler: Callable[[ScrollEvent], Any]) -> Subscription: ...
+    def on_scroll(self, handler: Callable[[ScrollEvent], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired whenever the viewport position changes.
+
+        Fires on mouse-wheel scrolls, programmatic `scroll_to_*` / `yview_moveto`
+        calls, and keyboard scrolling (arrow keys / Page Up / Page Down / Home /
+        End when the canvas has focus from a click).
+
+        Args:
+            handler: Called with a :class:`~bootstack.events.ScrollEvent` carrying
+                `y` (vertical fraction, 0.0–1.0) and `x` (horizontal fraction).
+                Omit to get a composable :class:`~bootstack.streams.Stream`.
+
+        Returns:
+            A cancellable :class:`~bootstack.events.Subscription` when a handler
+            is given, otherwise a :class:`~bootstack.streams.Stream`.
+        """
+        sequence = "<<BsScroll>>"
+        if handler is None:
+            def _source(h):
+                bid = self._internal.bind(sequence, adapt_handler(h), add="+")
+                return Subscription(self._internal, sequence, bid)
+            return Stream(self._internal, _source=_source)
+        bid = self._internal.bind(sequence, adapt_handler(handler), add="+")
+        return Subscription(self._internal, sequence, bid)