bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/togglegroup.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import tkinter
+from typing import overload, Any, Callable, Literal, TYPE_CHECKING
+
+from bootstack.widgets._impl.composites.togglegroup import ToggleGroup as _InternalToggleGroup
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets._core.selection_group import SelectionGroupMixin
+from bootstack.widgets._core.options import normalize_options, option_display
+from bootstack.widgets._core.events import register_widget_events
+from bootstack.events import Subscription, ChangeEvent
+from bootstack.streams import Stream
+from bootstack.widgets.types import AccentToken, Event, Option, Orient, ButtonVariant
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+_TOGGLEGROUP_EVENTS: dict[str, str] = {
+    "change": "<<Change>>",
+}
+
+
+class ToggleGroup(SelectionGroupMixin, PublicWidgetBase):
+    """A group of toggle buttons — single-select or multi-select.
+
+    Options are supplied at construction via `options=` and can be added
+    at runtime with `add()`. In `'single'` mode exactly one button is
+    active at a time; in `'multi'` mode any combination can be active.
+
+    Args:
+        options: Choices for the group. Each item is a plain string (text and
+            value are the same), a `(text, value)` tuple, or a
+            `{'text': ..., 'value': ...}` dict — e.g. `["Grid", "List"]` or
+            `[("Grid view", "grid"), ("List view", "list")]`. A dict option may
+            also carry `'icon'` (a glyph rendered beside the label) and
+            `'disabled'` (when `True` the option is dimmed and cannot be
+            selected); any other keys ride along as carried data on `selection`.
+            An option with an `'icon'` and no text — e.g.
+            `{'icon': 'grid', 'value': 'grid'}` — renders as an icon-only button.
+        mode: Selection behavior. `'single'` (default) enforces mutual
+            exclusivity like a radio group; `'multi'` allows any number
+            of buttons to be active simultaneously.
+        signal: Reactive `Signal` holding the selected value(s). In
+            `'single'` mode the signal value is a `str`; in `'multi'`
+            mode it is a `set[str]`. When provided, `value=` is ignored
+            — seed the Signal directly.
+        value: Initial selection. A `str` for `'single'` mode or a
+            `set[str]` for `'multi'` mode. Ignored when `signal=` is
+            passed.
+        orient: Layout direction. Default `'horizontal'`.
+        accent: Accent token applied to all buttons.
+        variant: Button style variant. Default `'solid'`.
+        disabled: If `True`, all buttons are non-interactive and dimmed.
+            Defaults to `False`.
+        localize: Whether option labels are translated through the catalog —
+            `True`, `False`, or `'auto'` (translate when a translation is
+            registered, otherwise show the literal). Defaults to the app's
+            `localize_mode`. Set `False` to keep proper nouns untranslated;
+            override a single option with its `localize` key.
+        parent: Explicit parent widget. If omitted, the current
+            context-stack container is used.
+        **kwargs: Layout placement options applied by the parent container —
+            `fill`, `expand`, `anchor`, `margin`, `row`, `column`, `sticky`.
+            See :doc:`/tasks/layout`.
+    """
+
+    def __init__(
+        self,
+        options: list[Option] | None = None,
+        *,
+        mode: Literal["single", "multi"] = "single",
+        signal: "Signal | None" = None,
+        value: Any = None,
+        orient: Orient = "horizontal",
+        accent: AccentToken | str | None = None,
+        variant: ButtonVariant = "default",
+        disabled: bool = False,
+        localize: bool | Literal['auto'] | None = None,
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        self._localize = localize
+        self._parent = self._resolve_parent(parent)
+        layout_kw = self._split_layout_kwargs(kwargs)
+
+        tk_master = self._parent._child_master() if self._parent else None
+
+        internal_kwargs: dict[str, Any] = {
+            "mode": mode,
+            "orient": orient,
+        }
+        if signal is not None:
+            internal_kwargs["signal"] = signal
+        if value is not None:
+            internal_kwargs["value"] = value
+        if accent is not None:
+            internal_kwargs["accent"] = accent
+        if variant is not None:
+            internal_kwargs["variant"] = variant
+        if disabled:
+            internal_kwargs["state"] = "disabled"
+
+        self._internal = _InternalToggleGroup(tk_master, **internal_kwargs)
+
+        # Populate options passed at construction; keep the records (the data
+        # bag) so `selection` can return each option's full dict.
+        records = normalize_options(options)
+        self._set_option_records(records)
+        for record in records:
+            icon, disabled = option_display(record)
+            add_kwargs, _ = self._option_render(icon, disabled, record.text)
+            item_localize = self._resolve_localize(record)
+            if item_localize is not None:
+                add_kwargs["localize"] = item_localize
+            self._internal.add(text=record.text, value=record.value, **add_kwargs)
+
+        # Trace signal → <<Change>> for consistent Subscription-based on_change().
+        self._prev_value = self._internal.signal()
+
+        def _on_value_change(new_value: Any) -> None:
+            try:
+                prev, self._prev_value = self._prev_value, new_value
+                self._internal.event_generate(
+                    "<<Change>>", data=ChangeEvent(value=new_value, prev_value=prev)
+                )
+            except tkinter.TclError:
+                pass
+
+        self._trace_id = self._internal.signal.subscribe(_on_value_change)
+        self._attach_to_parent(layout_kw)
+
+    # ----- Properties -----
+
+    @property
+    def value(self) -> Any:
+        """The current selection. A `str` in single mode, `set[str]` in multi mode."""
+        return self._internal.get()
+
+    @value.setter
+    def value(self, v: Any) -> None:
+        self._internal.set(v)
+
+    @property
+    def text(self) -> str | set[str] | None:
+        """The label(s) of the selected option(s) — the display complement of `value`.
+
+        In single mode, the selected option's label (or `None` if nothing is
+        selected). In multi mode, a `set` of the selected options' labels.
+        Read-only.
+        """
+        value = self._internal.get()
+        if isinstance(value, set):
+            return {t for v in value if (t := self._internal.text_for(v)) is not None}
+        return self._internal.text_for(value)
+
+    @property
+    def selection(self) -> dict | list[dict] | None:
+        """The selected option(s) as full record dicts — the data bag.
+
+        In single mode, the selected option's `{text, value, ...extras}` dict
+        (or `None`). In multi mode, a `list` of those dicts. Read-only.
+        """
+        value = self._internal.get()
+        if isinstance(value, set):
+            return [d for v in value if (d := self._record_dict_for(v)) is not None]
+        return self._record_dict_for(value)
+
+    @property
+    def disabled(self) -> bool:
+        """Whether all buttons in the group are non-interactive."""
+        return self._internal._state == "disabled"
+
+    @disabled.setter
+    def disabled(self, v: bool) -> None:
+        self._internal.configure(state="disabled" if v else "normal")
+
+    # ----- Methods -----
+
+    def add(
+        self,
+        label: str,
+        value: Any | None = None,
+        *,
+        icon: Any = None,
+        disabled: bool = False,
+        localize: bool | Literal['auto'] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Add a toggle button at runtime.
+
+        Args:
+            label: Display text. Pass `''` with an `icon` for an icon-only button.
+            value: Value this button represents. Defaults to `label`.
+            icon: Optional icon spec rendered beside the label (alone when
+                `label` is blank).
+            disabled: If `True`, the option is dimmed and cannot be selected.
+            localize: Translation mode for this option's label, overriding the
+                group's `localize=`. Defaults to the group setting.
+        """
+        resolved = value if value is not None else label
+        add_kwargs, extras = self._option_render(icon, disabled, label)
+        item_localize = self._resolve_localize(override=localize)
+        if item_localize is not None:
+            add_kwargs["localize"] = item_localize
+        if localize is not None:
+            extras["localize"] = localize
+        self._internal.add(text=label, value=resolved, **add_kwargs, **kwargs)
+        self._add_option_record(label, resolved, extras)
+
+    # ----- Event shorthands -----
+
+    @overload
+    def on_change(self) -> Stream: ...
+    @overload
+    def on_change(self, handler: Callable[[ChangeEvent], Any]) -> Subscription: ...
+    def on_change(self, handler: Callable[[ChangeEvent], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired whenever the selection changes.
+
+        Args:
+            handler: Called with a :class:`~bootstack.events.ChangeEvent`; the
+                current value is also available via `group.value`. Omit to get
+                a composable :class:`~bootstack.streams.Stream` instead.
+
+        Returns:
+            A cancellable :class:`~bootstack.events.Subscription` when a
+            handler is given, otherwise a :class:`~bootstack.streams.Stream`.
+        """
+        return self.on("change", handler)
+
+
+register_widget_events(ToggleGroup, _TOGGLEGROUP_EVENTS)

bootstack/widgets/toolbar.py

@@ -0,0 +1,347 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from bootstack.errors import BootstackError
+from bootstack.widgets._impl.composites.toolbar import Toolbar as _InternalToolbar
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets.types import AccentToken, WidgetDensity, SurfaceToken, ButtonVariant
+
+if TYPE_CHECKING:
+    from bootstack.widgets._impl.composites.menu.model import MenuGroup
+    from bootstack.widgets.button import Button
+    from bootstack.widgets.label import Label
+
+
+class Toolbar(PublicWidgetBase):
+    """A horizontal strip of buttons, labels, and other widgets.
+
+    The toolbar holds an app's commands — buttons, a search box, a theme toggle.
+    Items are added left-to-right via `add_button()`, `add_label()`,
+    `add_divider()`, `add_spacer()`, and `add_widget()`. Call `add_spacer()` to
+    push subsequent items to the right side.
+
+    Use this widget directly to build a standalone toolbar or a custom titlebar.
+
+    Args:
+        button_variant: Default variant applied to every button added via
+            `add_button()`. Default `'ghost'`.
+        density: Size of toolbar items. Default `'default'`.
+        surface: Background surface token. Defaults to `None` — the toolbar
+            inherits the base content surface (it blends into its parent). Pass
+            `'chrome'` (or another token) to tint the bar explicitly.
+        padding: Inner padding in pixels — an int (all sides) or a
+            `(horizontal, vertical)` tuple. Defaults to `3` for default density
+            and `(3, 1)` for compact.
+        show_border: If `True`, draws a border around the toolbar frame.
+            Default `False`.
+        show_window_controls: If `True`, adds minimize, maximize, and close
+            buttons to the right side. Default `False`.
+        draggable: If `True`, clicking and dragging the toolbar repositions
+            the window. Automatically enabled when `show_window_controls=True`.
+            Default `False`.
+        parent: Override the context-stack parent.
+        **kwargs: Layout placement options applied by the parent container —
+            `fill`, `expand`, `anchor`, `margin`, `row`, `column`, `sticky`.
+            See :doc:`/tasks/layout`.
+    """
+
+    def __init__(
+        self,
+        *,
+        button_variant: ButtonVariant = "ghost",
+        density: WidgetDensity = "default",
+        surface: SurfaceToken | str | None = None,
+        padding: int | tuple[int, int] | None = None,
+        show_border: bool = False,
+        show_window_controls: bool = False,
+        draggable: bool = False,
+        parent: Any = None,
+        _toolbar: Any = None,
+        _host: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        # The chrome host (App/Window/AppShell) that owns this bar, when built via
+        # `host.add_toolbar()`. Lets shell-aware conveniences (add_sidebar_toggle)
+        # reach the sidebar; None for a standalone bar.
+        self._host = _host
+        if _toolbar is not None:
+            # Adoption: wrap a pre-built internal toolbar (e.g. an AppShell's
+            # titlebar band, which already carries its window controls + drag).
+            self._internal = _toolbar
+            self._parent = None
+            return
+
+        self._parent = self._resolve_parent(parent)
+        layout_kw = self._split_layout_kwargs(kwargs)
+        tk_master = self._parent._child_master() if self._parent else None
+
+        internal_kwargs: dict[str, Any] = {
+            "button_variant": button_variant,
+            "density": density,
+            "show_window_controls": show_window_controls,
+            "draggable": draggable,
+            "show_border": show_border,
+        }
+        if surface is not None:
+            internal_kwargs["surface"] = surface
+        if padding is not None:
+            internal_kwargs["padding"] = padding
+        internal_kwargs.update(kwargs)
+
+        self._internal = _InternalToolbar(tk_master, **internal_kwargs)
+        self._attach_to_parent(layout_kw)
+
+    # ----- Properties -----
+
+    @property
+    def density(self) -> WidgetDensity:
+        """Current density setting for toolbar items."""
+        return self._internal.density
+
+    @property
+    def button_variant(self) -> str:
+        """Default variant applied to buttons added via `add_button()`."""
+        return self._internal._button_variant
+
+    # ----- Content -----
+
+    def add_button(
+        self,
+        label: str | None = None,
+        *,
+        icon: str | None = None,
+        on_click: Callable[[], Any] | None = None,
+        accent: AccentToken | str | None = None,
+        variant: ButtonVariant | None = None,
+        **kwargs: Any,
+    ) -> "Button":
+        """Add a button to the toolbar and return it for later control.
+
+        When both `label` and `icon` are given, the button shows text and icon
+        side by side. When only `icon` is given, the button is icon-only.
+
+        Args:
+            label: Button label text.
+            icon: Icon name. When provided without `label`, renders icon-only.
+            on_click: Callback fired when the button is clicked.
+            accent: Color intent override.
+            variant: Variant override. When omitted, falls back to the toolbar's
+                `button_variant` (default `'ghost'`).
+
+        Returns:
+            The :class:`~bootstack.Button` — use its live properties to control
+            it later, e.g. ``btn.disabled = True`` or ``btn.text = 'Saving…'``.
+        """
+        from bootstack.widgets.button import Button
+
+        kw: dict[str, Any] = {
+            "text": label or "",
+            "variant": variant or self.button_variant,
+            "density": self.density,
+            "surface": self._internal.surface,
+        }
+        if icon is not None:
+            kw["icon"] = icon
+        if on_click is not None:
+            kw["on_click"] = on_click
+        if accent is not None:
+            kw["accent"] = accent
+        kw.update(kwargs)  # explicit kwargs (incl. text=) win over the defaults
+        return Button(parent=self, **kw)
+
+    def add_menu(self, text: str, *, key: str | None = None) -> "MenuGroup":
+        """Add a dropdown menu (File / Edit / …) as a toolbar item.
+
+        A menu is just another toolbar item. The returned builder is a context
+        manager, so the natural form reads::
+
+            with toolbar.add_menu("File") as file:
+                file.add_action("Open", shortcut="Mod+O", on_click=open_file)
+                file.add_divider()
+                file.add_action("Quit", shortcut="Mod+Q", on_click=app.close)
+
+        On Windows/Linux the menu renders as an in-window dropdown; on macOS it
+        is bridged to the native global menu bar (when the toolbar is part of a
+        window's chrome).
+
+        Args:
+            text: The menu's label (e.g. `'File'`).
+            key: Optional stable identifier; defaults to `text`.
+
+        Returns:
+            The menu's `MenuGroup` builder (`add_action` / `add_check` /
+            `add_radio` / `add_divider`; usable as a context manager).
+        """
+        return self._internal.add_menu(text, key=key)
+
+    def add_label(
+        self,
+        text: str | None = None,
+        *,
+        icon: str | None = None,
+        font: str | None = None,
+        **kwargs: Any,
+    ) -> "Label":
+        """Add a non-interactive label to the toolbar and return it.
+
+        Args:
+            text: Label text.
+            icon: Icon name displayed alongside the text.
+            font: Font token, e.g. `'heading-md'` or `'caption'`.
+
+        Returns:
+            The :class:`~bootstack.Label` — use its live properties to update it
+            later, e.g. ``lbl.text = 'Updated'``.
+        """
+        from bootstack.widgets.label import Label
+
+        kw: dict[str, Any] = {"text": text or "", "surface": self._internal.surface}
+        if icon is not None:
+            kw["icon"] = icon
+        if font is not None:
+            kw["font"] = font
+        kw.update(kwargs)
+        lbl = Label(parent=self, **kw)
+        # On a draggable bar (e.g. a titlebar) the label doubles as a drag handle.
+        self._internal._attach_drag(lbl._internal)
+        return lbl
+
+    def add_divider(self, length: int = 16) -> None:
+        """Add a vertical divider.
+
+        Args:
+            length: Divider height in pixels. Defaults to `16`.
+        """
+        self._internal.add_separator(length=length)
+
+    def add_spacer(self) -> None:
+        """Add a flexible spacer that pushes subsequent items to the right."""
+        self._internal.add_spacer()
+
+    def add_widget(self, widget_cls: Any, **kwargs: Any) -> Any:
+        """Build a widget on the toolbar from its class.
+
+        Pass a widget **class** — the bar builds it, applying its own `density`
+        and `surface` (for any the class accepts) so the widget matches the rest
+        of the bar, and forwarding `kwargs` to the constructor (overriding those
+        defaults):
+
+            bar.add_widget(bs.ThemeToggle)
+            bar.add_widget(bs.TextField, placeholder="Search", width=24)
+
+        To add a widget you have already built yourself, parent it onto the bar
+        directly — it attaches automatically and keeps whatever you configured:
+
+            bs.MyCustomWidget(parent=bar)
+
+        Args:
+            widget_cls: The widget class to build on the bar.
+            **kwargs: Constructor arguments for the widget.
+
+        Returns:
+            The new widget instance.
+        """
+        self._apply_bar_defaults(widget_cls, kwargs)
+        return widget_cls(parent=self, **kwargs)
+
+    def _apply_bar_defaults(self, widget_cls: type, kwargs: dict[str, Any]) -> None:
+        """Default `density`/`surface` from the bar onto a class being built, but
+        only for parameters the widget actually accepts (and not if the caller
+        already passed them).
+
+        A widget is treated as accepting `density`/`surface` only when it declares
+        that parameter by name. A bare `**kwargs` catch-all does NOT count: in the
+        public layer `**kwargs` is the layout-placement passthrough, and several
+        widgets use it to *reject* unknown keys — injecting into those raises a
+        `TypeError`, and injecting into ones that ignore it is a silent no-op.
+        """
+        import inspect
+
+        try:
+            params = inspect.signature(widget_cls).parameters
+        except (TypeError, ValueError):
+            return
+        if "density" in params:
+            kwargs.setdefault("density", self._internal.density)
+        if "surface" in params:
+            kwargs.setdefault("surface", self._internal.surface)
+
+    # ----- Container protocol (so `parent=toolbar` works) -----
+
+    def _child_master(self) -> Any:
+        return self._internal.content
+
+    def guide_layout(self, child: Any, **layout_kw: Any) -> None:
+        # A widget created with `parent=toolbar` is packed into the bar.
+        self._internal.add_widget(child._internal)
+
+    def __enter__(self) -> "Toolbar":
+        # A *scoping* context manager (like `menubar.add_menu`): `with
+        # window.add_toolbar() as tb:` reads naturally and hands back the handle,
+        # but it does NOT capture bare widgets — fill the bar with `add_button` /
+        # `add_menu` / `add_widget(Class, ...)` so each item inherits the bar's
+        # density and surface (a constructed-then-attached widget cannot).
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        return None
+
+    @property
+    def content(self) -> Any:
+        """The bar's content frame — parent custom widgets here."""
+        return self._internal.content
+
+    def add_theme_toggle(self, **kwargs: Any) -> Any:
+        """Add a `ThemeToggle` — a sun/moon button that flips the theme.
+
+        Args:
+            **kwargs: Forwarded to `ThemeToggle` — e.g. `variant`, `density`,
+                `accent`, `light_icon`, `dark_icon`.
+
+        Returns:
+            The created `ThemeToggle`.
+        """
+        from bootstack.widgets.theme_toggle import ThemeToggle
+
+        self._apply_bar_defaults(ThemeToggle, kwargs)
+        return ThemeToggle(parent=self, **kwargs)
+
+    def add_sidebar_toggle(self, **kwargs: Any) -> Any:
+        """Add a hamburger button that collapses/expands the AppShell sidebar.
+
+        Only meaningful on a toolbar built into an `AppShell` (via
+        `shell.add_toolbar()`); raises on an `App`/`Window` toolbar, which has no
+        sidebar. Place it wherever you like in the bar.
+
+        Args:
+            **kwargs: Forwarded to the toggle button — e.g. `collapse`
+                (`'hidden'`/`'compact'`), `icon`, `expand_icon`, `collapse_icon`,
+                `variant`, `density`, `accent`.
+
+        Returns:
+            The created sidebar-toggle button.
+        """
+        from bootstack.widgets.sidebar_toggle import SidebarToggle
+
+        shell = self._sidebar_host()
+        self._apply_bar_defaults(SidebarToggle, kwargs)
+        return SidebarToggle(shell=shell, parent=self, **kwargs)
+
+    def _sidebar_host(self) -> Any:
+        """Return the owning `AppShell`, or raise if this bar has no sidebar.
+
+        Restricted to `AppShell` — the single-tier sidebar host. A `Workbench`
+        (two-tier, rail + per-workspace sidebars) inherits the shell sidebar
+        methods but is intentionally not supported here.
+        """
+        from bootstack.widgets.appshell import AppShell
+
+        host = getattr(self, "_host", None)
+        if not isinstance(host, AppShell):
+            raise BootstackError(
+                "add_sidebar_toggle() requires a toolbar built on an AppShell "
+                "(via shell.add_toolbar()); it is not supported on a Workbench or "
+                "a plain App/Window."
+            )
+        return host

bootstack/widgets/tooltip.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from bootstack.widgets._impl.composites.tooltip import ToolTip as _InternalToolTip
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets.types import AccentToken, Anchor, Justify
+
+
+class Tooltip:
+    """A hover tooltip attached to a target widget.
+
+    The tooltip appears after `delay` milliseconds when the mouse enters the
+    target and disappears when the mouse leaves or clicks. Positioning follows
+    the mouse cursor by default; pass `anchor_point` and `window_point` to
+    pin the tooltip to a specific edge of the widget instead.
+
+    Args:
+        target: Widget to attach the tooltip to. Accepts any bootstack widget.
+            When the target is a container, the tooltip shows while hovering
+            anywhere inside it, including over its children present at attach
+            time. For children added later, call `refresh_bindings()`.
+        text: Tooltip text content. Defaults to `''`.
+        delay: Milliseconds before the tooltip appears on mouse enter. Defaults
+            to `250`.
+        accent: Semantic color accent. Defaults to the theme's elevated
+            background color.
+        wrap_width: Maximum text width in pixels before wrapping. Defaults to
+            `None` (auto-scaled to approximately 300 px).
+        justify: Text alignment inside the tooltip. Defaults to `'left'`.
+        anchor_point: Anchor on the *target widget* the tooltip attaches to.
+            Defaults to `None` (tooltip follows the mouse).
+        window_point: Anchor on the *tooltip window* aligned to `anchor_point`.
+            Defaults to the opposite of `anchor_point` when it is set.
+        auto_flip: Keep the tooltip fully on screen. `True` flips both axes,
+            `False` disables flipping, `'vertical'` or `'horizontal'` restricts
+            flipping to one axis. Defaults to `True`.
+    """
+
+    def __init__(
+        self,
+        target: PublicWidgetBase | Any,
+        text: str = "",
+        *,
+        delay: int = 250,
+        accent: AccentToken | str | None = None,
+        wrap_width: int | None = None,
+        justify: Justify = "left",
+        anchor_point: Anchor | None = None,
+        window_point: Anchor | None = None,
+        auto_flip: bool | Literal["vertical", "horizontal"] = True,
+    ) -> None:
+        tk_widget = target.tk if isinstance(target, PublicWidgetBase) else target
+
+        internal_kwargs: dict[str, Any] = {
+            "text": text,
+            "delay": delay,
+            "justify": justify,
+            "auto_flip": auto_flip,
+        }
+        if accent is not None:
+            internal_kwargs["accent"] = accent
+        if wrap_width is not None:
+            internal_kwargs["wraplength"] = wrap_width
+        if anchor_point is not None:
+            internal_kwargs["anchor_point"] = anchor_point
+        if window_point is not None:
+            internal_kwargs["window_point"] = window_point
+
+        self._internal = _InternalToolTip(tk_widget, **internal_kwargs)
+
+    def refresh_bindings(self) -> None:
+        """Re-cover a container target's subtree after adding children to it.
+
+        A tooltip on a container covers the children present when it was
+        created. Add more children later and call this so hovering them shows
+        the tip too. Safe to call repeatedly — already-covered children are
+        left untouched.
+        """
+        self._internal.refresh_bindings()
+
+    @property
+    def text(self) -> str:
+        """The tooltip text. Assign to change it — a visible tooltip updates
+        immediately, and the next hover shows the new text."""
+        return self._internal._text
+
+    @text.setter
+    def text(self, value: str) -> None:
+        self._internal.text = value
+
+    def destroy(self) -> None:
+        """Remove the tooltip and unbind all event handlers."""
+        self._internal.destroy()