bootstack 0.1.0a1__py3-none-any.whl

bootstack/core/capabilities/bindtags.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from typing import Sequence
+
+
+class BindtagsMixin:
+    """Bindtags helpers (bindtags).
+
+    Bindtags control **the order in which Tk processes bindings** for an event.
+
+    Every widget has a list of bindtags. When an event occurs on a widget, Tk
+    processes bindings in tag order. Each tag may have bindings associated with it.
+
+    Typical default bindtags for a widget look like:
+
+        (widget_pathname, widget_class, toplevel_pathname, "all")
+
+    Practical uses:
+        - Insert a custom tag (e.g. "MyApp") to apply shared behaviors across widgets.
+        - Reorder tags to change precedence (e.g. run class bindings before widget bindings).
+        - Remove a tag to disable a layer of default behavior (use with care).
+
+    Notes:
+        - Bindtags affect event dispatch only; they do not change focus or grab behavior.
+        - Misordering tags can break default widget behaviors (Tab traversal, selection,
+          text editing, etc.), so keep changes minimal and well-scoped.
+    """
+
+    def bindtags(self, tags: Sequence[str] | None = None) -> tuple[str, ...]:
+        """Get or set the bindtags for this widget.
+
+        Args:
+            tags: The bindtags to set. If None, returns the current bindtags.
+                Tags are processed in order when dispatching events.
+
+        Returns:
+            The current bindtags as a tuple.
+        """
+        # Tkinter's `bindtags()` returns a tuple and accepts a sequence for setting.
+        if tags is None:
+            return super().bindtags()  # type: ignore[misc]
+        return super().bindtags(tags)  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Convenience helpers (optional)
+    # -------------------------------------------------------------------------
+
+    def bindtags_prepend(self, tag: str) -> tuple[str, ...]:
+        """Prepend a tag to the bindtags list.
+
+        This increases the tag's priority (it will be processed earlier).
+
+        Args:
+            tag: Tag name to prepend.
+
+        Returns:
+            The updated bindtags tuple.
+        """
+        current = list(self.bindtags())
+        if tag not in current:
+            current.insert(0, tag)
+            self.bindtags(current)
+        return tuple(current)
+
+    def bindtags_append(self, tag: str) -> tuple[str, ...]:
+        """Append a tag to the bindtags list.
+
+        This decreases the tag's priority (it will be processed later).
+
+        Args:
+            tag: Tag name to append.
+
+        Returns:
+            The updated bindtags tuple.
+        """
+        current = list(self.bindtags())
+        if tag not in current:
+            current.append(tag)
+            self.bindtags(current)
+        return tuple(current)
+
+    def bindtags_remove(self, tag: str) -> tuple[str, ...]:
+        """Remove a tag from the bindtags list.
+
+        Args:
+            tag: Tag name to remove.
+
+        Returns:
+            The updated bindtags tuple.
+        """
+        current = [t for t in self.bindtags() if t != tag]
+        self.bindtags(current)
+        return tuple(current)
+
+    def bindtags_replace(self, old: str, new: str) -> tuple[str, ...]:
+        """Replace a bindtag with another tag.
+
+        Args:
+            old: Existing tag name.
+            new: Replacement tag name.
+
+        Returns:
+            The updated bindtags tuple.
+        """
+        current = list(self.bindtags())
+        try:
+            idx = current.index(old)
+        except ValueError:
+            return tuple(current)
+        current[idx] = new
+        self.bindtags(current)
+        return tuple(current)

bootstack/core/capabilities/busy.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+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: Any) -> 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: Busy options forwarded to Tk. Common options include `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: Any) -> 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: Busy options forwarded to Tk.
+
+        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,88 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+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 keyword arguments.
+    """
+
+    def clipboard_clear(self, **kw: Any) -> None:
+        """Clear the clipboard on the target display.
+
+        This removes all data from the clipboard for the specified display.
+
+        Args:
+            **kw: Clipboard options forwarded to Tk. Common options include:
+                - displayof: A widget/window whose display should be targeted.
+                  (Rarely needed in typical single-display apps.)
+        """
+        return super().clipboard_clear(**kw)  # type: ignore[misc]
+
+    def clipboard_append(self, string: str, **kw: Any) -> None:
+        """Append text to the clipboard.
+
+        Appends *string* to the clipboard. If you want to replace clipboard contents,
+        call `clipboard_clear()` first and then `clipboard_append()`.
+
+        Args:
+            string: Text to append to the clipboard.
+            **kw: Clipboard options forwarded to Tk. Common options include:
+                - displayof: Target display for the clipboard.
+                - type: Clipboard type name (platform/window-system dependent).
+                - format: Data format name (platform/window-system dependent).
+
+        Example:
+            self.clipboard_clear()
+            self.clipboard_append("Hello, world!")
+        """
+        return super().clipboard_append(string, **kw)  # type: ignore[misc]
+
+    def clipboard_get(self, **kw: Any) -> str:
+        """Return clipboard contents as text.
+
+        Args:
+            **kw: Clipboard options forwarded to Tk. Common options include:
+                - displayof: Target display for the clipboard.
+                - type: Clipboard type name (platform/window-system dependent).
+
+        Returns:
+            The clipboard contents as a string.
+
+        Raises:
+            tkinter.TclError: If the clipboard is empty or does not contain
+                data that can be converted to the requested type.
+        """
+        return super().clipboard_get(**kw)  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Convenience helpers (optional): common "text clipboard" patterns
+    # -------------------------------------------------------------------------
+
+    def clipboard_set(self, text: str, **kw: Any) -> None:
+        """Replace clipboard contents with *text*.
+
+        This is a convenience wrapper for:
+
+            clipboard_clear(...)
+            clipboard_append(text, ...)
+
+        Args:
+            text: Text to set on the clipboard.
+            **kw: Clipboard options forwarded to `clipboard_clear` / `clipboard_append`.
+        """
+        self.clipboard_clear(**kw)
+        self.clipboard_append(text, **kw)
+
+    def clipboard_get_text(self, **kw: Any) -> 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,188 @@
+"""Grid geometry manager capabilities mixin for bootstack widgets."""
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+
+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.
+        - `rowconfigure()` / `columnconfigure()` set sizing behavior (weight/minsize/pad).
+        - `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: Any) -> Self:
+        """Position this widget using the grid geometry manager.
+
+        Args:
+            cnf: Optional dict of grid options.
+            **kw: Grid options. Common options include:
+                - row, column: Cell coordinates (0-based).
+                - rowspan, columnspan: Span across multiple cells.
+                - sticky: How the widget expands within its cell (e.g. "nsew").
+                - padx, pady: External padding around the widget.
+                - ipadx, ipady: Internal padding inside the widget.
+
+        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: Any) -> Self:
+        """Alias for `grid()`.
+
+        Args:
+            cnf: Optional dict of grid options.
+            **kw: Grid options (see `grid`).
+
+        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: Any) -> None:
+        """Configure sizing behavior for a grid row in this container.
+
+        Common options:
+            - weight: How extra space is distributed (0 means no expansion).
+            - minsize: Minimum row size in pixels.
+            - pad: Extra padding added to the row.
+
+        Args:
+            index: Row index (0-based).
+            cnf: Optional dict of configuration options.
+            **kw: Row configuration options.
+        """
+        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: Any) -> None:
+        """Configure sizing behavior for a grid column in this container.
+
+        Common options:
+            - weight: How extra space is distributed (0 means no expansion).
+            - minsize: Minimum column size in pixels.
+            - pad: Extra padding added to the column.
+
+        Args:
+            index: Column index (0-based).
+            cnf: Optional dict of configuration options.
+            **kw: Column configuration options.
+        """
+        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]