Scrollableprovides the interaction model for scrolling without specifying how the actual viewport is managed (a
ViewportBuildermust be provided). UI concerns are customized directly or via an inherited
ScrollConfigurationthat exposes an immutable
ScrollBehaviorinstance. 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.
ScrollPhysicsis 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.
ScrollController. This controller is responsible for producing the
ScrollPositionfrom a given
ScrollPhysics; it also provides the
- For example,
PageViewinjects a page-based scrolling mechanism by having its
PageController) return a custom scroll position subclass.
ScrollContextexposes build contexts for notifications and storage, a ticker provider for animations, and methods to interact with the scrollable; its analogous to
BuildContextfor an entire scrollable widget.
ScrollPositiontracks scroll offset as pixels (reporting changes via
Listenable), applies physics to interactions via
ScrollPhysics, and through subclasses like
ScrollActivityDelegateand makes concrete much of the actual scrolling machinery), starts and stops
ScrollActivityinstances 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.applyContentDimensionsto ensure the offset won’t change; if it does, layout must be repeated.
ViewportOffset.applyContentDimensionsare 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). [?]
ScrollControllerprovides 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.
ScrollNotificationsare emitted by scrollable (by way of the active
ScrollActivity). As a
LayoutChangedNotificationsubclass, 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 [?]
ScrollPositionWithSingleContextstarts and manages
ScrollActivityinstances via drag,
jumpTo, and more.
ScrollActivityinstances update the scroll position via
ScrollPositionWithSingleContextimplements 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.,
BallisticScrollActivityapply user-driven scrolling, animation-driven scrolling, and physics-driven scrolling, respectively.
ScrollPosition.beginActivitystarts 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.
- The underlying
Scrollableuses a gesture recognizer to detect and track dragging if
ScrollPhysics.shouldAcceptUserOffsetallows. When a drag begins, the
Scrollable’s scroll position is notified via
ScrollPositionWithSingleContextimplements this method to create a
ScrollDragControllerwhich 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
Draginstance, 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.applyPhysicsToUserOffsetand, 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
ScrollPhysicsinstance to determine how to react.
- Interestingly, the
DragScrollActivitydelegates most of its work to the drag controller and is mainly responsible for forwarding scroll notifications.
DrivenScrollActivityis 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.
ScrollPositionwrites the current scroll offset to
ScrollViewis a base class that builds a scrollable and a viewport, deferring to its subclass to specify how its slivers are constructed. The subclass overrides
buildSliversto do this (
Scrollable, which uses
viewportBuilder, which uses
ScrollView.buildSliversto obtain the sliver children).