bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/picture.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable, Literal, overload, TYPE_CHECKING
+
+from bootstack.events import ImageErrorEvent, ImageLoadEvent, Event, Subscription
+from bootstack.streams import Stream
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets._core.events import register_widget_events
+from bootstack.widgets._impl.composites.picture import Picture as _InternalPicture
+from bootstack.widgets.types import Anchor, Padding, SurfaceToken
+
+if TYPE_CHECKING:
+    from bootstack.images import Image
+
+ImageFit = Literal["contain", "cover", "fill", "none", "scale-down"]
+
+
+class Picture(PublicWidgetBase):
+    """Displays an image, scaled to fit, with optional animation.
+
+    `Picture` is the display widget for pictures and media — the counterpart to
+    an `Image`, which is only a source handle. Hand it an `Image` (or a file
+    path) and it renders the picture into a resizable area, scaling it to fit
+    with a chosen policy. Animated GIF and WebP sources play automatically.
+
+    Unlike showing an image on a `Label`, a `Picture` is sizing-aware: it fills
+    the space it is given and re-fits the picture as that space changes, so it
+    works in responsive layouts.
+
+    Args:
+        image: The picture to show — an `Image` handle (from `bootstack.images`),
+            a file path (`str` or `Path`, opened for you), or `None` for an empty
+            frame. Assign the `image` property later to change it.
+        fit: How the picture is scaled into the display area. Default
+            `'contain'`.
+
+            - `'contain'` — scale to fit inside, preserving aspect ratio
+              (letterboxing any remainder).
+            - `'cover'` — scale to fill, preserving aspect ratio (cropping the
+              overflow).
+            - `'fill'` — stretch to fill, ignoring aspect ratio.
+            - `'none'` — show at natural size, no scaling.
+            - `'scale-down'` — like `'contain'`, but never enlarge past natural
+              size.
+        width: Fixed display width in pixels. Omit to size from the container.
+        height: Fixed display height in pixels. Omit to size from the container.
+        anchor: Where the picture sits within the area when it does not fill it
+            (with `'contain'`, `'scale-down'`, or `'none'`). Default `'center'`.
+        corner_radius: Rounded-corner radius in pixels. `0` (default) is square.
+        autoplay: Start playing an animated source as soon as it is shown.
+            Default `True`.
+        loop: Loop an animated source. Default `True`.
+        surface: Background surface token used to letterbox behind the picture.
+        parent: Explicit parent widget. If omitted, the current context-stack
+            container is used.
+        **kwargs: Layout placement options applied by the parent container
+            (e.g. `fill`, `expand`, `row`, `column`). See :doc:`/tasks/layout`.
+    """
+
+    _internal_class = _InternalPicture
+
+    def __init__(
+        self,
+        image: "Image | str | Path | None" = None,
+        *,
+        fit: ImageFit = "contain",
+        width: int | None = None,
+        height: int | None = None,
+        anchor: Anchor = "center",
+        corner_radius: int = 0,
+        autoplay: bool = True,
+        loop: bool = True,
+        surface: SurfaceToken | str | None = None,
+        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] = {
+            "fit": fit,
+            "anchor": anchor,
+            "corner_radius": corner_radius,
+            "autoplay": autoplay,
+            "loop": loop,
+            "img_width": width,
+            "img_height": height,
+        }
+        if surface is not None:
+            internal_kwargs["surface"] = surface
+        if padding is not None:
+            internal_kwargs["padding"] = padding
+        internal_kwargs.update(kwargs)
+
+        self._source = self._coerce_image(image)
+        self._internal = self._internal_class(
+            tk_master, source=self._source, **internal_kwargs
+        )
+        self._attach_to_parent(layout_kw)
+
+    @staticmethod
+    def _coerce_image(image: "Image | str | Path | None") -> Any:
+        """Normalize an `image=` argument to an `Image` handle (or None)."""
+        if image is None:
+            return None
+        from bootstack.images import Image as _ImageHandle
+
+        if isinstance(image, _ImageHandle):
+            return image
+        if isinstance(image, (str, Path)):
+            return _ImageHandle.open(image)
+        try:
+            from PIL.Image import Image as _PILImage
+
+            if isinstance(image, _PILImage):
+                return _ImageHandle.from_pil(image)
+        except Exception:
+            pass
+        raise TypeError(
+            "Picture image must be an Image handle, a file path, or a PIL image; "
+            f"got {type(image).__name__}"
+        )
+
+    # ----- Properties -----
+
+    @property
+    def image(self) -> "Image | None":
+        """The displayed image handle, or `None` when empty.
+
+        Assign an `Image`, a file path, or `None` to change what is shown.
+        """
+        return self._source
+
+    @image.setter
+    def image(self, value: "Image | str | Path | None") -> None:
+        self._source = self._coerce_image(value)
+        self._internal.set_source(self._source)
+
+    @property
+    def fit(self) -> ImageFit:
+        """The fit policy controlling how the picture is scaled into its area."""
+        return self._internal._fit
+
+    @fit.setter
+    def fit(self, value: ImageFit) -> None:
+        self._internal.set_fit(value)
+
+    @property
+    def is_playing(self) -> bool:
+        """Whether an animated source is currently playing."""
+        return self._internal.is_playing
+
+    # ----- Playback -----
+
+    def play(self) -> None:
+        """Start or resume playback of an animated source.
+
+        Has no effect on a still image or when already playing.
+        """
+        self._internal.play()
+
+    def pause(self) -> None:
+        """Pause playback on the current frame.
+
+        Resume with `play`; the frame stays on screen meanwhile.
+        """
+        self._internal.pause()
+
+    def stop(self) -> None:
+        """Stop playback and reset to the first frame."""
+        self._internal.stop()
+
+    # ----- Events -----
+
+    @overload
+    def on_load(self) -> Stream: ...
+    @overload
+    def on_load(self, handler: Callable[[ImageLoadEvent], Any]) -> Subscription: ...
+    def on_load(
+        self, handler: Callable[[ImageLoadEvent], Any] | None = None
+    ) -> Stream | Subscription:
+        """Register a callback fired when an image is decoded and displayed.
+
+        The handler receives an :class:`~bootstack.events.ImageLoadEvent` with
+        the picture's natural `width`, `height`, and frame count.
+
+        Args:
+            handler: Called with the load event. Omit to get a composable
+                :class:`~bootstack.streams.Stream`.
+
+        Returns:
+            A :class:`~bootstack.events.Subscription` when a handler is given,
+            otherwise a :class:`~bootstack.streams.Stream`.
+        """
+        return self.on("load", handler)
+
+    @overload
+    def on_error(self) -> Stream: ...
+    @overload
+    def on_error(self, handler: Callable[[ImageErrorEvent], Any]) -> Subscription: ...
+    def on_error(
+        self, handler: Callable[[ImageErrorEvent], Any] | None = None
+    ) -> Stream | Subscription:
+        """Register a callback fired when an image fails to load or decode.
+
+        The handler receives an :class:`~bootstack.events.ImageErrorEvent`
+        carrying a human-readable `message`.
+
+        Args:
+            handler: Called with the error event. Omit to get a composable
+                :class:`~bootstack.streams.Stream`.
+
+        Returns:
+            A :class:`~bootstack.events.Subscription` when a handler is given,
+            otherwise a :class:`~bootstack.streams.Stream`.
+        """
+        return self.on("error", handler)
+
+    @overload
+    def on_click(self) -> Stream: ...
+    @overload
+    def on_click(self, handler: Callable[[Event], Any]) -> Subscription: ...
+    def on_click(
+        self, handler: Callable[[Event], Any] | None = None
+    ) -> Stream | Subscription:
+        """Register a callback for clicks on the picture.
+
+        The handler receives a curated :class:`~bootstack.events.Event`.
+
+        Args:
+            handler: Called with the click `Event`. Omit to get a composable
+                :class:`~bootstack.streams.Stream`.
+
+        Returns:
+            A :class:`~bootstack.events.Subscription` when a handler is given,
+            otherwise a :class:`~bootstack.streams.Stream`.
+        """
+        return self.on("click", handler)
+
+
+register_widget_events(
+    Picture,
+    {
+        "load": "<<PictureLoad>>",
+        "error": "<<PictureError>>",
+        "click": "<<PictureClick>>",
+    },
+)

bootstack/widgets/progressbar.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from typing import Any, Literal, TYPE_CHECKING
+
+from bootstack.widgets._impl.primitives.progressbar import Progressbar as _InternalProgressbar
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets._core.events import register_widget_events
+from bootstack.widgets.types import AccentToken, Orient
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+
+class ProgressBar(PublicWidgetBase):
+    """A progress indicator bar.
+
+    Displays determinate progress (a fixed percentage fill) or indeterminate
+    progress (a looping animation) for operations whose duration is unknown.
+
+    Args:
+        value: Initial progress value. Defaults to `0`.
+        max_value: Value that represents 100% progress. Defaults to `100`.
+        mode: `'determinate'` shows a fixed fill proportional to
+            `value / max_value`; `'indeterminate'` runs a looping animation.
+            Default `'determinate'`.
+        orient: Track orientation. Default `'horizontal'`.
+        signal: Reactive `Signal` two-way bound to `value`.
+        accent: Color intent token for the bar. Defaults to the theme's default
+            color.
+        variant: Style variant. `'thin'` reduces the bar height.
+        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: float = 0,
+        *,
+        max_value: float = 100,
+        mode: Literal["determinate", "indeterminate"] = "determinate",
+        orient: Orient = "horizontal",
+        signal: Signal | None = None,
+        accent: AccentToken | str | None = None,
+        variant: Literal["thin"] | 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] = {
+            "value": value,
+            "maximum": max_value,
+            "mode": mode,
+            "orient": orient,
+        }
+        if signal is not None:
+            internal_kwargs["signal"] = signal
+        if accent is not None:
+            internal_kwargs["accent"] = accent
+        if variant is not None:
+            internal_kwargs["variant"] = variant
+
+        self._internal = _InternalProgressbar(tk_master, **internal_kwargs)
+        self._attach_to_parent(layout_kw)
+
+    # ----- Properties -----
+
+    @property
+    def value(self) -> float:
+        """The current progress value."""
+        return self._internal.get()
+
+    @value.setter
+    def value(self, v: float) -> None:
+        self._internal.set(v)
+
+    @property
+    def max_value(self) -> float:
+        """The value that represents 100% progress."""
+        return float(self._internal.cget("maximum"))
+
+    @max_value.setter
+    def max_value(self, v: float) -> None:
+        self._internal.configure(maximum=float(v))
+
+    # ----- Methods -----
+
+    def start(self, interval: int = 50) -> None:
+        """Start indeterminate animation. `interval` is the step delay in ms."""
+        self._internal.start(interval)
+
+    def stop(self) -> None:
+        """Stop indeterminate animation."""
+        self._internal.stop()
+
+    def step(self, amount: float = 1.0) -> None:
+        """Advance the value by `amount`."""
+        self._internal.step(amount)
+
+
+register_widget_events(ProgressBar, {})

bootstack/widgets/radio_variants.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+from typing import overload, Any, Callable, Literal, TYPE_CHECKING
+
+from bootstack.widgets._impl.primitives.radiobutton import RadioButton as _InternalRadioButton
+from bootstack.widgets._impl.primitives.radiotoggle import RadioToggle as _InternalRadioToggle
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets._core.events import register_widget_events
+from bootstack.events import Subscription
+from bootstack.streams import Stream
+from bootstack.widgets.types import AccentToken, Event, WidgetDensity, IconPosition
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+_RADIO_EVENTS: dict[str, str] = {
+    "change": "<<Change>>",
+    "select": "<<Select>>",
+}
+
+
+class _RadioBase(PublicWidgetBase):
+    """Shared base for Radio and RadioToggleButton."""
+
+    _internal_class: type
+
+    def __init__(
+        self,
+        label: str = "",
+        value: Any = None,
+        *,
+        signal: "Signal | None" = None,
+        text_signal: "Signal | None" = None,
+        on_change: Callable[[], Any] | None = None,
+        icon: str | None = None,
+        selected_icon: str | None = None,
+        unselected_icon: str | None = None,
+        icon_only: bool = False,
+        show_indicator: bool = True,
+        icon_position: IconPosition | None = None,
+        disabled: bool = False,
+        accent: AccentToken | str | None = None,
+        localize: bool | Literal['auto'] | None = None,
+        _internal_options: dict[str, Any] | None = None,
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        self._parent = self._resolve_parent(parent)
+        layout_kw = self._split_layout_kwargs(kwargs)
+        if kwargs:
+            raise TypeError(
+                f"{type(self).__name__}() got unexpected keyword argument(s): "
+                f"{', '.join(sorted(kwargs))}"
+            )
+
+        tk_master = self._parent._child_master() if self._parent else None
+
+        _ctor_callback = on_change
+
+        if icon is not None and not label:
+            icon_only = True
+
+        internal_kwargs: dict[str, Any] = {}
+        if label:
+            internal_kwargs["text"] = label
+        if value is not None:
+            internal_kwargs["value"] = value
+        if signal is not None:
+            internal_kwargs["signal"] = signal
+        if text_signal is not None:
+            internal_kwargs["textsignal"] = text_signal
+        if icon is not None:
+            internal_kwargs["icon"] = icon
+        if selected_icon is not None:
+            internal_kwargs["on_icon"] = selected_icon
+        if unselected_icon is not None:
+            internal_kwargs["off_icon"] = unselected_icon
+        if icon_only:
+            internal_kwargs["icon_only"] = True
+        if not show_indicator:
+            internal_kwargs["show_indicator"] = False
+        if icon_position is not None:
+            internal_kwargs["compound"] = icon_position
+        if disabled:
+            internal_kwargs["state"] = "disabled"
+        if accent is not None:
+            internal_kwargs["accent"] = accent
+        if localize is not None:
+            internal_kwargs["localize"] = localize
+        # Per-subclass styling options (e.g. density — RadioToggleButton only).
+        if _internal_options:
+            internal_kwargs.update(_internal_options)
+
+        self._internal = self._internal_class(tk_master, **internal_kwargs)
+
+        def _command():
+            self._internal.event_generate("<<Change>>")
+            self._internal.event_generate("<<Select>>")
+            if _ctor_callback is not None:
+                _ctor_callback()
+
+        self._internal.configure(command=_command)
+        self._attach_to_parent(layout_kw)
+
+    # ----- Properties -----
+
+    @property
+    def selected(self) -> bool:
+        """True if this radio is the currently selected option in its group."""
+        return self._internal.get() == self._internal.cget("value")
+
+    @property
+    def disabled(self) -> bool:
+        """Whether the control is disabled (non-interactive and greyed out)."""
+        return str(self._internal.cget("state")) == "disabled"
+
+    @disabled.setter
+    def disabled(self, v: bool) -> None:
+        self._internal.configure(state="disabled" if v else "normal")
+
+    # ----- Methods -----
+
+    def select(self) -> None:
+        """Programmatically select this radio button."""
+        self._internal.invoke()
+
+    # ----- Event shorthands -----
+
+    @overload
+    def on_change(self) -> Stream: ...
+    @overload
+    def on_change(self, handler: Callable[[Event], Any]) -> Subscription: ...
+    def on_change(self, handler: Callable[[Event], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired when this radio is selected.
+
+        Args:
+            handler: Called with the :class:`~bootstack.events.Event`. 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_select(self) -> Stream: ...
+    @overload
+    def on_select(self, handler: Callable[[Event], Any]) -> Subscription: ...
+    def on_select(self, handler: Callable[[Event], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired when this radio is selected.
+
+        Args:
+            handler: Called with the :class:`~bootstack.events.Event`. 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("select", handler)
+
+
+class Radio(_RadioBase):
+    """A single radio button — one selectable option in a mutually-exclusive group.
+
+    Radio buttons in a group share a `signal`; clicking one sets the signal
+    to the radio's `value`.
+
+    Usage::
+
+        sig = bs.Signal("a")
+        bs.Radio("Option A", "a", signal=sig)
+        bs.Radio("Option B", "b", signal=sig)
+
+    Args:
+        label: Text displayed beside the radio indicator.
+        value: The value written to `signal` when this radio is selected.
+        signal: Shared `Signal` that holds the group's current value.
+        text_signal: Reactive `Signal` linked to the label text.
+        on_change: Callback fired when this radio is selected.
+        icon: Icon shown for all states.
+        selected_icon: Icon shown when this radio is selected.
+        unselected_icon: Icon shown when this radio is not selected.
+        icon_only: If True, removes extra padding reserved for the label.
+            Inferred automatically when `icon=` is set and no label is provided.
+        show_indicator: If False, hides the circular indicator.
+        icon_position: Position of the icon relative to the text.
+        disabled: If True, widget is non-interactive.
+        accent: Accent token applied to the indicator.
+        localize: Whether the label is translated through the catalog — `True`,
+            `False`, or `'auto'`. Defaults to the app's `localize_mode`. Set
+            `False` to keep a proper noun untranslated.
+        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`.
+    """
+    _internal_class = _InternalRadioButton
+
+
+class RadioToggleButton(_RadioBase):
+    """A radio button that renders as a toggle button — toolbar/segmented-control style.
+
+    Behaves identically to `Radio` but renders as a depressed button when
+    selected rather than showing the circular indicator.
+
+    Args:
+        label: Text displayed on the button.
+        value: The value written to `signal` when this button is selected.
+        signal: Shared `Signal` that holds the group's current value.
+        text_signal: Reactive `Signal` linked to the label text.
+        on_change: Callback fired when this button is selected.
+        icon: Icon shown for all states.
+        selected_icon: Icon shown when selected.
+        unselected_icon: Icon shown when not selected.
+        icon_only: If True, removes extra label padding. Inferred
+            automatically when `icon=` is set and no label is provided.
+        disabled: If True, widget is non-interactive.
+        accent: Accent token applied to the button when selected.
+        density: Widget density.
+        localize: Whether the label is translated through the catalog — `True`,
+            `False`, or `'auto'`. Defaults to the app's `localize_mode`. Set
+            `False` to keep a proper noun untranslated.
+        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`.
+    """
+    _internal_class = _InternalRadioToggle
+
+    def __init__(
+        self,
+        label: str = "",
+        value: Any = None,
+        *,
+        signal: "Signal | None" = None,
+        text_signal: "Signal | None" = None,
+        on_change: Callable[[], Any] | None = None,
+        icon: str | None = None,
+        selected_icon: str | None = None,
+        unselected_icon: str | None = None,
+        icon_only: bool = False,
+        disabled: bool = False,
+        accent: AccentToken | str | None = None,
+        density: WidgetDensity | None = None,
+        localize: bool | Literal['auto'] | None = None,
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            label,
+            value,
+            signal=signal,
+            text_signal=text_signal,
+            on_change=on_change,
+            icon=icon,
+            selected_icon=selected_icon,
+            unselected_icon=unselected_icon,
+            icon_only=icon_only,
+            disabled=disabled,
+            accent=accent,
+            localize=localize,
+            _internal_options=({"density": density} if density is not None else None),
+            parent=parent,
+            **kwargs,
+        )
+
+
+register_widget_events(Radio, _RADIO_EVENTS)
+register_widget_events(RadioToggleButton, _RADIO_EVENTS)