ScrollableControl

Shared scroll behavior for controls that expose a scrollable viewport.

This mixin-style control is inherited by controls such as Column, Row, View, ListView, and GridView. It provides a common API for:

• enabling/disabling scrolling and scrollbar visibility via scroll;
• receiving throttled scroll notifications via on_scroll and scroll_interval;
• imperatively changing position with scroll_to.

Inherits: Control

Properties

• auto_scroll - Whether the scrollbar should automatically move its position to the end when children updated.
• scroll - Defines the scroll bar configuration of this control.
• scroll_interval - Throttling in milliseconds for on_scroll event.

Events

• on_scroll - Called when scroll position is changed by a user.

Methods

• scroll_to - Moves the scroll position.

Properties

buildauto_scrollclass-attributeinstance-attribute

auto_scroll: bool = False

Whether the scrollbar should automatically move its position to the end when children updated.

Note

Must be False for scroll_to method to work.

buildscrollclass-attributeinstance-attribute

scroll: Optional[Union[ScrollMode, Scrollbar]] = None

Defines the scroll bar configuration of this control.

Can be a Scrollbar instance for full control over the appearance of the scrollbar, or a ScrollMode value, for ready-made scrollbar behaviors.

buildscroll_intervalclass-attributeinstance-attribute

scroll_interval: Number = 10

Throttling in milliseconds for on_scroll event.

Events

bolton_scrollclass-attributeinstance-attribute

on_scroll: Optional[EventHandler[OnScrollEvent]] = None

Called when scroll position is changed by a user.

Methods

deployed_codescroll_toasync

scroll_to(offset: Optional[float] = None, delta: Optional[float] = None, scroll_key: Union[ScrollKey, str, int, float, bool, None] = None, duration: DurationValue = 0, curve: AnimationCurve = AnimationCurve.EASE)

Moves the scroll position.

Parameters:

• offset (Optional[float], default: None) - Absolute scroll target in pixels. A negative value is interpreted relative to the end (e.g. -1 to jump to the very end).
• delta (Optional[float], default: None) - Relative scroll change in pixels. Positive values scroll forward, negative values scroll backward.
• scroll_key (Union[ScrollKey, str, int, float, bool, None], default: None) - Key of the target control to scroll to.
• duration (DurationValue, default: 0) - The scroll animation duration.
• curve (AnimationCurve, default: AnimationCurve.EASE) - The scroll animation curve.

Notes

• Exactly one of offset, delta or scroll_key should be provided.
• auto_scroll must be False.
• This method is ineffective for controls (e.g. ListView, GridView) that build items dynamically.