bootstack 0.1.0__py3-none-any.whl

bootstack/_core/capabilities/busy.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+from typing_extensions import TypedDict
+
+if TYPE_CHECKING:
+    from typing_extensions import Unpack
+
+
+class BusyKwargs(TypedDict, total=False):
+    """Keyword options accepted by busy-mode operations."""
+    cursor: str
+    """Cursor to display while busy mode is active (e.g., `'wait'`, `'watch'`)."""
+
+
+class BusyMixin:
+    """Busy (input-blocking) helpers (busy).
+
+    Tk's *busy* facility blocks pointer events from reaching a widget/window by
+    placing an input-only window above it. This is typically used to prevent
+    user interaction during a long-running operation (e.g., loading, saving).
+
+    Notes:
+        - Busy blocks pointer events; it does not guarantee keyboard events are blocked.
+        - Always release busy state in a `finally:` block (or use a context manager).
+    """
+
+    def busy_hold(self, **kw: Unpack[BusyKwargs]) -> None:
+        """Activate busy mode for this widget/window.
+
+        While busy is active, pointer events are intercepted so the user cannot
+        interact with the target window (and typically its children).
+
+        Args:
+            **kw: See `BusyKwargs`. Use `cursor` to set the busy cursor.
+        """
+        return super().busy_hold(**kw)  # type: ignore[misc]
+
+    def busy_forget(self) -> None:
+        """Deactivate busy mode for this widget/window."""
+        return super().busy_forget()  # type: ignore[misc]
+
+    def busy_status(self) -> bool:
+        """Return True if this widget/window is currently in busy mode."""
+        return bool(super().busy_status())  # type: ignore[misc]
+
+    def busy_configure(self, **kw: Unpack[BusyKwargs]) -> Any:
+        """Query or configure busy options for this widget/window.
+
+        With no options, returns configuration information (format depends on Tk).
+        With options provided, updates the busy configuration.
+
+        Args:
+            **kw: See `BusyKwargs`.
+
+        Returns:
+            The raw Tk result for the configure query/set.
+        """
+        return super().busy_configure(**kw)  # type: ignore[misc]
+
+    def busy_cget(self, option: str) -> Any:
+        """Return the current value of a single busy option.
+
+        Args:
+            option: Option name (e.g., `'cursor'` or `'-cursor'`).
+
+        Returns:
+            The option value.
+        """
+        opt = option if option.startswith("-") else f"-{option}"
+        return super().busy_cget(opt)  # type: ignore[misc]

bootstack/_core/capabilities/clipboard.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+from typing_extensions import TypedDict
+
+if TYPE_CHECKING:
+    from typing_extensions import Unpack
+
+
+class ClipboardKwargs(TypedDict, total=False):
+    """Keyword options accepted by clipboard operations."""
+    displayof: Any
+    """Widget or window whose display to target. Omit for the main application display."""
+    type: str
+    """Clipboard type name (e.g., `'STRING'`, `'UTF8_STRING'`). Platform-dependent."""
+    format: str
+    """Data format for representing selection data to the X server (e.g., `'STRING'`). Platform-dependent."""
+
+
+class ClipboardMixin:
+    """Clipboard helpers (clipboard).
+
+    Tk's `clipboard` command provides access to the system (or Tk-managed) clipboard.
+    Tkinter exposes this via the `clipboard_*` methods.
+
+    Notes:
+        - Clipboard behavior can vary by platform and window system.
+        - Most apps only need text clipboard operations (clear/append/get).
+        - For advanced cases (multiple clipboard types, non-text formats), Tk supports
+          additional options passed via `ClipboardKwargs`.
+    """
+
+    def clipboard_clear(self, **kw: Unpack[ClipboardKwargs]) -> None:
+        """Clear the clipboard on the target display.
+
+        This removes all data from the clipboard for the specified display.
+
+        Args:
+            **kw: See `ClipboardKwargs`. The `displayof` key targets a specific display.
+        """
+        return super().clipboard_clear(**kw)  # type: ignore[misc]
+
+    def clipboard_append(self, string: str, **kw: Unpack[ClipboardKwargs]) -> None:
+        """Append text to the clipboard.
+
+        Appends *string* to the clipboard. To replace clipboard contents,
+        call `clipboard_clear()` first.
+
+        Args:
+            string: Text to append to the clipboard.
+            **kw: See `ClipboardKwargs`. Use `type` and `format` for non-text data.
+        """
+        return super().clipboard_append(string, **kw)  # type: ignore[misc]
+
+    def clipboard_get(self, **kw: Unpack[ClipboardKwargs]) -> str:
+        """Return clipboard contents as text.
+
+        Args:
+            **kw: See `ClipboardKwargs`. Use `type="UTF8_STRING"` to retrieve UTF-8 data.
+
+        Returns:
+            The clipboard contents as a string.
+
+        Raises:
+            tkinter.TclError: If the clipboard is empty or cannot be converted to the
+                requested type.
+        """
+        return super().clipboard_get(**kw)  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Convenience helpers
+    # -------------------------------------------------------------------------
+
+    def clipboard_set(self, text: str, **kw: Unpack[ClipboardKwargs]) -> None:
+        """Replace clipboard contents with *text*.
+
+        Convenience wrapper for `clipboard_clear()` + `clipboard_append()`.
+
+        Args:
+            text: Text to set on the clipboard.
+            **kw: See `ClipboardKwargs`. Forwarded to both clear and append.
+        """
+        self.clipboard_clear(**kw)
+        self.clipboard_append(text, **kw)
+
+    def clipboard_get_text(self, **kw: Unpack[ClipboardKwargs]) -> str:
+        """Return clipboard contents as text (alias for `clipboard_get`)."""
+        return self.clipboard_get(**kw)

bootstack/_core/capabilities/focus.py

@@ -0,0 +1,118 @@
+"""Focus management capabilities mixin for bootstack widgets."""
+from __future__ import annotations
+
+from typing import Any
+
+
+class FocusMixin:
+    """Keyboard focus helpers (focus).
+
+    Tk's *input focus* determines which widget receives key press/release events.
+    Focus is typically managed by the window manager at the top-level window level,
+    and then by the application within the top-level.
+
+    Tk remembers the most recent focused descendant for each top-level. When the
+    window manager gives focus to a top-level, Tk redirects it to that remembered
+    widget automatically.
+
+    Notes:
+        - Prefer `focus_set()` for normal use.
+        - `focus_force()` can steal focus and should be used sparingly.
+        - Tab/Shift-Tab traversal typically uses `tk_focusNext()` / `tk_focusPrev()`.
+    """
+
+    # -------------------------------------------------------------------------
+    # Core focus operations
+    # -------------------------------------------------------------------------
+
+    def focus_get(self) -> Any:
+        """Return the widget in this application that currently has focus.
+
+        This queries the focus window on the display containing the application's
+        main window. If no window in this application has focus on that display,
+        the return value is None / empty (depending on Tkinter/Tk behavior).
+
+        Returns:
+            The focused widget instance, or None if no widget in this application
+            currently has focus on the relevant display.
+        """
+        return super().focus_get()  # type: ignore[misc]
+
+    def focus_set(self, *, visual_focus: bool = False) -> None:
+        """Request focus for this widget.
+
+        If this application currently has the focus on the widget's display, this
+        resets the focus for that display to this widget. Otherwise, Tk remembers
+        this widget as the focus for its top-level and will redirect focus to it
+        the next time the top-level receives focus.
+
+        Args:
+            visual_focus: If True, show focus ring as if focused via keyboard
+                (Tab navigation). Default is False, which shows no focus ring
+                for programmatic focus. Useful for validation errors where you
+                want to draw attention to a field.
+        """
+        return super().focus_set(visual_focus=visual_focus)  # type: ignore[misc]
+
+    def focus_force(self, *, visual_focus: bool = False) -> None:
+        """Force focus to this widget (use sparingly).
+
+        This attempts to set the focus for the widget's display even if the
+        application does not currently have the input focus for that display.
+        In normal usage, applications should not claim focus; they should wait
+        for the window manager/user to give it focus.
+
+        Args:
+            visual_focus: If True, show focus ring as if focused via keyboard
+                (Tab navigation). Default is False, which shows no focus ring
+                for programmatic focus.
+        """
+        return super().focus_force(visual_focus=visual_focus)  # type: ignore[misc]
+
+    def focus_displayof(self) -> Any:
+        """Return the focused widget for the display containing this widget.
+
+        If the focus window for this widget's display is not in this application,
+        the return value is None / empty (depending on Tkinter/Tk behavior).
+
+        Returns:
+            The focused widget instance for this display, or None.
+        """
+        return super().focus_displayof()  # type: ignore[misc]
+
+    def focus_lastfor(self) -> Any:
+        """Return the most recent focused widget within this widget's top-level.
+
+        Tk tracks the most recent focus window for each top-level. This returns
+        the widget that will receive focus the next time the top-level gets focus
+        from the window manager. If none has ever had focus (or it was deleted),
+        Tk returns the top-level itself.
+
+        Returns:
+            The most recent focused widget in the same top-level, or the top-level.
+        """
+        return super().focus_lastfor()  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Focus traversal (Tab order utilities)
+    # -------------------------------------------------------------------------
+
+    def tk_focusNext(self) -> Any:
+        """Return the next widget in the focus traversal order.
+
+        This is used by default bindings for Tab traversal in many Tk widgets.
+
+        Returns:
+            The next widget in focus order, or this widget if no other is eligible.
+        """
+        return super().tk_focusNext()  # type: ignore[misc]
+
+    def tk_focusPrev(self) -> Any:
+        """Return the previous widget in the focus traversal order.
+
+        This is used by default bindings for Shift-Tab traversal in many Tk widgets.
+
+        Returns:
+            The previous widget in focus order, or this widget if no other is eligible.
+        """
+        return super().tk_focusPrev()  # type: ignore[misc]

bootstack/_core/capabilities/grab.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class GrabMixin:
+    """Pointer/keyboard grab helpers (grab).
+
+    A *grab* confines mouse and keyboard events to a particular widget subtree.
+
+    When a grab is active:
+      - Pointer events are delivered only to the grab window and its descendants.
+      - Keyboard events are also directed to the grab window (effectively focusing input).
+      - This is the foundation for *modal* interactions (e.g., modal dialogs).
+
+    Tk supports two kinds of grabs:
+      - **Local (application) grab**: confines events within the current Tk application.
+      - **Global grab**: confines events at the window system level (more intrusive).
+
+    Notes:
+        - Grabs should be released when you are done (typically in a `finally:` block).
+        - Global grabs can make the entire desktop feel “stuck” if misused; prefer local grabs
+          unless you specifically need global behavior.
+        - A grab does not automatically make a window modal; typical modal patterns also:
+          `transient(parent)`, `focus_set()`, and `wait_window()` / `wait_visibility()`.
+    """
+
+    def grab_set(self) -> None:
+        """Set a local (application) grab on this widget.
+
+        With a local grab, events are confined within the current Tk application.
+        This is the preferred grab type for modal dialogs inside an application.
+        """
+        return super().grab_set()  # type: ignore[misc]
+
+    def grab_set_global(self) -> None:
+        """Set a global grab on this widget.
+
+        A global grab confines events at the window system level. This is more
+        intrusive than a local grab and should be used with care.
+        """
+        return super().grab_set_global()  # type: ignore[misc]
+
+    def grab_release(self) -> None:
+        """Release a grab held by this widget (if any)."""
+        return super().grab_release()  # type: ignore[misc]
+
+    def grab_current(self) -> Any:
+        """Return the widget in this application that currently holds the grab.
+
+        Returns:
+            The widget instance that currently holds the grab, or None if
+                no grab is held by this application.
+        """
+        return super().grab_current()  # type: ignore[misc]
+
+    def grab_status(self) -> str | None:
+        """Return the grab status for this widget.
+
+        Returns:
+            The grab status: "local" if this widget holds a local grab,
+                "global" if this widget holds a global grab, or None if
+                this widget does not hold the grab.
+        """
+        return super().grab_status()  # type: ignore[misc]

bootstack/_core/capabilities/grid.py

@@ -0,0 +1,211 @@
+"""Grid geometry manager capabilities mixin for bootstack widgets."""
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+from typing_extensions import TypedDict
+
+if TYPE_CHECKING:
+    from typing_extensions import Self, Unpack
+
+
+class GridKwargs(TypedDict, total=False):
+    """Keyword options for `grid()` and `grid_configure()`."""
+    row: int
+    """Row index (0-based). Defaults to the next available row."""
+    column: int
+    """Column index (0-based). Defaults to 0."""
+    rowspan: int
+    """Number of rows to span. Defaults to 1."""
+    columnspan: int
+    """Number of columns to span. Defaults to 1."""
+    sticky: str
+    """How the widget expands within its cell (e.g., `'nsew'`, `'ew'`, `'n'`). Defaults to `''`."""
+    padx: int | tuple[int, int]
+    """Horizontal external padding in pixels. A tuple sets (left, right) independently."""
+    pady: int | tuple[int, int]
+    """Vertical external padding in pixels. A tuple sets (top, bottom) independently."""
+    ipadx: int
+    """Horizontal internal padding in pixels."""
+    ipady: int
+    """Vertical internal padding in pixels."""
+    in_: Any
+    """Parent widget to grid into (rarely needed — defaults to the widget's own master)."""
+
+
+class GridRowColumnKwargs(TypedDict, total=False):
+    """Keyword options for `grid_rowconfigure()` and `grid_columnconfigure()`."""
+    weight: int
+    """How extra space is distributed among rows/columns. 0 means no expansion. Defaults to 0."""
+    minsize: int
+    """Minimum row/column size in pixels. Defaults to 0."""
+    pad: int
+    """Extra padding added to the row/column in pixels. Defaults to 0."""
+    uniform: str
+    """Group name — rows/columns sharing a group are given equal size."""
+
+
+class GridMixin:
+    """Grid geometry manager helpers (grid).
+
+    Tk's `grid` geometry manager arranges widgets in a table of rows and columns.
+
+    In bootstack v2 you may prefer higher-level layout containers (e.g. `GridFrame`)
+    for most UI layout. This mixin documents the underlying Tkinter `grid_*` API
+    as an escape hatch and for interoperability with existing Tk code.
+
+    Notes:
+        - `grid()` attaches a widget to a parent container that is using grid.
+        - `grid_rowconfigure()` / `grid_columnconfigure()` set sizing behavior.
+        - `grid_propagate(False)` prevents a container from resizing to fit its children.
+        - If the parent has a `_on_child_grid` hook (e.g. GridFrame), layout defaults
+          are applied automatically.
+    """
+
+    # -------------------------------------------------------------------------
+    # Core widget methods
+    # -------------------------------------------------------------------------
+
+    def grid(self, cnf: dict[str, Any] | None = None, **kw: Unpack[GridKwargs]) -> Self:
+        """Position this widget using the grid geometry manager.
+
+        Args:
+            cnf: Optional dict of grid options (same keys as `GridKwargs`).
+            **kw: See `GridKwargs`.
+
+        Returns:
+            Self for method chaining.
+        """
+        options = cnf or {}
+        options.update(kw)
+
+        parent = self.master  # type: ignore[attr-defined]
+        if hasattr(parent, '_on_child_grid'):
+            parent._on_child_grid(self, **options)
+        else:
+            super().grid(**options)  # type: ignore[misc]
+        return self  # type: ignore[return-value]
+
+    def grid_configure(self, cnf: dict[str, Any] | None = None, **kw: Unpack[GridKwargs]) -> Self:
+        """Alias for `grid()`.
+
+        Args:
+            cnf: Optional dict of grid options.
+            **kw: See `GridKwargs`.
+
+        Returns:
+            Self for method chaining.
+        """
+        return self.grid(cnf, **kw)
+
+    def grid_forget(self) -> Self:
+        """Unmap this widget and forget its grid configuration.
+
+        The widget is removed from the layout, and its previous grid options
+        are discarded.
+
+        Returns:
+            Self for method chaining.
+        """
+        parent = self.master  # type: ignore[attr-defined]
+        if hasattr(parent, '_on_child_grid_forget'):
+            parent._on_child_grid_forget(self)
+        else:
+            super().grid_forget()  # type: ignore[misc]
+        return self  # type: ignore[return-value]
+
+    def grid_remove(self) -> Self:
+        """Unmap this widget but remember its grid configuration.
+
+        Use `grid()` with no args to restore it to its previous grid location.
+
+        Returns:
+            Self for method chaining.
+        """
+        parent = self.master  # type: ignore[attr-defined]
+        if hasattr(parent, '_on_child_grid_remove'):
+            parent._on_child_grid_remove(self)
+        else:
+            super().grid_remove()  # type: ignore[misc]
+        return self  # type: ignore[return-value]
+
+    def grid_info(self) -> dict[str, Any]:
+        """Return this widget's current grid configuration.
+
+        Returns:
+            A dict containing the current grid options for this widget
+            (row, column, sticky, padx, pady, etc.).
+        """
+        return super().grid_info()  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Container methods (applied to the grid parent container)
+    # -------------------------------------------------------------------------
+
+    def grid_propagate(self, flag: bool | None = None) -> bool | None:
+        """Get or set grid geometry propagation for this container.
+
+        When propagation is enabled (default), the container may resize itself
+        to fit the size requests of its children.
+
+        Args:
+            flag: True/False to enable/disable propagation. If None, acts as a getter.
+
+        Returns:
+            When queried, returns the current propagation flag. When set, returns None.
+        """
+        return super().grid_propagate(flag)  # type: ignore[misc]
+
+    def grid_rowconfigure(self, index: int, cnf: dict[str, Any] | None = None, **kw: Unpack[GridRowColumnKwargs]) -> None:
+        """Configure sizing behavior for a grid row in this container.
+
+        Args:
+            index: Row index (0-based).
+            cnf: Optional dict of configuration options (same keys as `GridRowColumnKwargs`).
+            **kw: See `GridRowColumnKwargs`.
+        """
+        if cnf is None:
+            return super().grid_rowconfigure(index, **kw)  # type: ignore[misc]
+        return super().grid_rowconfigure(index, cnf, **kw)  # type: ignore[misc]
+
+    def grid_columnconfigure(self, index: int, cnf: dict[str, Any] | None = None, **kw: Unpack[GridRowColumnKwargs]) -> None:
+        """Configure sizing behavior for a grid column in this container.
+
+        Args:
+            index: Column index (0-based).
+            cnf: Optional dict of configuration options (same keys as `GridRowColumnKwargs`).
+            **kw: See `GridRowColumnKwargs`.
+        """
+        if cnf is None:
+            return super().grid_columnconfigure(index, **kw)  # type: ignore[misc]
+        return super().grid_columnconfigure(index, cnf, **kw)  # type: ignore[misc]
+
+    def grid_size(self) -> tuple[int, int]:
+        """Return the grid size (columns, rows) used in this container.
+
+        Returns:
+            A tuple (num_columns, num_rows).
+        """
+        return super().grid_size()  # type: ignore[misc]
+
+    def grid_slaves(
+            self,
+            row: int | None = None,
+            column: int | None = None,
+    ) -> list[Any]:
+        """Return the widgets managed by grid in this container.
+
+        Args:
+            row: If provided, return only widgets in the given row.
+            column: If provided, return only widgets in the given column.
+
+        Returns:
+            A list of child widgets managed by grid.
+        """
+        if row is None and column is None:
+            return super().grid_slaves()  # type: ignore[misc]
+        if row is None:
+            return super().grid_slaves(column=column)  # type: ignore[misc]
+        if column is None:
+            return super().grid_slaves(row=row)  # type: ignore[misc]
+        return super().grid_slaves(row=row, column=column)  # type: ignore[misc]