bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_impl/composites/numericentry.py

@@ -0,0 +1,201 @@
+"""Numeric entry field widget with spin buttons.
+
+Provides a specialized entry field for numeric input with increment/decrement
+buttons and keyboard/mouse wheel support.
+"""
+
+from typing import Any, Callable
+from tkinter import TclError
+from typing_extensions import Unpack
+
+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
+
+
+class NumericEntry(Field):
+    """A numeric entry field widget with increment/decrement spin buttons.
+
+    Extends Field to provide numeric input with spin buttons, bounds validation,
+    keyboard stepping (Up/Down arrows), mouse wheel support, and optional wrapping.
+    """
+
+    def __init__(
+            self,
+            master: Master = None,
+            value: int | float = 0,
+            label: str = None,
+            message: str = None,
+            show_spin_buttons: bool = True,
+            minvalue: int | float | None = None,
+            maxvalue: int | float | None = None,
+            increment: int | float = 1,
+            **kwargs: Unpack[FieldOptions]
+    ):
+        """Args:
+            master: Parent widget. If None, uses the default root window.
+            value: Initial numeric value to display.
+            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_spin_buttons: If True, displays increment/decrement buttons
+                (plus and minus icons) to the right of the entry.
+            minvalue: Minimum allowed value (inclusive). Values below
+                this will be clamped or wrapped depending on the wrap setting.
+            maxvalue: Maximum allowed value (inclusive). Values above
+                this will be clamped or wrapped depending on the wrap setting.
+            increment: Step size for increment/decrement operations.
+
+        Other Parameters:
+            wrap: If True, values wrap around at min/max boundaries.
+            value_format: Number format — a `NumberPreset` string
+                (e.g., `'decimal'`, `'percent'`, `'currency'`) or a custom ICU
+                pattern (e.g., `'#,##0.00'`).
+            locale: Locale identifier for number formatting (e.g., `'en_US'`).
+            required: If True, field cannot be empty.
+            accent: Accent token for the focus ring and active border.
+            allow_blank: If True, empty input is allowed (sets value to None).
+            cursor: Cursor style when hovering.
+            exportselection: Export selection to clipboard.
+            font: Font for text display.
+            foreground: Text color.
+            initial_focus: If True, widget receives focus on creation.
+            justify: Text alignment (`'left'`, `'center'`, `'right'`).
+            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.
+            xscrollcommand: Callback for horizontal scrolling.
+        """
+        super().__init__(
+            master, value=value, label=label, message=message, minvalue=minvalue, maxvalue=maxvalue, kind="numeric",
+            increment=increment, **kwargs)
+
+        self._show_spin_buttons = show_spin_buttons
+
+        # pack info
+        self._increment_pack_info = {}
+        self._decrement_pack_info = {}
+
+        # buttons
+        self.insert_addon(
+            Button, position="after", name="decrement", icon="dash-lg", command=self.decrement, icon_only=True)
+        self.insert_addon(
+            Button, position="after", name="increment", icon="plus-lg", command=self.increment, icon_only=True)
+        self._delegate_show_spin_buttons(show_spin_buttons)
+
+        self.entry_widget.bind('<<StateChanged>>', self._on_entry_state_changed, add=True)
+        self._update_spin_button_states()
+
+    @property
+    def increment_widget(self) -> Button:
+        """Get the increment spin button widget."""
+        return self.addons['increment']
+
+    @property
+    def decrement_widget(self) -> Button:
+        """Get the decrement spin button widget."""
+        return self.addons['decrement']
+
+    def increment(self) -> None:
+        """Increment the numeric value by one step."""
+        if not self._entry_is_interactive():
+            return
+        self.entry_widget.event_generate("<<Increment>>")
+
+    def decrement(self) -> None:
+        """Decrement the numeric value by one step."""
+        if not self._entry_is_interactive():
+            return
+        self.entry_widget.event_generate("<<Decrement>>")
+
+    def step(self, n: int = 1) -> None:
+        """Step the value by `n` increments (positive) or decrements (negative).
+
+        Args:
+            n: Number of steps. Positive steps up, negative steps down.
+        """
+        self.entry_widget.step(n)
+
+    def on_increment(self, callback: Callable) -> str:
+        """Register a callback for `<<Increment>>` events (fires when value steps up).
+
+        Args:
+            callback: Receives a Tkinter `Event` object with `event.data['value']`
+                set to the new numeric value.
+
+        Returns:
+            Bind ID — pass to `off_increment()` to unsubscribe.
+        """
+        return self.entry_widget.on_increment(callback)
+
+    def off_increment(self, bind_id: str | None = None) -> None:
+        """Unsubscribe from `<<Increment>>`.
+
+        Args:
+            bind_id: ID returned by `on_increment()`.
+        """
+        self.entry_widget.off_increment(bind_id)
+
+    def on_decrement(self, callback: Callable) -> str:
+        """Register a callback for `<<Decrement>>` events (fires when value steps down).
+
+        Args:
+            callback: Receives a Tkinter `Event` object with `event.data['value']`
+                set to the new numeric value.
+
+        Returns:
+            Bind ID — pass to `off_decrement()` to unsubscribe.
+        """
+        return self.entry_widget.on_decrement(callback)
+
+    def off_decrement(self, bind_id: str | None = None) -> None:
+        """Unsubscribe from `<<Decrement>>`.
+
+        Args:
+            bind_id: ID returned by `on_decrement()`.
+        """
+        self.entry_widget.off_decrement(bind_id)
+
+    def _entry_is_interactive(self) -> bool:
+        """Return True if the entry widget is not disabled or readonly."""
+        state = self.entry_widget.state()
+        return 'disabled' not in state and 'readonly' not in state
+
+    def _on_entry_state_changed(self, _: Any = None):
+        """Sync spin buttons whenever the entry state mutates."""
+        self._update_spin_button_states()
+
+    def _update_spin_button_states(self):
+        """Enable or disable spin buttons based on entry interactivity."""
+        state_value = 'disabled' if not self._entry_is_interactive() else '!disabled'
+        for control in (self.increment_widget, self.decrement_widget):
+            try:
+                control.configure(state=state_value)
+            except TclError:
+                pass
+
+    @configure_delegate('show_spin_buttons')
+    def _delegate_show_spin_buttons(self, value: bool = None):
+        """Get or set the visibility of spin buttons."""
+        if value is None:
+            return self._show_spin_buttons
+        else:
+            self._show_spin_buttons = value
+            if value:
+                if not self.increment_widget.winfo_ismapped():
+                    self.increment_widget.pack(**self._increment_pack_info)
+                if not self.decrement_widget.winfo_ismapped():
+                    self.decrement_widget.pack(**self._decrement_pack_info)
+            else:
+                self._increment_pack_info = self.increment_widget.pack_info()
+                self._decrement_pack_info = self.decrement_widget.pack_info()
+                self.increment_widget.pack_forget()
+                self.decrement_widget.pack_forget()
+        return None

bootstack/widgets/_impl/composites/pagestack.py

@@ -0,0 +1,395 @@
+import tkinter
+from typing import Any, Callable
+
+from typing_extensions import TypedDict, Unpack
+
+from bootstack.events import PageChangeEvent
+from bootstack.widgets._impl.primitives import Frame
+from bootstack.widgets.types import Master, AccentToken, SurfaceToken
+from bootstack._core import NavigationError
+
+
+class PageOptions(TypedDict, total=False):
+    padding: Any
+    width: int
+    height: int
+    style: str
+    cursor: str
+    show_border: bool
+    accent: AccentToken | str
+    variant: str
+    surface: SurfaceToken | str
+    style_options: dict[str, Any]
+
+
+class PageStackKwargs(TypedDict, total=False):
+    takefocus: bool
+    width: int
+    height: int
+    padding: Any
+
+
+class PageStack(Frame):
+    """A navigation container widget for managing multiple pages with history support.
+
+    PageStack provides a stack-based navigation system where only one page is
+    visible at a time. It maintains a navigation history, allowing users to move
+    backward and forward through pages similar to a web browser.
+
+    """
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[PageStackKwargs]):
+        """Initialize a new PageStack instance.
+
+        Creates an empty PageStack with no pages and no navigation history.
+        The widget inherits from Frame and supports all standard Frame
+        configuration options.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            **kwargs: Additional arguments passed to Frame (e.g., `takefocus`,
+                `width`, `height`, `padding`).
+        """
+        super().__init__(master, **kwargs)
+        self._pages: dict[str, tkinter.Widget] = {}
+        self._current: str | None = None
+        self._history: list[tuple[str, dict]] = []
+        self._index: int = -1
+        # macOS (Aqua) only: re-mapping a previously-unmapped page paints blank
+        # for one display cycle, so swapping pages with pack_forget/pack flashes
+        # white. There we instead keep every visited page mapped, stacked in a
+        # single grid cell, and switch with lift()/lower() — no remap, no flash.
+        # A page must stay *full size* while hidden for this to hold (a shrunk
+        # page re-expands with the same blank flash), so each mapped page does
+        # reflow on a window resize; that cost is the deliberate trade. Other
+        # platforms don't have the flash and keep the cheaper one-page-mapped
+        # pack path unchanged.
+        try:
+            self._stacked: bool = self.tk.call('tk', 'windowingsystem') == 'aqua'
+        except tkinter.TclError:
+            self._stacked = False
+
+    def add(self, key: str, page: tkinter.Widget = None, **kwargs) -> tkinter.Widget:
+        """Add a page to the stack, optionally creating a Frame.
+
+        Args:
+            key: Unique identifier for the page (required for navigation).
+            page: The widget to add. If None, creates a Frame.
+            **kwargs: When page is None, these are passed to Frame (e.g., padding, accent, variant).
+
+        Returns:
+            Widget: The page widget (passed or created Frame).
+
+        Raises:
+            NavigationError: If a page with the given key already exists.
+            ValueError: If key is an empty string.
+        """
+        if not key:
+            raise ValueError("Page key cannot be an empty string")
+        if key in self._pages:
+            raise NavigationError(f"Page {key} already exists")
+
+        if page is None:
+            page = Frame(self, **kwargs)
+
+        self._pages[key] = page
+        if self._stacked:
+            # Stacked layout: every page shares grid cell (0, 0); navigate()
+            # maps/lifts the active one. Left unmapped here — it maps on first
+            # show (the initial render always paints fresh, flash or not).
+            self.grid_rowconfigure(0, weight=1)
+            self.grid_columnconfigure(0, weight=1)
+            page._bs_nav_hidden = True
+        else:
+            page.pack(fill='both', expand=True)
+            page.pack_forget()
+        return page
+
+    def remove(self, key: str) -> None:
+        """Remove a page from the stack and destroy its widget.
+
+        Args:
+            key: The identifier of the page to remove
+
+        Raises:
+            NavigationError: If no page with the given key exists.
+            ValueError: If key is an empty string.
+
+        Note:
+            If the removed page is currently displayed, the current page
+            will be set to None without navigating to another page.
+        """
+        if not key:
+            raise ValueError("Page key cannot be an empty string")
+        if key not in self._pages:
+            raise NavigationError(f"Page {key} does not exist")
+        page = self._pages.pop(key)
+        page.destroy()
+        if self._current == key:
+            self._current = None
+
+    def navigate(
+            self,
+            key: str,
+            data: dict | None = None,
+            replace: bool = False,
+            _nav: str = 'push',
+            _prev: tuple[str, dict] | None = None
+    ) -> None:
+        """Navigate to the page with the given key.
+
+        This method handles page transitions, manages navigation history,
+        and triggers lifecycle events (`<<PageUnmount>>`, `<<PageWillMount>>`,
+        `<<PageMount>>`, `<<PageChange>>`).
+
+        Args:
+            key: The identifier of the page to navigate to
+            data: Optional data to pass to the page and include in event payloads
+            replace: If True, replace the current history entry instead of adding a new one
+            _nav: Internal parameter indicating navigation type ('push', 'back', 'forward')
+            _prev: Internal parameter for preserving previous page state
+
+        Raises:
+            NavigationError: If the page with the given key does not exist
+            ValueError: If key is an empty string
+
+        Note:
+            Event payloads include: page, prev_page, prev_data, nav, index,
+            length, can_back, and can_forward.
+        """
+        if not key:
+            raise ValueError("Page key cannot be an empty string")
+        if key not in self._pages:
+            raise NavigationError(f"Page {key} does not exist")
+
+        # Normalize data to empty dict if None
+        if data is None:
+            data = {}
+
+        # Snapshot "previous" BEFORE mutating history
+        if _prev is None:
+            prev_key = self._current
+            prev_data = self._history[self._index][1] if self._index >= 0 else {}
+        else:
+            prev_key, prev_data = _prev
+
+        # Mutate history
+        if replace and 0 <= self._index < len(self._history):
+            self._history[self._index] = (key, data)
+        else:
+            if self._index < len(self._history) - 1:
+                self._history = self._history[:self._index + 1]
+            self._history.append((key, data))
+            self._index += 1
+
+        # Unmount the previous page. On Aqua keep it mapped (stacked behind the
+        # incoming page) so returning to it doesn't remap-flash; elsewhere unmap
+        # it for the cheaper one-page-mapped path.
+        if self._stacked:
+            if self._current is not None and self._current != key:
+                prev_page = self._pages[self._current]
+                prev_page.event_generate('<<PageUnmount>>', when="tail")
+                prev_page._bs_nav_hidden = True
+                prev_page.lower()
+        elif self._current is not None:
+            # Pre-size the target page while the current one is still mounted, so
+            # the swap doesn't briefly collapse the content area (a freshly built
+            # page is otherwise unsized at mount time and the view jumps when it
+            # settles). Only needed for a real swap — the initial mount has
+            # nothing to collapse from, and forcing layout there would serialize
+            # the first render (a visible "slow-motion" build of the page).
+            self._pages[key].update_idletasks()
+            self._pages[self._current].event_generate('<<PageUnmount>>', when="tail")
+            self._pages[self._current].pack_forget()
+
+        # Normalized payload (self-contained snapshot)
+        payload = PageChangeEvent(
+            page=key,
+            prev_page=prev_key,
+            nav=_nav,
+            data=dict(data),
+            prev_data=prev_data,
+            index=self._index,
+            length=len(self._history),
+            can_back=self._index > 0,
+            can_forward=self._index < len(self._history) - 1,
+        )
+
+        # Mount and notify
+        page = self._pages[key]
+        page.event_generate('<<PageWillMount>>', data=payload, when="tail")
+        if self._stacked:
+            page._bs_nav_hidden = False
+            # Map into the shared cell (the first show maps it; later shows are a
+            # no-op reconfigure of an already-mapped page) and lift it above the
+            # stack. Pages are never unmapped again, so a return never remaps.
+            page.grid(row=0, column=0, sticky='nsew')
+            page.lift()
+        else:
+            page.pack(fill='both', expand=True)
+        self._current = key
+        # A theme change that arrived while this page was hidden left its widgets
+        # stale (the walk skips off-screen widgets); recolor the now-visible page.
+        # Deferred to idle so the page is mapped first.
+        def _recolor_shown(p=page):
+            from bootstack.style.style import get_style
+            get_style().apply_theme_walk(p, only_stale=True)
+        self.after_idle(_recolor_shown)
+        self.event_generate('<<PageMount>>', data=payload, when="tail")
+        self.event_generate('<<PageChange>>', data=payload, when="tail")
+
+    def back(self) -> None:
+        """Navigate to the previous page in the navigation history.
+
+        This method moves backward in the history stack if possible.
+        Does nothing if already at the first page.
+        """
+        if self._index > 0:
+            # Snapshot BEFORE changing index
+            prev = (self._current, self._history[self._index][1] if self._index >= 0 else {})
+            self._index -= 1
+            key, data = self._history[self._index]
+            # use replace=True to avoid pushing a new entry
+            # pass _prev to preserve the correct 'previous' snapshot
+            self.navigate(key, data=data, replace=True, _nav='back', _prev=prev)
+
+    def forward(self) -> None:
+        """Navigate to the next page in the navigation history.
+
+        This method moves forward in the history stack if possible.
+        Does nothing if already at the most recent page.
+        """
+        if self._index < len(self._history) - 1:
+            prev = (self._current, self._history[self._index][1] if self._index >= 0 else {})
+            self._index += 1
+            key, data = self._history[self._index]
+            self.navigate(key, data=data, replace=True, _nav='forward', _prev=prev)
+
+    def can_back(self) -> bool:
+        """Check if backward navigation is possible.
+
+        Returns:
+            True if there is a previous page in the history to navigate back to,
+            False otherwise.
+        """
+        return self._index > 0
+
+    def can_forward(self) -> bool:
+        """Check if forward navigation is possible.
+
+        Returns:
+            True if there is a next page in the history to navigate forward to,
+            False otherwise.
+        """
+        return self._index < len(self._history) - 1
+
+    def current(self) -> tuple[str, dict] | None:
+        """Return the current page key and its navigation data.
+
+        Returns:
+            A tuple of (page_key, data_dict) if a page is currently displayed,
+            None if no page is currently displayed.
+        """
+        if self._current is None:
+            return None
+        return self._current, (self._history[self._index][1] if self._index >= 0 else {})
+
+    def item(self, key: str) -> tkinter.Widget:
+        """Get a page by its key.
+
+        Args:
+            key: The identifier of the page to retrieve.
+
+        Returns:
+            The page widget.
+
+        Raises:
+            NavigationError: If no page with the given key exists.
+            ValueError: If key is an empty string.
+        """
+        if not key:
+            raise ValueError("Page key cannot be an empty string")
+        if key not in self._pages:
+            raise NavigationError(f"Page {key} does not exist")
+        return self._pages[key]
+
+    def items(self) -> tuple[tkinter.Widget, ...]:
+        """Get all page widgets in the stack.
+
+        Returns:
+            A tuple of all page widgets managed by this PageStack.
+        """
+        return tuple(self._pages.values())
+
+    def keys(self) -> tuple[str, ...]:
+        """Get all page keys.
+
+        Returns:
+            A tuple of all page keys in the stack.
+        """
+        return tuple(self._pages.keys())
+
+    def configure_item(self, key: str, option: Any = None, **kwargs: Any) -> Any:
+        """Query or configure the page configuration.
+
+        Args:
+            key: The identifier of the page to configure.
+            option: Optional configuration option to query.
+            **kwargs: Configuration options to set on the page widget.
+
+        Returns:
+            If option is provided, returns the value of that option.
+            Otherwise returns the result of configure() if kwargs are provided.
+
+        Raises:
+            NavigationError: If no page with the given key exists.
+            ValueError: If key is an empty string.
+        """
+        if not key:
+            raise ValueError("Page key cannot be an empty string")
+        if key not in self._pages:
+            raise NavigationError(f"Page {key} does not exist")
+        if option is not None:
+            return self._pages[key].cget(option)
+        else:
+            return self._pages[key].configure(**kwargs)
+
+    def on_page_changed(self, callback: Callable) -> str:
+        """Register a callback for `<<PageChange>>` events (fires after every navigation).
+
+        Args:
+            callback: Receives `event.data` with navigation info: `page`, `prev_page`,
+                `nav`, `index`, `length`, `can_back`, `can_forward`.
+
+        Returns:
+            Bind ID — pass to `off_page_changed()` to unsubscribe.
+        """
+        return self.bind('<<PageChange>>', callback, add="+")
+
+    def off_page_changed(self, bind_id: str | None = None) -> None:
+        """Unsubscribe from `<<PageChange>>`.
+
+        Args:
+            bind_id: ID returned by `on_page_changed()`. If None, removes all.
+        """
+        self.unbind("<<PageChange>>", bind_id)
+
+    def on_page_mount(self, callback: Callable) -> str:
+        """Register a callback for `<<PageMount>>` events (fires after a new page is displayed).
+
+        Args:
+            callback: Receives `event.data` with navigation info: `page`,
+                `prev_page`, `nav`, `index`, `length`, `can_back`, `can_forward`.
+
+        Returns:
+            Bind ID — pass to `off_page_mount()` to unsubscribe.
+        """
+        return self.bind('<<PageMount>>', callback, add='+')
+
+    def off_page_mount(self, bind_id: str | None = None) -> None:
+        """Unsubscribe from `<<PageMount>>`.
+
+        Args:
+            bind_id: ID returned by `on_page_mount()`. If None, removes all.
+        """
+        self.unbind('<<PageMount>>', bind_id)