bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_impl/composites/passwordentry.py

@@ -0,0 +1,142 @@
+"""Password entry field widget with visibility toggle.
+
+Provides a specialized text entry field for password input with masked characters
+and an optional visibility toggle button.
+"""
+
+from bootstack.widgets._impl.primitives.button import Button
+from bootstack.widgets._impl.composites.field import Field, FieldOptions
+from bootstack.widgets._impl.mixins.configure_mixin import configure_delegate
+from bootstack.widgets.types import Master
+from typing_extensions import Unpack
+
+
+class PasswordEntry(Field):
+    """A password entry field widget with masked input and visibility toggle.
+
+    PasswordEntry extends the Field widget to provide password-specific functionality,
+    including character masking and a toggle button to temporarily reveal the password.
+    The widget automatically inserts a visibility toggle button (eye icon) that shows
+    the password while pressed and hides it when released.
+    """
+
+    def __init__(
+            self,
+            master: Master = None,
+            value: str = None,
+            label: str = None,
+            message: str = None,
+            show_visibility_toggle: bool = True,
+            **kwargs: Unpack[FieldOptions]):
+        """Args:
+            master: Parent widget. If None, uses the default root window.
+            value: Initial password value to display (masked). Default is None.
+            label: Optional label text to display above the entry field.
+                If required=True, an asterisk (*) is automatically appended.
+            message: Optional message text to display below the entry field.
+                Used for hints or help text. Replaced by validation errors when
+                validation fails.
+            show_visibility_toggle: If True, displays the visibility toggle button
+                (eye icon) that reveals the password while pressed. Default is True.
+                Can be changed at runtime via `configure(show_visibility_toggle=...)`.
+
+        Other Parameters:
+            show: Character to mask password input. Default is '•'.
+            required: If True, field cannot be empty.
+            accent: Accent token for the focus ring and active border.
+            allow_blank: Allow empty input.
+            cursor: Cursor style when hovering.
+            font: Font for text display.
+            foreground: Text color.
+            initial_focus: If True, widget receives focus on creation.
+            justify: Text alignment.
+            show_message: If True, displays message area.
+            padding: Padding around entry widget.
+            takefocus: If True, widget accepts Tab focus.
+            textvariable: Tkinter Variable to link with text.
+                See [tkinter Variables](https://docs.python.org/3/library/tkinter.html#tkinter-variables).
+            textsignal: Signal object for reactive updates.
+            width: Width in characters.
+        """
+        # set default mask if not provided
+        self._show_indicator = kwargs.get('show', '•')
+        kwargs.setdefault('show', self._show_indicator)
+        super().__init__(master, value=value, label=label, message=message, **kwargs)
+
+        # configuration
+        self._show_visibility_toggle = show_visibility_toggle
+        self._show_visibility_pack = {}
+
+        self.insert_addon(
+            Button,
+            position="after",
+            name="visibility",
+            icon={"name": "eye", "state": [("pressed", "eye-slash")]},
+            compound="image",
+            icon_only=True,
+            # Revealing only flips the mask char — it never mutates the value —
+            # so the toggle stays usable on a read-only field (e.g. a generated
+            # secret shown for the user to peek at). A fully disabled field still
+            # dims it. (active_when_readonly postdates this widget, hence the gap.)
+            active_when_readonly=True,
+        )
+        addon = self.addons['visibility']
+        addon.bind('<ButtonPress>', self._show_password, add=True)
+        addon.bind('<ButtonRelease>', self._hide_password, add=True)
+
+        # Apply initial visibility setting
+        if not show_visibility_toggle:
+            self._apply_visibility_toggle(False)
+
+    @property
+    def _visibility_toggle(self):
+        """Get the visibility toggle button widget."""
+        return self.addons['visibility']
+
+    def _show_password(self, _):
+        """Reveal the password by removing character masking."""
+        self.entry_widget['show'] = ''
+
+    def _hide_password(self, _):
+        """Hide the password by restoring character masking."""
+        # leave an unmasked placeholder alone — it is not real input to mask
+        if getattr(self.entry_widget, '_showing_placeholder', False):
+            return
+        self.entry_widget['show'] = self._show_indicator
+
+    # ------ Configuration Delegates ------
+
+    @configure_delegate('show_visibility_toggle')
+    def _delegate_show_visibility_toggle(self, value=None):
+        """Get or set the visibility of the eye-icon toggle button."""
+        if value is None:
+            return self._show_visibility_toggle
+        else:
+            self._apply_visibility_toggle(value)
+        return None
+
+    def _apply_visibility_toggle(self, value: bool):
+        """Show or hide the visibility toggle button.
+
+        Args:
+            value: If True, show the toggle button. If False, hide it.
+        """
+        self._show_visibility_toggle = value
+        is_managed = bool(self._visibility_toggle.winfo_manager())
+        if value and not is_managed:
+            self._visibility_toggle.pack(**self._show_visibility_pack)
+        elif not value and is_managed:
+            self._show_visibility_pack = self._visibility_toggle.pack_info()
+            self._visibility_toggle.pack_forget()
+
+    def reveal(self) -> None:
+        """Remove character masking to show the password in plain text."""
+        self.entry_widget['show'] = ''
+
+    def hide(self) -> None:
+        """Restore character masking."""
+        # leave an unmasked placeholder alone — it is not real input to mask
+        if getattr(self.entry_widget, '_showing_placeholder', False):
+            return
+        self.entry_widget['show'] = self._show_indicator
+

bootstack/widgets/_impl/composites/pathentry.py

@@ -0,0 +1,168 @@
+"""Path entry field widget with file/directory chooser dialog."""
+
+from tkinter import filedialog
+from typing import Any, Literal
+
+from typing_extensions import Unpack
+
+from bootstack.events import ChangeEvent
+from bootstack.widgets._impl.primitives.button import Button
+from bootstack.widgets._impl.composites.field import Field, FieldOptions
+from bootstack.widgets._impl.mixins import configure_delegate
+from bootstack.widgets.types import Master
+
+PathMode = Literal['open', 'open_multiple', 'save', 'directory']
+
+_MODE_TO_DIALOG = {
+    'open':          filedialog.askopenfilename,
+    'open_multiple': filedialog.askopenfilenames,
+    'save':          filedialog.asksaveasfilename,
+    'directory':     filedialog.askdirectory,
+}
+
+
+class PathEntry(Field):
+    """A path entry field with a browse button that opens a native dialog."""
+
+    def __init__(
+            self,
+            master: Master = None,
+            *,
+            value: str | None = None,
+            mode: PathMode = 'open',
+            dialog_title: str | None = None,
+            start_dir: str | None = None,
+            file_filters: list[tuple[str, str]] | None = None,
+            default_extension: str | None = None,
+            default_filename: str | None = None,
+            label: str = None,
+            message: str = None,
+            **kwargs: Unpack[FieldOptions]
+    ):
+        """Args:
+            master: Parent widget. If None, uses the default root window.
+            value: Initial path value. Updated when the user picks a path.
+            mode: Dialog type — `'open'` (default), `'open_multiple'`,
+                `'save'`, or `'directory'`.
+            dialog_title: Title shown in the native picker window.
+            start_dir: Directory the dialog opens in.
+            file_filters: File type filters, e.g. `[('Images', '*.png *.jpg')]`.
+                Not used for `'directory'` mode.
+            default_extension: Extension appended automatically if the user
+                omits it. `'save'` mode only.
+            default_filename: Suggested filename pre-filled in the dialog.
+                `'save'` mode only.
+            label: Label displayed above the field.
+            message: Hint text displayed below the field.
+        """
+        self._mode = mode
+        self._dialog_title = dialog_title
+        self._start_dir = start_dir
+        self._file_filters = file_filters
+        self._default_extension = default_extension
+        self._default_filename = default_filename
+        self._dialog_result = None
+        self._prev_value: str | None = value
+
+        super().__init__(master=master, label=label, message=message, value=value, **kwargs)
+
+        self.insert_addon(
+            Button,
+            position="after",
+            name="dialog-button",
+            icon="folder",
+            icon_only=True,
+            command=self._show_file_chooser
+        )
+
+    @property
+    def dialog_button(self) -> Button:
+        """The browse button widget."""
+        return self.addons.get('dialog-button')
+
+    @property
+    def dialog_result(self) -> str | tuple[str, ...] | None:
+        """Raw result from the most recent dialog (string or tuple of strings)."""
+        return self._dialog_result
+
+    def _build_dialog_kwargs(self) -> dict[str, Any]:
+        """Assemble the kwargs dict for the native dialog call."""
+        opts: dict[str, Any] = {}
+        if self._dialog_title is not None:
+            opts['title'] = self._dialog_title
+        if self._start_dir is not None:
+            opts['initialdir'] = self._start_dir
+        if self._file_filters is not None:
+            opts['filetypes'] = self._file_filters
+        if self._default_extension is not None:
+            opts['defaultextension'] = self._default_extension
+        if self._default_filename is not None:
+            opts['initialfile'] = self._default_filename
+        return opts
+
+    # ------ Configuration delegates ------
+
+    @configure_delegate('mode')
+    def _delegate_mode(self, value: PathMode = None):
+        """Get or set the dialog mode."""
+        if value is None:
+            return self._mode
+        self._mode = value
+
+    @configure_delegate('dialog_title')
+    def _delegate_dialog_title(self, value: str = None):
+        if value is None:
+            return self._dialog_title
+        self._dialog_title = value
+
+    @configure_delegate('start_dir')
+    def _delegate_start_dir(self, value: str = None):
+        if value is None:
+            return self._start_dir
+        self._start_dir = value
+
+    @configure_delegate('file_filters')
+    def _delegate_file_filters(self, value: list = None):
+        if value is None:
+            return self._file_filters
+        self._file_filters = value
+
+    @configure_delegate('default_extension')
+    def _delegate_default_extension(self, value: str = None):
+        if value is None:
+            return self._default_extension
+        self._default_extension = value
+
+    @configure_delegate('default_filename')
+    def _delegate_default_filename(self, value: str = None):
+        if value is None:
+            return self._default_filename
+        self._default_filename = value
+
+    def _show_file_chooser(self):
+        """Open the native dialog and update the entry with the selected path."""
+        dialog_func = _MODE_TO_DIALOG.get(self._mode)
+        if dialog_func is None:
+            raise ValueError(f"Invalid mode {self._mode!r}")
+
+        result = dialog_func(**self._build_dialog_kwargs())
+        self._dialog_result = result
+
+        if isinstance(result, (tuple, list)):
+            display_text = ", ".join(str(p) for p in result)
+        else:
+            display_text = result
+
+        if result:
+            prev_value = self._prev_value
+            self._prev_value = display_text
+            self.value = display_text
+            self.event_generate(
+                '<<Change>>',
+                data=ChangeEvent(
+                    value=display_text,
+                    prev_value=prev_value,
+                    text=display_text,
+                ),
+                when="tail"
+            )

bootstack/widgets/_impl/composites/picture.py

@@ -0,0 +1,289 @@
+"""Internal Picture composite — a canvas-backed image display.
+
+Renders a single image (or an animated sequence) into a themed canvas, fitting
+it to the canvas's allocated size with a CSS `object-fit`-style policy. The
+public `bootstack.Picture` wrapper drives this; nothing here is public.
+
+The canvas (not a Label) is the backing widget on purpose: it does not
+shrink-wrap to the image, it reports its allocated pixel size through
+`<Configure>`, and it letterboxes cleanly behind a fitted image.
+"""
+
+from __future__ import annotations
+
+from tkinter import Canvas, TclError
+from typing import Any
+
+from PIL import Image as PILImage, ImageSequence
+from PIL.ImageTk import PhotoImage
+
+from bootstack.events import ImageErrorEvent, ImageLoadEvent
+from bootstack.style.style import get_style
+from bootstack.widgets._impl.composites._image_fit import (
+    FitMode, fit_image, round_corners, rounded_mask,
+)
+from bootstack.widgets._impl.primitives.frame import Frame
+from bootstack.widgets.types import Master
+
+# Map an anchor token to a (relative-x, relative-y) position in the box and the
+# matching Tk canvas image anchor. Used to place an image that does not fill the
+# box (contain / scale-down / none).
+_ANCHOR_POS: dict[str, tuple[float, float]] = {
+    "center": (0.5, 0.5),
+    "n": (0.5, 0.0), "s": (0.5, 1.0), "e": (1.0, 0.5), "w": (0.0, 0.5),
+    "nw": (0.0, 0.0), "ne": (1.0, 0.0), "sw": (0.0, 1.0), "se": (1.0, 1.0),
+}
+
+
+class Picture(Frame):
+    """Canvas-backed image display with fit modes, resize, and GIF playback."""
+
+    def __init__(
+        self,
+        master: Master = None,
+        *,
+        source: Any = None,
+        fit: FitMode = "contain",
+        anchor: str = "center",
+        corner_radius: int = 0,
+        autoplay: bool = True,
+        loop: bool = True,
+        img_width: int | None = None,
+        img_height: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(master, **kwargs)
+
+        self._fit: FitMode = fit
+        self._anchor = anchor if anchor in _ANCHOR_POS else "center"
+        self._corner_radius = max(0, int(corner_radius))
+        self._autoplay = autoplay
+        self._loop = loop
+        self._fixed_w = img_width
+        self._fixed_h = img_height
+
+        from bootstack.scheduling import Schedule
+
+        self._source: Any = None              # public Image handle, or None
+        self._frames: list[tuple[PILImage.Image, int]] = []  # (RGBA frame, ms)
+        self._frame_index = 0
+        self._schedule = Schedule(self)        # cancels itself on destroy
+        self._anim_job = None
+        self._photo: PhotoImage | None = None  # strong ref — Tk GC guard
+        self._img_id: int | None = None
+        self._box: tuple[int, int] = (0, 0)
+        self._mask_key: tuple[int, int, int] | None = None  # single-entry cache
+        self._mask: PILImage.Image | None = None
+
+        self._surface_color = self._resolve_surface()
+        self._canvas = Canvas(
+            self,
+            highlightthickness=0,
+            bd=0,
+            background=self._surface_color,
+            width=self._fixed_w or 1,
+            height=self._fixed_h or 1,
+        )
+        self._canvas.pack(fill="both", expand=True)
+        self._canvas.bind("<Configure>", self._on_configure)
+        self._canvas.bind("<Button-1>", self._forward_click)
+
+        # Defer the initial load to idle so the constructor returns first: the
+        # caller can bind on_load/on_error before the <<PictureLoad>> fires.
+        if source is not None:
+            self._schedule.idle(lambda: self.set_source(source))
+
+    # ----- theme / surface ---------------------------------------------------
+
+    def _resolve_surface(self) -> str:
+        """Resolve the canvas letterbox color from the frame's surface token."""
+        token = getattr(self, "_surface", None) or "background"
+        builder = get_style().style_builder
+        try:
+            return builder.color(token)
+        except Exception:
+            return builder.color("background")
+
+    def _bs_apply_theme(self, _event=None) -> None:
+        self._surface_color = self._resolve_surface()
+        try:
+            self._canvas.configure(background=self._surface_color)
+        except TclError:
+            return
+        # A theme-following icon source must re-render in the new theme color.
+        src = self._source
+        if src is not None and getattr(src, "_is_theme_following", False):
+            self.set_source(src)
+
+    # ----- source ------------------------------------------------------------
+
+    def set_source(self, source: Any) -> None:
+        """Replace the displayed image and (re)start playback if animated.
+
+        Args:
+            source: A public `bootstack.images.Image` handle, or None to clear.
+        """
+        self._stop_animation()
+        self._source = source
+        if source is None:
+            self._frames = []
+            self._clear_canvas()
+            return
+        try:
+            self._frames = self._load_frames(source)
+        except Exception as exc:  # decode/seek/format failures
+            self._frames = []
+            self._clear_canvas()
+            self.event_generate(
+                "<<PictureError>>", data=ImageErrorEvent(message=str(exc))
+            )
+            return
+
+        self._frame_index = 0
+        self._render_current()
+
+        first = self._frames[0][0]
+        self.event_generate(
+            "<<PictureLoad>>",
+            data=ImageLoadEvent(
+                width=first.width, height=first.height, frames=len(self._frames)
+            ),
+        )
+        if self._autoplay and len(self._frames) > 1:
+            self.play()
+
+    def _load_frames(self, image: Any) -> list[tuple[PILImage.Image, int]]:
+        """Decode `image` into a list of (RGBA frame, duration-ms) tuples."""
+        # A deferred icon handle has no raster source to open; render its glyph.
+        icon = getattr(image, "_icon", None)
+        if icon is not None:
+            from bootstack._core.images import _ImageService
+
+            color = image._resolve_icon_color()
+            rgba = _ImageService._render_icon(icon.name, icon.size, color)
+            return [(rgba.convert("RGBA"), 0)]
+
+        pil = image._load_pil()
+        frames: list[tuple[PILImage.Image, int]] = []
+        for frame in ImageSequence.Iterator(pil):
+            rgba = frame.convert("RGBA").copy()
+            duration = int(frame.info.get("duration", 0) or 0)
+            frames.append((rgba, duration))
+        if not frames:
+            raise ValueError("image has no frames")
+        return frames
+
+    # ----- fit / render ------------------------------------------------------
+
+    def set_fit(self, fit: FitMode) -> None:
+        """Change the fit policy and re-render."""
+        self._fit = fit
+        self._render_current()
+
+    def _on_configure(self, event) -> None:
+        box = (int(event.width), int(event.height))
+        if box == self._box:
+            return
+        self._box = box
+        self._render_current()
+
+    def _render_current(self) -> None:
+        """Compose the current frame to the live box and draw it."""
+        if not self._frames:
+            return
+        bw, bh = self._box
+        if self._fixed_w:
+            bw = self._fixed_w
+        if self._fixed_h:
+            bh = self._fixed_h
+        if bw <= 1 or bh <= 1:
+            return  # not laid out yet; the <Configure> pass will render
+
+        frame = self._frames[self._frame_index][0]
+        composed = self._compose(frame, bw, bh)
+        self._photo = PhotoImage(image=composed)
+
+        rx, ry = _ANCHOR_POS[self._anchor]
+        x = int(bw * rx)
+        y = int(bh * ry)
+        if self._img_id is None:
+            self._img_id = self._canvas.create_image(
+                x, y, image=self._photo, anchor=self._anchor
+            )
+        else:
+            self._canvas.coords(self._img_id, x, y)
+            self._canvas.itemconfigure(self._img_id, image=self._photo, anchor=self._anchor)
+
+    def _compose(self, frame: PILImage.Image, bw: int, bh: int) -> PILImage.Image:
+        """Scale/crop `frame` to the box per the fit policy; round the corners."""
+        result = fit_image(frame, bw, bh, self._fit)
+        if self._corner_radius > 0:
+            result = round_corners(result, self._corner_radius, self._corner_mask(*result.size))
+        return result
+
+    def _corner_mask(self, w: int, h: int) -> PILImage.Image:
+        """A cached rounded-rect mask for a `w`x`h` result (reused across frames)."""
+        key = (w, h, self._corner_radius)
+        if self._mask_key != key or self._mask is None:
+            self._mask = rounded_mask(w, h, self._corner_radius)
+            self._mask_key = key
+        return self._mask
+
+    def _clear_canvas(self) -> None:
+        if self._img_id is not None:
+            try:
+                self._canvas.delete(self._img_id)
+            except TclError:
+                pass
+            self._img_id = None
+        self._photo = None
+
+    # ----- animation ---------------------------------------------------------
+
+    @property
+    def is_playing(self) -> bool:
+        return self._anim_job is not None
+
+    def play(self) -> None:
+        """Start (or resume) playback of an animated source."""
+        if len(self._frames) <= 1 or self._anim_job is not None:
+            return
+        self._schedule_next()
+
+    def pause(self) -> None:
+        """Pause playback on the current frame."""
+        self._stop_animation()
+
+    def stop(self) -> None:
+        """Stop playback and reset to the first frame."""
+        self._stop_animation()
+        if self._frames:
+            self._frame_index = 0
+            self._render_current()
+
+    def _schedule_next(self) -> None:
+        duration = self._frames[self._frame_index][1] or 100
+        self._anim_job = self._schedule.delay(duration, self._advance_frame)
+
+    def _advance_frame(self) -> None:
+        self._anim_job = None
+        nxt = self._frame_index + 1
+        if nxt >= len(self._frames):
+            if not self._loop:
+                return
+            nxt = 0
+        self._frame_index = nxt
+        self._render_current()
+        self._schedule_next()
+
+    def _stop_animation(self) -> None:
+        if self._anim_job is not None:
+            self._anim_job.cancel()
+            self._anim_job = None
+
+    # ----- events ------------------------------------------------------------
+
+    def _forward_click(self, event) -> None:
+        # The canvas covers the frame, so clicks land on it, not the frame the
+        # public wrapper binds. Re-emit on the frame so on_click works.
+        self.event_generate("<<PictureClick>>", x=event.x, y=event.y)