# Scrollable

## What are the building blocks of scrolling?

* `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 `ScrollContext` and `ScrollPhysics`; it also provides the `initialScrollOffset`.
  * For example, `PageView` injects a page-based scrolling mechanism by having its `ScrollController` (`PageController`) return a custom scroll position subclass.
* The `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 `ViewportOffset` superclass.
  * 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 (`extentBefore`, `extentAfter`), the pixel offset corresponding to the top and bottom of the current viewport (`minScrollExtent`, `maxScrollExtent`) and the viewport size (`viewportDimension`).
  * 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.applyViewportDimension` and `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 `ScrollActivity.applyNewDimensions`().
    * 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 \[?]

## How is the scroll position updated in general?

* The `ScrollPositionWithSingleContext` starts and manages `ScrollActivity` instances via drag, `animateTo`, `jumpTo`, and more.
* `ScrollActivity` instances update the scroll position via `ScrollActivityDelegate`; `ScrollPositionWithSingleContext` implements this interface and applies changes requested by the current activity (`setPixels`, `applyUserOffset`) and starts follow-on activities (`goIdle`, `goBalastic`).
* Any changes applied by the activity are processed by the scroll position, then passed back to the activity which generates scroll notifications (e.g., `dispatchScrollUpdateNotification`).
* `DragScrollActivity`, `DrivenScrollActivity`, and `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.

## How is the scroll position updated by dragging?

* The underlying `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 `ScrollPosition.drag`.
* `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 `ScrollActivityDelegate.applyUserOffset` (`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.
* Interestingly, the `DragScrollActivity` delegates most of its work to the drag controller and is mainly responsible for forwarding scroll notifications.

## How is the scroll position updated by `animateTo`?

* The `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.

## How is scrolling behavior and state managed?

* `The` `ScrollPosition` writes the current scroll offset to `PageStorage` if `ScrollPosition.keepScrollOffset` is true.

## How are the scrollable, the viewport, and any contained slivers associated?

* `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).