Scrollable provides the interaction model for scrolling without specifying how the actual viewport is managed (a
ViewportBuilder must be provided). UI concerns are customized directly or via an inherited
ScrollConfiguration that exposes an immutable
ScrollBehavior instance. This instance is used to build platform-specific chrome (i.e., a scrolling indicator) and provides ambient
ScrollPhysics, a class that describes how scrolling UI will respond to user gestures.
ScrollPhysics is consulted throughout the framework to construct physics simulations for ballistic scrolling, to validate and adjust user interaction, to manage momentum across interactions, and to identify overscroll regions.
ScrollableState connects the
Scrollable to a
ScrollPosition via a
ScrollController. This controller is responsible for producing the
ScrollPosition from a given
ScrollPhysics; it also provides the
PageView injects a page-based scrolling mechanism by having its
PageController) return a custom scroll position subclass.
ScrollContext exposes build contexts for notifications and storage, a ticker provider for animations, and methods to interact with the scrollable; its analogous to
BuildContext for an entire scrollable widget.
ScrollPosition tracks scroll offset as pixels (reporting changes via
Listenable), applies physics to interactions via
ScrollPhysics, and through subclasses like
ScrollPositionWithSingleContext (which implement
ScrollActivityDelegate and makes concrete much of the actual scrolling machinery), starts and stops
ScrollActivity instances to mutate the represented scroll position.
The actual pixel offset and mechanisms for reacting to changes in the associated viewport are introduced via the
Viewport metrics are mixed in via
ScrollMetrics, which redundantly defines pixel offset and defines a number of other useful metrics like the amount of content above and below the current viewport (
extentAfter), the pixel offset corresponding to the top and bottom of the current viewport (
maxScrollExtent) and the viewport size (
The scroll position may need to be corrected (via
ScrollPosition.correctPixels [replaces pixels outright] /
ViewportOffset.correctBy [applies a delta to pixels]) when the viewport is resized, as triggered by shrink wrapping or relayout. Every time a viewport (via
RenderViewport) is laid out, the new content extents are checked by
ViewportOffset.applyContentDimensions to ensure the offset won’t change; if it does, layout must be repeated.
ViewportOffset.applyContentDimensions are called to determine if this is the case; any extents provided represent viewport slack -- how far the viewport can be scrolled in either direction beyond what is already visible. Activities are notified via
The original pixel values corresponds to certain children being visible. If the dimensions of the viewport change, the pixel offset required to maintain that same view may change. For example, consider a viewport sized to a single letter displaying “A,” “B,” and “C” in a column. When “B” is visible, pixels will correspond to “A”’s height. Suppose the viewport expands to fit the full column. Now, pixels will be zero (no offset is needed). [?]
The same is true if the viewport’s content changes size. Again, consider the aforementioned “A-B-C” scenario with “B” visible. Instead of the viewport changing size, suppose “A” is resized to be zero pixels tall. To keep “B” in view, the pixel offset must be updated (from non-zero to zero). [?]
ScrollController provides a convenient interface for interacting with one or more
ScrollPositions; in effect, it calls the corresponding method in each of its positions. As a
Listenable, the controller aggregates notifications from its positions.
ScrollNotifications are emitted by scrollable (by way of the active
ScrollActivity). As a
LayoutChangedNotification subclass, these are emitted after build and layout have already occurred, thus only painting can be performed in response without introduce jank.
Listening to a scroll position directly avoids the delay, allowing layout to be performed in response to offset changes. It’s not clear why this is faster - both paths seem to trigger at the same time [?]
ScrollPositionWithSingleContext starts and manages
ScrollActivity instances via drag,
jumpTo, and more.
ScrollActivity instances update the scroll position via
ScrollPositionWithSingleContext implements this interface and applies changes requested by the current activity (
applyUserOffset) and starts follow-on activities (
Any changes applied by the activity are processed by the scroll position, then passed back to the activity which generates scroll notifications (e.g.,
BallisticScrollActivity apply user-driven scrolling, animation-driven scrolling, and physics-driven scrolling, respectively.
ScrollPosition.beginActivity starts activities and tracks all state changes. This is possible because the scroll position is always running an activity, even when idle (
IdleScrollActivity). These state changes generate scroll notifications via the activity.
Scrollable uses a gesture recognizer to detect and track dragging if
ScrollPhysics.shouldAcceptUserOffset allows. When a drag begins, the
Scrollable’s scroll position is notified via
ScrollPositionWithSingleContext implements this method to create a
ScrollDragController which serves as an integration point for the
Scrollable, which receives drag events, and the activity, which manages scroll state / notifications. The controller is returned as a
Drag instance, which provides a mechanism to update state as events arrive.
As the user drags, the drag controller forwards a derived user offset back to
ScrollPositionWithSingleContext) which applies
ScrollPhysics.applyPhysicsToUserOffset and, if valid, invokes
ScrollActivityDelegate.setPixels. This actually updates the scroll offset and generates scroll notifications.
When the drag completes, a ballistic simulation is started via
ScrollActivityDelegate.goBallistic. This delegates to the scroll position’s
ScrollPhysics instance to determine how to react.
DragScrollActivity delegates most of its work to the drag controller and is mainly responsible for forwarding scroll notifications.
DrivenScrollActivity is much more straightforward. It starts an animation controller which, on every tick, updates the current pixel value via
setPixels. When animating, if the container over-scrolls, an idle activity is started. If the animation completes successfully, a ballistic activity is started instead.
ScrollPosition writes the current scroll offset to
ScrollPosition.keepScrollOffset is true.
ScrollView is a base class that builds a scrollable and a viewport, deferring to its subclass to specify how its slivers are constructed. The subclass overrides
buildSlivers to do this (
ScrollView.build creates the
Scrollable, which uses
ScrollView.buildViewport as its
viewportBuilder, which uses
ScrollView.buildSlivers to obtain the sliver children).