ScrollView

Bases: 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:

Name	Type	Description
`canvas`	`Canvas`	The underlying tkinter Canvas widget.
`vertical_scrollbar`	`Scrollbar`	The vertical scrollbar widget.
`horizontal_scrollbar`	`Scrollbar`	The horizontal scrollbar widget.

init

__init__(
    master: Master = None,
    scroll_direction: Literal[
        "horizontal", "vertical", "both"
    ] = "both",
    scrollbar_visibility: Literal[
        "always", "never", "hover", "scroll"
    ] = "always",
    autohide_delay: int = 1000,
    scrollbar_variant: str = "default",
    **kwargs: Any,
)

Initialize a ScrollView widget.

Parameters:

Name	Type	Description	Default
`master`	`Master`	The parent widget.	`None`
`scroll_direction`	`Literal['horizontal', 'vertical', 'both']`	Scroll direction - 'horizontal' for horizontal only, 'vertical' for vertical only, or 'both' for bidirectional scrolling. Horizontal scrolling uses Shift+MouseWheel.	`'both'`
`scrollbar_visibility`	`Literal['always', 'never', 'hover', 'scroll']`	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	`'always'`
`autohide_delay`	`int`	Time in milliseconds before auto-hiding scrollbars in 'scroll' mode. Default is 1000ms (1 second).	`1000`
`scrollbar_variant`	`str`	The variant to apply to scrollbars (e.g., 'default', 'round'). If None, uses the default scrollbar variant.	`'default'`
`**kwargs`	`Any`	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().

enable_scrolling

enable_scrolling()

Enable mouse wheel scrolling on canvas and all child widgets.

disable_scrolling

disable_scrolling()

Disable mouse wheel scrolling on canvas and all child widgets.

add

add(
    widget: Widget = None,
    *,
    anchor: str = "nw",
    **kwargs: Any,
) -> Widget

Add a widget to the scrollable area, or create and return a Frame.

Parameters:

Name	Type	Description	Default
`widget`	`Widget \| None`	The widget to add. If None, creates a Frame.	`None`
`anchor`	`str`	Anchor position for the widget in the canvas. Default is 'nw'.	`'nw'`
`**kwargs`	`Any`	When widget is None, these are passed to Frame (e.g., padding, bootstyle).	`{}`

Returns:

Name	Type	Description
`Widget`	`Widget`	The content widget (passed or created).

Raises:

Type	Description
`ValueError`	If the ScrollView already contains a widget and a new one is provided.

remove

remove() -> Optional[Widget]

Remove the current widget from the scrollable area.

Returns:

Type	Description
`Optional[Widget]`	The removed widget, or None if no widget was present.

get_child

get_child() -> Optional[Widget]

Get the current child widget.

Returns:

Type	Description
`Optional[Widget]`	The child widget, or None if no widget is present.

refresh_bindings

refresh_bindings()

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.

yview

yview(*args)

Query or command vertical view position.

xview

xview(*args)

Query or command horizontal view position.

yview_moveto

yview_moveto(fraction: float)

Scroll to a specific vertical position.

Parameters:

Name	Type	Description	Default
`fraction`	`float`	Position from 0.0 (top) to 1.0 (bottom).	required

xview_moveto

xview_moveto(fraction: float)

Scroll to a specific horizontal position.

Parameters:

Name	Type	Description	Default
`fraction`	`float`	Position from 0.0 (left) to 1.0 (right).	required

destroy

destroy()

Clean up resources and destroy the widget.