bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_impl/composites/scrollview.py

@@ -0,0 +1,764 @@
+"""Canvas-based scrollable container widget with mouse wheel support."""
+from tkinter import Canvas
+from tkinter.ttk import Widget
+from typing import Any, Literal
+
+from bootstack.widgets._impl.primitives.frame import Frame
+from bootstack.widgets._impl.mixins.configure_mixin import configure_delegate
+from bootstack.widgets._impl.primitives.scrollbar import Scrollbar
+from bootstack.widgets.types import Master
+from bootstack.events import ScrollEvent
+
+
+class ScrollView(Frame):
+    """A canvas-based scrollable container with configurable scrollbar behavior.
+
+    The ScrollView widget provides a scrollable area for child widgets with
+    full mouse wheel support on all descendants. Scrollbars can be configured
+    to appear always, never, on hover, or when scrolling, and are only visible
+    when the content exceeds the available space.
+
+    Attributes:
+        canvas: The underlying tkinter Canvas widget.
+        vertical_scrollbar: The vertical scrollbar widget.
+        horizontal_scrollbar: The horizontal scrollbar widget.
+    """
+
+    def __init__(
+            self,
+            master: Master = None,
+            scroll_direction: Literal['horizontal', 'vertical', 'both'] = 'both',
+            scrollbar_visibility: Literal['always', 'never', 'hover', 'scroll'] = 'always',
+            autohide_delay: int = 1000,  # milliseconds for scroll mode
+            scrollbar_variant: str = 'default',
+            **kwargs: Any
+    ):
+        """Initialize a ScrollView widget.
+
+        Args:
+            master: The parent widget.
+            scroll_direction: Scroll direction - 'horizontal' for horizontal only,
+                'vertical' for vertical only, or 'both' for bidirectional
+                scrolling. Horizontal scrolling uses Shift+MouseWheel.
+            scrollbar_visibility: Scrollbar visibility mode:
+                - 'always': Scrollbars always visible
+                - 'never': Scrollbars hidden (scrolling still works)
+                - 'hover': Scrollbars appear when mouse enters the widget
+                - 'scroll': Scrollbars appear when scrolling, auto-hide after delay
+            autohide_delay: Time in milliseconds before auto-hiding scrollbars
+                in 'scroll' mode. Default is 1000ms (1 second).
+            scrollbar_variant: The variant to apply to scrollbars (e.g., 'default',
+                'round'). If None, uses the default scrollbar variant.
+            **kwargs: Additional keyword arguments passed to the Frame parent class.
+
+        Note:
+            Mouse wheel scrolling is automatically enabled on all child widgets,
+            including those added dynamically. For manual refresh of bindings
+            after adding many widgets at once, call refresh_bindings().
+        """
+        canvas_height = kwargs.pop('height', None)
+        canvas_width = kwargs.pop('width', None)
+        super().__init__(master, **kwargs)
+
+        # configuration
+        self._direction = scroll_direction
+        self._scrollbar_visibility = scrollbar_visibility
+        self._autohide_delay = autohide_delay
+        self._scrollbar_variant = scrollbar_variant
+
+        self._child_widget = None
+        self._window_id = None
+        self._hide_timer = None
+        self._scrolling_enabled = False
+        self._hovering = False
+
+        # Create unique bind tag for this scrollview
+        self._scroll_tag = f'ScrollView_{id(self)}'
+
+        # Detect windowing system
+        self.winsys = self.tk.call("tk", "windowingsystem")
+
+        # Bind scroll events to our custom tag
+        self._setup_scroll_tag_bindings()
+
+        # Create canvas
+        canvas_kw: dict[str, Any] = {"highlightthickness": 0, "borderwidth": 0}
+        if canvas_height is not None:
+            canvas_kw["height"] = canvas_height
+        if canvas_width is not None:
+            canvas_kw["width"] = canvas_width
+        self.canvas = Canvas(self, **canvas_kw)
+        self.canvas.bind("<Configure>", self._on_canvas_configure)
+        # Focus canvas on click so keyboard scrolling works.
+        self.canvas.bind("<Button-1>", lambda e: self.canvas.focus_set(), add="+")
+        self._setup_keyboard_bindings()
+
+        # Create scrollbars. Thread our own surface through so the scrollbar track
+        # matches the container (an auto-hiding bar then leaves no tinted gutter).
+        sb_surface = getattr(self, "_surface", None)
+        sb_kw: dict[str, Any] = {"surface": sb_surface} if sb_surface else {}
+        self.vertical_scrollbar = Scrollbar(
+            master=self,
+            orient='vertical',
+            command=self.canvas.yview,
+            variant=self._scrollbar_variant,
+            **sb_kw,
+        )
+        self.horizontal_scrollbar = Scrollbar(
+            master=self,
+            orient='horizontal',
+            command=self.canvas.xview,
+            variant=self._scrollbar_variant,
+            **sb_kw,
+        )
+
+        # Configure canvas scrolling
+        scroll_config = {}
+        if scroll_direction in ('vertical', 'both'):
+            scroll_config['yscrollcommand'] = self._on_canvas_scroll_y
+        if scroll_direction in ('horizontal', 'both'):
+            scroll_config['xscrollcommand'] = self._on_canvas_scroll_x
+
+        self.canvas.configure(**scroll_config)
+
+        # Layout
+        self._layout_widgets()
+
+        # Bind events for autohide/hover
+        self._bind_container_events()
+
+        # Initial scrollbar visibility
+        self._update_scrollbar_visibility()
+
+        # Finalize content sizing on first show. A ScrollView is usually built
+        # inside a hidden window (the `with App()/Workbench()` block), so the
+        # canvas <Configure> that pins the content width to the viewport may fire
+        # at a transient size — or never at the final size — leaving the content
+        # at its natural width (inflated by wide children, e.g. a chart's default
+        # request). It then overflows until a user resize or theme change triggers
+        # a fresh <Configure>. Re-pin the width and recompute the scroll region
+        # once we are actually mapped.
+        self._first_map_done = False
+        self.bind('<Map>', self._on_first_map, add='+')
+
+    @configure_delegate('scroll_direction')
+    def _delegate_scroll_direction(self, value=None):
+        """Get or set the scroll direction."""
+        if value is None:
+            return self._direction
+        else:
+            old_direction = self._direction
+            self._direction = value
+
+            # Update canvas scroll configuration
+            scroll_config = {}
+            if value in ('vertical', 'both'):
+                scroll_config['yscrollcommand'] = self._on_canvas_scroll_y
+            else:
+                scroll_config['yscrollcommand'] = None
+
+            if value in ('horizontal', 'both'):
+                scroll_config['xscrollcommand'] = self._on_canvas_scroll_x
+            else:
+                scroll_config['xscrollcommand'] = None
+
+            self.canvas.configure(**scroll_config)
+
+            # Update scrollbar visibility and layout
+            self._update_scrollbar_visibility()
+        return None
+
+    @configure_delegate('scrollbar_visibility')
+    def _delegate_scrollbar_visibility(self, value=None):
+        """Get or set the scrollbar visibility mode."""
+        if value is None:
+            return self._scrollbar_visibility
+        else:
+            old_value = self._scrollbar_visibility
+            self._scrollbar_visibility = value
+
+            # Unbind old events if changing from hover
+            if old_value == 'hover':
+                self.unbind('<Enter>')
+                self.unbind('<Leave>')
+                self.canvas.unbind('<Enter>')
+                self.canvas.unbind('<Leave>')
+                self.vertical_scrollbar.unbind('<Enter>')
+                self.vertical_scrollbar.unbind('<Leave>')
+                self.horizontal_scrollbar.unbind('<Enter>')
+                self.horizontal_scrollbar.unbind('<Leave>')
+
+            # Sync gutter reservation with the new mode
+            if value in ('hover', 'scroll'):
+                self._set_scrollbar_gutter(reserve=True)
+            else:
+                self._set_scrollbar_gutter(reserve=False)
+
+            # Bind new events and update scrollbar visibility
+            self._bind_container_events()
+            self._update_scrollbar_visibility()
+
+            # Update scrolling enabled state
+            if value in ('always', 'never', 'scroll'):
+                if self._child_widget:
+                    self.enable_scrolling()
+            elif value == 'hover':
+                # Scrolling will be enabled on hover
+                self.disable_scrolling()
+        return None
+
+    @configure_delegate('autohide_delay')
+    def _delegate_autohide_delay(self, value=None):
+        """Get or set the autohide delay in milliseconds."""
+        if value is None:
+            return self._autohide_delay
+        else:
+            self._autohide_delay = value
+        return None
+
+    @configure_delegate('scrollbar_variant')
+    def _delegate_scrollbar_variant(self, value=None):
+        """Get or set the scrollbar variant."""
+        if value is None:
+            return self._scrollbar_variant
+        else:
+            self._scrollbar_variant = value
+            # Apply the new variant to both scrollbars
+            if value:
+                self.vertical_scrollbar.configure(variant=value)
+                self.horizontal_scrollbar.configure(variant=value)
+        return None
+
+    def _setup_scroll_tag_bindings(self):
+        """Setup bindings on our custom bind tag."""
+        if self.winsys.lower() == "x11":
+            self.bind_class(self._scroll_tag, "<Button-4>", self._on_mousewheel)
+            self.bind_class(self._scroll_tag, "<Button-5>", self._on_mousewheel)
+            self.bind_class(self._scroll_tag, "<Shift-Button-4>", self._on_shift_mousewheel)
+            self.bind_class(self._scroll_tag, "<Shift-Button-5>", self._on_shift_mousewheel)
+        else:
+            self.bind_class(self._scroll_tag, "<MouseWheel>", self._on_mousewheel)
+            self.bind_class(self._scroll_tag, "<Shift-MouseWheel>", self._on_shift_mousewheel)
+
+    def _setup_keyboard_bindings(self) -> None:
+        """Bind arrow / page / home / end keys to the canvas for keyboard scroll."""
+        c = self.canvas
+        # Vertical
+        c.bind("<Up>",    lambda e: self.canvas.yview_scroll(-1, "units") or "break", add="+")
+        c.bind("<Down>",  lambda e: self.canvas.yview_scroll( 1, "units") or "break", add="+")
+        c.bind("<Prior>", lambda e: self.canvas.yview_scroll(-1, "pages") or "break", add="+")
+        c.bind("<Next>",  lambda e: self.canvas.yview_scroll( 1, "pages") or "break", add="+")
+        c.bind("<Home>",  lambda e: self.canvas.yview_moveto(0.0) or "break", add="+")
+        c.bind("<End>",   lambda e: self.canvas.yview_moveto(1.0) or "break", add="+")
+        # Horizontal
+        c.bind("<Left>",  lambda e: self.canvas.xview_scroll(-1, "units") or "break", add="+")
+        c.bind("<Right>", lambda e: self.canvas.xview_scroll( 1, "units") or "break", add="+")
+
+    def _layout_widgets(self):
+        """Layout the canvas and scrollbars.
+
+        For 'hover' and 'scroll' visibility modes the grid column and row that
+        hold the scrollbars are given a fixed minimum size equal to the
+        scrollbar's natural dimensions before the scrollbars are hidden. This
+        reserves the gutter permanently so the canvas never resizes when a
+        scrollbar is toggled — the same principle as the CSS
+        `scrollbar-gutter: stable` property.
+
+        An overlay approach (lift/lower over the canvas) was considered but
+        rejected because the scrollbar then covers content, which was reported
+        as confusing by users. Reserving the gutter avoids both the
+        layout-shift problem *and* the content-coverage problem.
+
+        For 'never' mode the scrollbars are never placed in the grid at all.
+        Gridding them and immediately calling grid_remove() leaves Tkinter's
+        geometry manager holding the column's natural width until the next idle
+        cycle, which produces a visible gap beside the content area.
+        """
+        self.canvas.grid(row=0, column=0, sticky='nsew')
+
+        # Configure grid weights
+        self.grid_rowconfigure(0, weight=1)
+        self.grid_columnconfigure(0, weight=1)
+
+        if self._scrollbar_visibility == 'never':
+            # Don't touch the grid for the scrollbar columns/rows — column 1
+            # and row 1 stay at zero width so no space is reserved.
+            return
+
+        if self._direction in ('vertical', 'both'):
+            self.vertical_scrollbar.grid(row=0, column=1, sticky='ns')
+
+        if self._direction in ('horizontal', 'both'):
+            self.horizontal_scrollbar.grid(row=1, column=0, sticky='ew')
+
+        # Keep scrollbars above the canvas/content when visible
+        self.vertical_scrollbar.lift()
+        self.horizontal_scrollbar.lift()
+
+        if self._scrollbar_visibility in ('hover', 'scroll'):
+            # Hide scrollbars now; defer gutter measurement to after_idle so
+            # the style system has finished sizing the widgets before we read
+            # their dimensions.  Measuring too early (before the widget is
+            # placed in its parent) can return an inflated reqwidth and leave
+            # a visible gap beside the scrollbar when it appears.
+            self.vertical_scrollbar.grid_remove()
+            self.horizontal_scrollbar.grid_remove()
+            self.after_idle(lambda: self._set_scrollbar_gutter(reserve=True))
+
+    def _set_scrollbar_gutter(self, reserve: bool):
+        """Reserve or release the grid gutter used by each scrollbar.
+
+        When *reserve* is `True` the column (vertical scrollbar) and row
+        (horizontal scrollbar) are given a `minsize` equal to the scrollbar's
+        natural requested dimensions.  The minsize persists even after the
+        scrollbar widget is removed from the grid via `grid_remove()`, so the
+        canvas occupies a constant area regardless of scrollbar visibility.
+
+        When *reserve* is `False` the minsize is cleared (set to 0), which
+        is appropriate for 'always' and 'never' modes where no gutter needs to
+        be held open.
+        """
+        if reserve:
+            if self._direction in ('vertical', 'both'):
+                width = self.vertical_scrollbar.winfo_reqwidth()
+                if width > 1:
+                    self.grid_columnconfigure(1, minsize=width)
+            if self._direction in ('horizontal', 'both'):
+                height = self.horizontal_scrollbar.winfo_reqheight()
+                if height > 1:
+                    self.grid_rowconfigure(1, minsize=height)
+        else:
+            self.grid_columnconfigure(1, minsize=0)
+            self.grid_rowconfigure(1, minsize=0)
+
+    def _bind_container_events(self):
+        """Bind events for the container (enter/leave for autohide)."""
+        if self._scrollbar_visibility == 'hover':
+            self.bind('<Enter>', self._on_container_enter)
+            self.bind('<Leave>', self._on_container_leave)
+            self.canvas.bind('<Enter>', self._on_container_enter)
+            self.canvas.bind('<Leave>', self._on_container_leave)
+            self.vertical_scrollbar.bind('<Enter>', self._on_container_enter)
+            self.vertical_scrollbar.bind('<Leave>', self._on_container_leave)
+            self.horizontal_scrollbar.bind('<Enter>', self._on_container_enter)
+            self.horizontal_scrollbar.bind('<Leave>', self._on_container_leave)
+
+    def _on_container_enter(self, event):
+        """Handle mouse entering the container."""
+        self._hovering = True
+        self.enable_scrolling()
+        if self._scrollbar_visibility == 'hover':
+            self._show_scrollbars()
+
+    def _on_container_leave(self, event):
+        """Handle mouse leaving the container."""
+        self._hovering = False
+        self.disable_scrolling()
+        if self._scrollbar_visibility == 'hover':
+            self._hide_scrollbars()
+
+    def _content_fits(self):
+        """Return booleans for whether content fits in the viewport (x_fit, y_fit)."""
+        if self._window_id:
+            bbox = self.canvas.bbox(self._window_id)
+        else:
+            bbox = self.canvas.bbox('all')
+        if not bbox:
+            return True, True
+        x0, y0, x1, y1 = bbox
+        content_w = x1 - x0
+        content_h = y1 - y0
+        viewport_w = max(1, self.canvas.winfo_width())
+        viewport_h = max(1, self.canvas.winfo_height())
+        if viewport_w <= 1 or viewport_h <= 1:
+            return True, True
+        return content_w <= viewport_w, content_h <= viewport_h
+
+    def _show_scrollbars(self):
+        """Show scrollbars only if content overflows the viewport."""
+        x_fit, y_fit = self._content_fits()
+        if self._direction in ('vertical', 'both') and not y_fit:
+            self.vertical_scrollbar.grid(row=0, column=1, sticky='ns')
+            self.vertical_scrollbar.lift()
+        else:
+            self.vertical_scrollbar.grid_remove()
+        if self._direction in ('horizontal', 'both') and not x_fit:
+            self.horizontal_scrollbar.grid(row=1, column=0, sticky='ew')
+            self.horizontal_scrollbar.lift()
+        else:
+            self.horizontal_scrollbar.grid_remove()
+
+    def _hide_scrollbars(self):
+        """Hide scrollbars."""
+        self.vertical_scrollbar.grid_remove()
+        self.horizontal_scrollbar.grid_remove()
+
+    def _on_canvas_configure(self, event):
+        """Pin content width to viewport and update visibility."""
+        if self._window_id and self._direction in ('vertical', 'both'):
+            self.canvas.itemconfig(self._window_id, width=event.width)
+        self._update_scrollbar_visibility()
+
+    def _on_first_map(self, event=None):
+        """On the first show, finalize content sizing (see __init__)."""
+        if event is not None and event.widget is not self:
+            return
+        if self._first_map_done:
+            return
+        self._first_map_done = True
+        # Defer to idle so the geometry manager has assigned the canvas its real
+        # viewport size before we read it.
+        self.after_idle(self._finalize_layout)
+
+    def _finalize_layout(self):
+        """Pin the content width to the realized viewport and recompute scroll."""
+        try:
+            if not self.winfo_exists():
+                return
+            self.canvas.update_idletasks()
+            width = self.canvas.winfo_width()
+            if (self._window_id and width > 1
+                    and self._direction in ('vertical', 'both')):
+                self.canvas.itemconfig(self._window_id, width=width)
+            self.canvas.configure(scrollregion=self.canvas.bbox('all'))
+            self._update_scrollbar_visibility()
+        except Exception:
+            pass
+
+    def _on_canvas_scroll_y(self, first, last):
+        """Update vertical scrollbar position."""
+        self.vertical_scrollbar.set(first, last)
+        self._update_scrollbar_visibility()
+        self._emit_scroll_event()
+
+    def _on_canvas_scroll_x(self, first, last):
+        """Update horizontal scrollbar position."""
+        self.horizontal_scrollbar.set(first, last)
+        self._update_scrollbar_visibility()
+        self._emit_scroll_event()
+
+    def _emit_scroll_event(self) -> None:
+        y = float(self.canvas.yview()[0])
+        x = float(self.canvas.xview()[0])
+        self.event_generate("<<BsScroll>>", data=ScrollEvent(y=y, x=x))
+
+    @property
+    def scroll_position(self) -> tuple[float, float]:
+        """Current scroll position as `(y, x)` fractions in `[0.0, 1.0]`."""
+        return float(self.canvas.yview()[0]), float(self.canvas.xview()[0])
+
+    def _update_scrollbar_visibility(self):
+        """Update scrollbar visibility based on current mode."""
+        if self._scrollbar_visibility == 'always':
+            self._show_scrollbars()
+        elif self._scrollbar_visibility == 'never':
+            self._hide_scrollbars()
+        elif self._scrollbar_visibility == 'hover':
+            # Show only while hovering and overflowing
+            x_fit, y_fit = self._content_fits()
+            if self._hovering and self._direction in ('vertical', 'both') and not y_fit:
+                self.vertical_scrollbar.grid()
+            else:
+                self.vertical_scrollbar.grid_remove()
+
+            if self._hovering and self._direction in ('horizontal', 'both') and not x_fit:
+                self.horizontal_scrollbar.grid()
+            else:
+                self.horizontal_scrollbar.grid_remove()
+        elif self._scrollbar_visibility == 'scroll':
+            # Hide if no overflow; otherwise leave current visibility to scroll events
+            x_fit, y_fit = self._content_fits()
+            if y_fit:
+                self.vertical_scrollbar.grid_remove()
+            if x_fit:
+                self.horizontal_scrollbar.grid_remove()
+
+    def _on_frame_configure(self, event):
+        """Update scroll region and refresh bindings on configure."""
+        self.canvas.configure(scrollregion=self.canvas.bbox('all'))
+        self._update_scrollbar_visibility()
+
+        # Refresh bindings for any newly added widgets
+        if self._scrolling_enabled and self._child_widget:
+            self._add_scroll_binding(self._child_widget)
+
+    def _on_mousewheel(self, event):
+        """Handle vertical mouse wheel scrolling."""
+        # Check if vertical scrolling is actually possible
+        if self._direction in ('vertical', 'both'):
+            try:
+                first, last = self.canvas.yview()
+                # If first=0.0 and last=1.0, all content is visible, no need to scroll
+                if first <= 0.0 and last >= 1.0:
+                    return  # Content fits, don't scroll
+            except:
+                pass  # If we can't check, allow scrolling
+
+        # Show scrollbar temporarily in scroll mode
+        if self._scrollbar_visibility == 'scroll':
+            self._show_scrollbars()
+            if self._hide_timer:
+                self.after_cancel(self._hide_timer)
+            self._hide_timer = self.after(self._autohide_delay, self._hide_scrollbars)
+
+        # Calculate delta based on platform
+        delta = 0
+        if self.winsys.lower() == "win32":
+            delta = -int(event.delta / 120)
+        elif self.winsys.lower() == "aqua":
+            delta = -event.delta
+        elif event.num == 4:
+            delta = -10
+        elif event.num == 5:
+            delta = 10
+
+        # Scroll vertically
+        if self._direction in ('vertical', 'both') and delta != 0:
+            self.canvas.yview_scroll(delta, 'units')
+
+        # Don't return 'break' - allow event to propagate to other handlers if needed
+        # But we can return None to continue normal processing
+
+    def _on_shift_mousewheel(self, event):
+        """Handle horizontal mouse wheel scrolling (Shift+MouseWheel)."""
+        # Check if horizontal scrolling is actually possible
+        if self._direction in ('horizontal', 'both'):
+            try:
+                first, last = self.canvas.xview()
+                # If first=0.0 and last=1.0, all content is visible, no need to scroll
+                if first <= 0.0 and last >= 1.0:
+                    return  # Content fits, don't scroll
+            except:
+                pass  # If we can't check, allow scrolling
+
+        # Show scrollbar temporarily in scroll mode
+        if self._scrollbar_visibility == 'scroll':
+            self._show_scrollbars()
+            if self._hide_timer:
+                self.after_cancel(self._hide_timer)
+            self._hide_timer = self.after(self._autohide_delay, self._hide_scrollbars)
+
+        # Calculate delta based on platform
+        delta = 0
+        if self.winsys.lower() == "win32":
+            delta = -int(event.delta / 120)
+        elif self.winsys.lower() == "aqua":
+            delta = -event.delta
+        elif event.num == 4:
+            delta = -10
+        elif event.num == 5:
+            delta = 10
+
+        # Scroll horizontally
+        if self._direction in ('horizontal', 'both') and delta != 0:
+            self.canvas.xview_scroll(delta, 'units')
+
+        # Don't return 'break' - allow event to propagate if needed
+
+    def _add_scroll_binding(self, widget):
+        """Recursively add scroll bind tag to widget and all descendants."""
+        try:
+            # Get current bindtags
+            tags = list(widget.bindtags())
+
+            # Add our scroll tag if not already present
+            if self._scroll_tag not in tags:
+                # Insert after the widget name but before the class
+                # Typical order: (widget_name, class, toplevel, 'all')
+                # We want: (widget_name, scroll_tag, class, toplevel, 'all')
+                if len(tags) >= 2:
+                    tags.insert(1, self._scroll_tag)
+                else:
+                    tags.append(self._scroll_tag)
+                widget.bindtags(tuple(tags))
+        except:
+            # Some widgets may not support bindtags
+            pass
+
+        # Recurse into all children
+        for child in widget.winfo_children():
+            self._add_scroll_binding(child)
+
+    def _del_scroll_binding(self, widget):
+        """Recursively remove scroll bind tag from widget and all descendants."""
+        try:
+            tags = list(widget.bindtags())
+            if self._scroll_tag in tags:
+                tags.remove(self._scroll_tag)
+                widget.bindtags(tuple(tags))
+        except:
+            pass
+
+        # Recurse into all children
+        for child in widget.winfo_children():
+            self._del_scroll_binding(child)
+
+    def enable_scrolling(self):
+        """Enable mouse wheel scrolling on canvas and all child widgets."""
+        if not self._scrolling_enabled:
+            # Add binding to canvas for exposed areas
+            self._add_scroll_binding(self.canvas)
+
+            # Add binding to child widget if it exists
+            if self._child_widget:
+                self._add_scroll_binding(self._child_widget)
+
+            self._scrolling_enabled = True
+
+    def disable_scrolling(self):
+        """Disable mouse wheel scrolling on canvas and all child widgets."""
+        if self._scrolling_enabled:
+            # Remove binding from canvas
+            self._del_scroll_binding(self.canvas)
+
+            # Remove binding from child widget if it exists
+            if self._child_widget:
+                self._del_scroll_binding(self._child_widget)
+
+            self._scrolling_enabled = False
+
+    def add(self, widget: Widget = None, *, anchor: str = 'nw', **kwargs: Any) -> Widget:
+        """Add a widget to the scrollable area, or create and return a Frame.
+
+        Args:
+            widget: The widget to add. If None, creates a Frame.
+            anchor: Anchor position for the widget in the canvas. Default is 'nw'.
+            **kwargs: When widget is None, these are passed to Frame (e.g., padding, accent).
+
+        Returns:
+            Widget: The content widget (passed or created).
+
+        Raises:
+            ValueError: If the ScrollView already contains a widget and a new one is provided.
+        """
+        # If content exists and no widget passed, return existing (idempotent)
+        if self._child_widget is not None:
+            if widget is not None:
+                raise ValueError("ScrollView already contains a widget. Use remove() first.")
+            return self._child_widget
+
+        # Create frame with kwargs if no widget provided
+        if widget is None:
+            widget = Frame(self.canvas, **kwargs)
+
+        self._child_widget = widget
+
+        # Create window in canvas
+        self._window_id = self.canvas.create_window(0, 0, anchor=anchor, window=widget)
+
+        # Keep scrollbars above the canvas/content
+        self.vertical_scrollbar.lift()
+        self.horizontal_scrollbar.lift()
+
+        # Bind configure event to update scroll region. (bind() auto-adds here,
+        # so this must run exactly once — a second identical bind double-fires
+        # _on_frame_configure on every resize, doubling the recursive subtree walk.)
+        widget.bind('<Configure>', self._on_frame_configure)
+        self._update_scrollbar_visibility()
+
+        # Enable scrolling based on mode
+        if self._scrollbar_visibility in ('always', 'never', 'scroll'):
+            # Always enable scrolling for these modes
+            self.enable_scrolling()
+        # For 'hover' mode, scrolling is enabled on enter
+
+        # Initial scroll region update
+        self.canvas.update_idletasks()
+        self.canvas.configure(scrollregion=self.canvas.bbox('all'))
+
+        return widget
+
+    def remove(self) -> Widget | None:
+        """Remove the current widget from the scrollable area.
+
+        Returns:
+            The removed widget, or None if no widget was present.
+        """
+        if self._child_widget is None:
+            return None
+
+        widget = self._child_widget
+
+        # Disable scrolling
+        self.disable_scrolling()
+
+        # Unbind events
+        widget.unbind('<Configure>')
+
+        # Delete canvas window
+        if self._window_id:
+            self.canvas.delete(self._window_id)
+            self._window_id = None
+
+        self._child_widget = None
+        self._scrolling_enabled = False
+
+        return widget
+
+    def get_child(self) -> Widget | None:
+        """Get the current child widget.
+
+        Returns:
+            The child widget, or None if no widget is present.
+        """
+        return self._child_widget
+
+    def refresh_bindings(self):
+        """Refresh mouse wheel bindings for all widgets.
+
+        Call this after dynamically adding many widgets at once to ensure
+        mouse wheel scrolling works on all new widgets.
+        """
+        if self._child_widget and self._scrolling_enabled:
+            # Re-enable to refresh bindings
+            self.disable_scrolling()
+            self.enable_scrolling()
+
+    def yview(self, *args):
+        """Query or command vertical view position."""
+        return self.canvas.yview(*args)
+
+    def xview(self, *args):
+        """Query or command horizontal view position."""
+        return self.canvas.xview(*args)
+
+    def yview_moveto(self, fraction: float):
+        """Scroll to a specific vertical position.
+
+        Args:
+            fraction: Position from 0.0 (top) to 1.0 (bottom).
+        """
+        self.canvas.yview_moveto(fraction)
+
+    def xview_moveto(self, fraction: float):
+        """Scroll to a specific horizontal position.
+
+        Args:
+            fraction: Position from 0.0 (left) to 1.0 (right).
+        """
+        self.canvas.xview_moveto(fraction)
+
+    def destroy(self):
+        """Clean up resources and destroy the widget."""
+        # Cancel any pending timer
+        if self._hide_timer:
+            self.after_cancel(self._hide_timer)
+            self._hide_timer = None
+
+        # Remove scroll bindings from child widget
+        if self._child_widget:
+            self.disable_scrolling()
+
+        # Unbind class bindings for the scroll tag
+        if self.winsys.lower() == "x11":
+            self.unbind_class(self._scroll_tag, "<Button-4>")
+            self.unbind_class(self._scroll_tag, "<Button-5>")
+            self.unbind_class(self._scroll_tag, "<Shift-Button-4>")
+            self.unbind_class(self._scroll_tag, "<Shift-Button-5>")
+        else:
+            self.unbind_class(self._scroll_tag, "<MouseWheel>")
+            self.unbind_class(self._scroll_tag, "<Shift-MouseWheel>")
+
+        # Call parent destroy
+        super().destroy()
+