bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/slider.py

@@ -0,0 +1,408 @@
+from __future__ import annotations
+
+from typing import overload, Any, Callable, TYPE_CHECKING
+
+from bootstack.widgets._impl.composites.slider.slider import Slider as _InternalSlider
+from bootstack.widgets._impl.composites.slider.rangeslider import RangeSlider as _InternalRangeSlider
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets._core.events import register_widget_events
+from bootstack.events import RangeSliderCommitEvent, RangeSliderEvent, SliderCommitEvent, SliderEvent, Subscription
+from bootstack.streams import Stream
+from bootstack.widgets.types import AccentToken, Event, Orient
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+_SLIDER_EVENTS: dict[str, str] = {
+    "change": "<<Change>>",
+    "commit": "<<Commit>>",
+}
+
+
+class Slider(PublicWidgetBase):
+    """A single-handle slider for selecting a numeric value within a range.
+
+    The initial value is the first positional argument. All options are
+    keyword-only.
+
+    Args:
+        value: Initial value. Defaults to `0`.
+        min_value: Minimum of the range. Defaults to `0`.
+        max_value: Maximum of the range. Defaults to `100`.
+        signal: Reactive `Signal[float]` linked to the slider value. The
+            slider and signal stay in sync automatically.
+        orient: Track orientation. Default `'horizontal'`.
+        show_value: If `True`, shows a floating badge with the current
+            value above the handle. Defaults to `False`.
+        show_minmax: If `True`, shows min/max labels at the track ends.
+            Defaults to `False`.
+        tick_step: Spacing between major tick marks. `None` disables
+            ticks entirely.
+        minor_ticks: Number of minor tick marks between each major tick.
+            Defaults to `0`.
+        tick_labels: If `True`, shows numeric labels at major tick
+            positions. Defaults to `True`.
+        tick_format: Python format string applied to tick and badge labels.
+            Defaults to `'{:.0f}'`.
+        step: Snap increment. When set, click/drag values snap to multiples of
+            `step` (measured from `min_value`) and the arrow keys move by `step`.
+            `None` (the default) leaves the value continuous. Independent of
+            `tick_step`, which only places tick marks.
+        accent: Accent token controlling the fill, handle, and focus ring
+            color. Defaults to `'primary'`.
+        disabled: If `True`, slider is non-interactive. Defaults to
+            `False`.
+        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,
+        value: float = 0,
+        *,
+        min_value: float = 0,
+        max_value: float = 100,
+        signal: "Signal[float] | None" = None,
+        orient: Orient = "horizontal",
+        show_value: bool = False,
+        show_minmax: bool = False,
+        tick_step: float | None = None,
+        minor_ticks: int = 0,
+        tick_labels: bool = True,
+        tick_format: str = "{:.0f}",
+        step: float | None = None,
+        accent: AccentToken | str | None = None,
+        disabled: bool = False,
+        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] = {
+            "value":        value,
+            "minvalue":     min_value,
+            "maxvalue":     max_value,
+            "orient":       orient,
+            "show_value":   show_value,
+            "show_minmax":  show_minmax,
+            "tick_interval": tick_step,
+            "minor_ticks":  minor_ticks,
+            "tick_labels":  tick_labels,
+            "tick_format":  tick_format,
+            "step":         step,
+        }
+        if signal is not None:
+            internal_kwargs["signal"] = signal
+        if accent is not None:
+            internal_kwargs["accent"] = accent
+        if disabled:
+            internal_kwargs["state"] = "disabled"
+
+        self._internal = _InternalSlider(tk_master, **internal_kwargs)
+        self._attach_to_parent(layout_kw)
+
+    # ----- Properties -----
+
+    @property
+    def value(self) -> float:
+        """The current slider value."""
+        return self._internal.value
+
+    @value.setter
+    def value(self, v: float) -> None:
+        # Route through set() so the value is clamped to [min, max] — a bare
+        # signal write would store an out-of-range value the getter reads back.
+        self._internal.set(float(v))
+
+    @property
+    def signal(self) -> "Signal[float]":
+        """The reactive `Signal[float]` linked to this slider."""
+        return self._internal.signal
+
+    @property
+    def min_value(self) -> float:
+        """The minimum value of the slider range."""
+        return self._internal._minvalue
+
+    @min_value.setter
+    def min_value(self, v: float) -> None:
+        self._internal.configure(minvalue=float(v))
+
+    @property
+    def max_value(self) -> float:
+        """The maximum value of the slider range."""
+        return self._internal._maxvalue
+
+    @max_value.setter
+    def max_value(self, v: float) -> None:
+        self._internal.configure(maxvalue=float(v))
+
+    @property
+    def step(self) -> float | None:
+        """Snap increment, or `None` when the value is continuous."""
+        return self._internal._step_size
+
+    @step.setter
+    def step(self, v: float | None) -> None:
+        self._internal.configure(step=v)
+
+    @property
+    def disabled(self) -> bool:
+        """Whether the slider is non-interactive."""
+        return self._internal._state == "disabled"
+
+    @disabled.setter
+    def disabled(self, v: bool) -> None:
+        self._internal.configure(state="disabled" if v else "normal")
+
+    # ----- Event shorthands -----
+
+    @overload
+    def on_change(self) -> Stream: ...
+    @overload
+    def on_change(self, handler: Callable[[SliderEvent], Any]) -> Subscription: ...
+    def on_change(self, handler: Callable[[SliderEvent], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired continuously as the handle moves.
+
+        The current value is available via `slider.value` inside the handler.
+
+        Args:
+            handler: Called with a :class:`~bootstack.events.SliderEvent`. 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)
+
+    @overload
+    def on_commit(self) -> Stream: ...
+    @overload
+    def on_commit(self, handler: Callable[[SliderCommitEvent], Any]) -> Subscription: ...
+    def on_commit(self, handler: Callable[[SliderCommitEvent], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired when the handle is released.
+
+        Args:
+            handler: Called with a :class:`~bootstack.events.SliderCommitEvent`. 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("commit", handler)
+
+
+register_widget_events(Slider, _SLIDER_EVENTS)
+
+
+class RangeSlider(PublicWidgetBase):
+    """A two-handle slider for selecting a low/high value range.
+
+    The initial handle positions are the first two positional arguments.
+    All options are keyword-only.
+
+    Args:
+        low_value: Initial low-handle value. Defaults to `0`.
+        high_value: Initial high-handle value. Defaults to `100`.
+        min_value: Minimum of the range. Defaults to `0`.
+        max_value: Maximum of the range. Defaults to `100`.
+        low_signal: Reactive `Signal[float]` linked to the low handle.
+        high_signal: Reactive `Signal[float]` linked to the high handle.
+        orient: Track orientation. Default `'horizontal'`.
+        show_value: If `True`, shows floating badges on both handles.
+            Defaults to `False`.
+        tick_step: Spacing between major tick marks. `None` disables
+            ticks entirely.
+        minor_ticks: Number of minor tick marks between each major tick.
+            Defaults to `0`.
+        tick_labels: If `True`, shows numeric labels at major tick
+            positions. Defaults to `True`.
+        tick_format: Python format string applied to tick and badge labels.
+            Defaults to `'{:.0f}'`.
+        step: Snap increment. When set, handle values snap to multiples of
+            `step` (measured from `min_value`) and the arrow keys move by `step`.
+            `None` (the default) leaves the values continuous. Independent of
+            `tick_step`, which only places tick marks.
+        accent: Accent token controlling the fill, handles, and focus ring
+            color. Defaults to `'primary'`.
+        disabled: If `True`, slider is non-interactive. Defaults to
+            `False`.
+        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,
+        low_value: float = 0,
+        high_value: float = 100,
+        *,
+        min_value: float = 0,
+        max_value: float = 100,
+        low_signal: "Signal[float] | None" = None,
+        high_signal: "Signal[float] | None" = None,
+        orient: Orient = "horizontal",
+        show_value: bool = False,
+        tick_step: float | None = None,
+        minor_ticks: int = 0,
+        tick_labels: bool = True,
+        tick_format: str = "{:.0f}",
+        step: float | None = None,
+        accent: AccentToken | str | None = None,
+        disabled: bool = False,
+        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] = {
+            "lovalue":       low_value,
+            "hivalue":       high_value,
+            "minvalue":      min_value,
+            "maxvalue":      max_value,
+            "orient":        orient,
+            "show_value":    show_value,
+            "tick_interval": tick_step,
+            "minor_ticks":   minor_ticks,
+            "tick_labels":   tick_labels,
+            "tick_format":   tick_format,
+            "step":          step,
+        }
+        if low_signal is not None:
+            internal_kwargs["lo_signal"] = low_signal
+        if high_signal is not None:
+            internal_kwargs["hi_signal"] = high_signal
+        if accent is not None:
+            internal_kwargs["accent"] = accent
+        if disabled:
+            internal_kwargs["state"] = "disabled"
+
+        self._internal = _InternalRangeSlider(tk_master, **internal_kwargs)
+        self._attach_to_parent(layout_kw)
+
+    # ----- Properties -----
+
+    @property
+    def low_value(self) -> float:
+        """The current low-handle value."""
+        return self._internal.lovalue
+
+    @low_value.setter
+    def low_value(self, v: float) -> None:
+        # Route through set_lo so the value is clamped to [min, high] — a bare
+        # signal write would let the low handle cross above the high handle.
+        self._internal.set_lo(float(v))
+
+    @property
+    def high_value(self) -> float:
+        """The current high-handle value."""
+        return self._internal.hivalue
+
+    @high_value.setter
+    def high_value(self, v: float) -> None:
+        # Route through set_hi so the value is clamped to [low, max].
+        self._internal.set_hi(float(v))
+
+    @property
+    def value(self) -> tuple[float, float]:
+        """Current `(low, high)` values as a tuple."""
+        return (self._internal.lovalue, self._internal.hivalue)
+
+    @property
+    def low_signal(self) -> "Signal[float]":
+        """The reactive `Signal[float]` linked to the low handle."""
+        return self._internal._lo_signal
+
+    @property
+    def high_signal(self) -> "Signal[float]":
+        """The reactive `Signal[float]` linked to the high handle."""
+        return self._internal._hi_signal
+
+    @property
+    def min_value(self) -> float:
+        """The minimum value of the slider range."""
+        return self._internal._minvalue
+
+    @min_value.setter
+    def min_value(self, v: float) -> None:
+        self._internal.configure(minvalue=float(v))
+
+    @property
+    def max_value(self) -> float:
+        """The maximum value of the slider range."""
+        return self._internal._maxvalue
+
+    @max_value.setter
+    def max_value(self, v: float) -> None:
+        self._internal.configure(maxvalue=float(v))
+
+    @property
+    def step(self) -> float | None:
+        """Snap increment, or `None` when the values are continuous."""
+        return self._internal._step_size
+
+    @step.setter
+    def step(self, v: float | None) -> None:
+        self._internal.configure(step=v)
+
+    @property
+    def disabled(self) -> bool:
+        """Whether the slider is non-interactive."""
+        return self._internal._state == "disabled"
+
+    @disabled.setter
+    def disabled(self, v: bool) -> None:
+        self._internal.configure(state="disabled" if v else "normal")
+
+    # ----- Event shorthands -----
+
+    @overload
+    def on_change(self) -> Stream: ...
+    @overload
+    def on_change(self, handler: Callable[[RangeSliderEvent], Any]) -> Subscription: ...
+    def on_change(self, handler: Callable[[RangeSliderEvent], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired continuously as either handle moves.
+
+        The current values are available via `slider.low_value` and
+        `slider.high_value` inside the handler.
+
+        Args:
+            handler: Called with a :class:`~bootstack.events.RangeSliderEvent`. 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)
+
+    @overload
+    def on_commit(self) -> Stream: ...
+    @overload
+    def on_commit(self, handler: Callable[[RangeSliderCommitEvent], Any]) -> Subscription: ...
+    def on_commit(self, handler: Callable[[RangeSliderCommitEvent], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired when a handle is released.
+
+        Args:
+            handler: Called with a :class:`~bootstack.events.RangeSliderCommitEvent`. 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("commit", handler)
+
+
+register_widget_events(RangeSlider, _SLIDER_EVENTS)

bootstack/widgets/spinbox.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from typing import overload, Any, Callable, TYPE_CHECKING
+
+from bootstack.widgets._impl.primitives.spinbox import Spinbox as _InternalSpinbox
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets._core.events import register_widget_events
+from bootstack.events import ChangeEvent, Subscription
+from bootstack.streams import Stream
+from bootstack.widgets.types import Event, AccentToken, WidgetDensity
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+_SPINBOX_EVENTS: dict[str, str] = {
+    "change": "<KeyRelease>",
+    "submit": "<Return>",
+}
+
+
+class Spinbox(PublicWidgetBase):
+    """A spin-box that cycles through a fixed list or numeric range.
+
+    Pass either `options=` for a discrete list, or `min_value=`/`max_value=`
+    for a numeric range. `options=` takes precedence if both are provided.
+
+    Args:
+        value: Initial display value.
+        options: Fixed list of values to cycle through.
+        min_value: Minimum numeric value (used when `options=` is not set).
+        max_value: Maximum numeric value.
+        step: Increment between values. Default `1`.
+        wrap: If True, wraps from max back to min and vice versa.
+        value_format: Display format string (e.g. `'%.2f'`).
+        textsignal: Reactive `Signal` linked to the displayed text.
+        width: Width in character cells.
+        disabled: If True, widget is non-interactive.
+        density: Padding density.
+        accent: Accent token applied to the focus ring.
+        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,
+        value: Any = "",
+        *,
+        options: list[Any] | None = None,
+        min_value: float | None = None,
+        max_value: float | None = None,
+        step: float = 1,
+        wrap: bool = False,
+        value_format: str | None = None,
+        textsignal: "Signal | None" = None,
+        width: int | None = None,
+        disabled: bool = False,
+        density: WidgetDensity | None = None,
+        accent: AccentToken | str | 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] = {"wrap": wrap}
+        if options is not None:
+            internal_kwargs["values"] = [str(o) for o in options]
+        elif min_value is not None or max_value is not None:
+            if min_value is not None:
+                internal_kwargs["from_"] = min_value
+            if max_value is not None:
+                internal_kwargs["to"] = max_value
+            internal_kwargs["increment"] = step
+        if value_format is not None:
+            internal_kwargs["format"] = value_format
+        if textsignal is not None:
+            internal_kwargs["textsignal"] = textsignal
+        if width is not None:
+            internal_kwargs["width"] = width
+        if disabled:
+            internal_kwargs["state"] = "disabled"
+        if density is not None:
+            internal_kwargs["density"] = density
+        if accent is not None:
+            internal_kwargs["accent"] = accent
+        # Clean up any None values accidentally set. (**kwargs is layout-only —
+        # already split out above — so it is NOT forwarded to the internal widget.)
+        internal_kwargs = {k: v for k, v in internal_kwargs.items() if v is not None}
+
+        self._internal = _InternalSpinbox(tk_master, **internal_kwargs)
+
+        # Seed the display value after construction in all cases.
+        if value != "":
+            self._internal.set(str(value))
+
+        self._attach_to_parent(layout_kw)
+
+    # ----- Properties -----
+
+    @property
+    def value(self) -> str:
+        return self._internal.get()
+
+    @value.setter
+    def value(self, v: Any) -> None:
+        self._internal.set(str(v))
+
+    @property
+    def disabled(self) -> bool:
+        return str(self._internal.cget("state")) == "disabled"
+
+    @disabled.setter
+    def disabled(self, v: bool) -> None:
+        self._internal.configure(state="disabled" if v else "normal")
+
+    # ----- 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 on each keystroke or spin-button click.
+
+        Returns:
+            Subscription — call `.cancel()` to unsubscribe.
+        """
+        return self.on("change", handler)
+
+    @overload
+    def on_submit(self) -> Stream: ...
+    @overload
+    def on_submit(self, handler: Callable[[Event], Any]) -> Subscription: ...
+    def on_submit(self, handler: Callable[[Event], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired on Enter key.
+
+        Returns:
+            Subscription — call `.cancel()` to unsubscribe.
+        """
+        return self.on("submit", handler)
+
+
+register_widget_events(Spinbox, _SPINBOX_EVENTS)