ScrollPosition class abstract

Determines which portion of the content is visible in a scroll view.

The pixels value determines the scroll offset that the scroll view uses to select which part of its content to display. As the user scrolls the viewport, this value changes, which changes the content that is displayed.

The ScrollPosition applies physics to scrolling, and stores the minScrollExtent and maxScrollExtent.

Scrolling is controlled by the current activity, which is set by beginActivity. ScrollPosition itself does not start any activities. Instead, concrete subclasses, such as ScrollPositionWithSingleContext, typically start activities in response to user input or instructions from a ScrollController.

This object is a Listenable that notifies its listeners when pixels changes.

Accessing Scrolling Information

There are several ways to acquire information about scrolling and scrollable widgets, but each provides different types of information about the scrolling activity, the position, and the dimensions of the Viewport.

A ScrollController is a Listenable. It notifies its listeners whenever any of the attached ScrollPositions notify their listeners, such as when scrolling occurs. This is very similar to using a NotificationListener of type ScrollNotification to listen to changes in the scroll position, with the difference being that a notification listener will provide information about the scrolling activity. A notification listener can further listen to specific subclasses of ScrollNotification, like UserScrollNotification.

This sample shows the difference between using a ScrollController or a NotificationListener of type ScrollNotification to listen to scrolling activities. Toggling the Radio button switches between the two. Using a ScrollNotification will provide details about the scrolling activity, along with the metrics of the ScrollPosition, but not the scroll position object itself. By listening with a ScrollController, the position object is directly accessible. Both of these types of notifications are only triggered by scrolling.

To create a local project with this code sample, run:
flutter create --sample=widgets.ScrollPosition.1 mysample

ScrollController does not notify its listeners when the list of ScrollPositions attached to the scroll controller changes. To listen to the attaching and detaching of scroll positions to the controller, use the ScrollController.onAttach and ScrollController.onDetach methods. This is also useful for adding a listener to the ScrollPosition.isScrollingNotifier when the position is created during the build method of the Scrollable.

At the time that a scroll position is attached, the ScrollMetrics, such as the ScrollMetrics.maxScrollExtent, are not yet available. These are not determined until the Scrollable has finished laying out its contents and computing things like the full extent of that content. ScrollPosition.hasContentDimensions can be used to know when the metrics are available, or a ScrollMetricsNotification can be used, discussed further below.

This sample shows how to apply a listener to the ScrollPosition.isScrollingNotifier using ScrollController.onAttach. This is used to change the AppBar's color when scrolling is occurring.

To create a local project with this code sample, run:
flutter create --sample=widgets.ScrollPosition.2 mysample

From a different context

When needing to access scrolling information from a context that is within the scrolling widget itself, use Scrollable.of to access the ScrollableState and the ScrollableState.position. This would be the same ScrollPosition attached to a ScrollController.

When needing to access scrolling information from a context that is not an ancestor of the scrolling widget, use ScrollNotificationObserver. This is used by AppBar to create the scrolled under effect. Since Scaffold.appBar is a separate subtree from the Scaffold.body, scroll notifications would not bubble up to the app bar. Use ScrollNotificationObserverState.addListener to listen to scroll notifications happening outside of the current context.

Dimension changes

Lastly, listening to a ScrollController or a ScrollPosition will not notify when the ScrollMetrics of a given scroll position changes, such as when the window is resized, changing the dimensions of the Viewport and the previously mentioned extents of the scrollable. In order to listen to changes in scroll metrics, use a NotificationListener of type ScrollMetricsNotification. This type of notification differs from ScrollNotification, as it is not associated with the activity of scrolling, but rather the dimensions of the scrollable area, such as the window size.

This sample shows how a ScrollMetricsNotification is dispatched when the windowSize is changed. Press the floating action button to increase the scrollable window's size.

To create a local project with this code sample, run:
flutter create --sample=widgets.ScrollPosition.3 mysample

Subclassing ScrollPosition

Over time, a Scrollable might have many different ScrollPosition objects. For example, if Scrollable.physics changes type, Scrollable creates a new ScrollPosition with the new physics. To transfer state from the old instance to the new instance, subclasses implement absorb. See absorb for more details.

Subclasses also need to call didUpdateScrollDirection whenever userScrollDirection changes values.

Constructors

ScrollPosition({required ScrollPhysics physics, required ScrollContext context, bool keepScrollOffset = true, ScrollPosition? oldPosition, String? debugLabel}): Creates an object that determines which portion of the content is visible in a scroll view.

Properties

activity → ScrollActivity?: The currently operative ScrollActivity.
no setter
allowImplicitScrolling → bool: Whether a viewport is allowed to change pixels implicitly to respond to a call to RenderObject.showOnScreen.
no setteroverride
atEdge → bool: Whether the pixels value is exactly at the minScrollExtent or the maxScrollExtent.
no setterinherited
axis → Axis: The axis in which the scroll view scrolls.
no setterinherited
axisDirection → AxisDirection: The direction in which the scroll view scrolls.
no setterinherited
context → ScrollContext: Where the scrolling is taking place.
final
debugLabel → String?: A label that is used in the toString output.
final
devicePixelRatio → double: The FlutterView.devicePixelRatio of the view that the Scrollable associated with this metrics object is drawn into.
no setteroverride
extentAfter → double: The quantity of content conceptually "below" the viewport in the scrollable. This is the content below the content described by extentInside.
no setterinherited
extentBefore → double: The quantity of content conceptually "above" the viewport in the scrollable. This is the content above the content described by extentInside.
no setterinherited
extentInside → double: The quantity of content conceptually "inside" the viewport in the scrollable (including empty space if the total amount of content is less than the viewportDimension).
no setterinherited
extentTotal → double: The total quantity of content available.
no setterinherited
hasContentDimensions → bool: Whether the minScrollExtent and the maxScrollExtent properties are available.
no setteroverride
hashCode → int: The hash code for this object.
no setterinherited
hasListeners → bool: Whether any listeners are currently registered.
no setterinherited
hasPixels → bool: Whether the pixels property is available.
no setteroverride
hasViewportDimension → bool: Whether the viewportDimension property is available.
no setteroverride
haveDimensions → bool: Whether viewportDimension, minScrollExtent, maxScrollExtent, outOfRange, and atEdge are available.
no setter
isScrollingNotifier → ValueNotifier<bool>: This notifier's value is true if a scroll is underway and false if the scroll position is idle.
final
keepScrollOffset → bool: Save the current scroll offset with PageStorage and restore it if this scroll position's scrollable is recreated.
final
maxScrollExtent → double: The maximum in-range value for pixels.
no setteroverride
minScrollExtent → double: The minimum in-range value for pixels.
no setteroverride
outOfRange → bool: Whether the pixels value is outside the minScrollExtent and maxScrollExtent.
no setterinherited
physics → ScrollPhysics: How the scroll position should respond to user input.
final
pixels → double: The number of pixels to offset the children in the opposite of the axis direction.
no setteroverride
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
shouldIgnorePointer → bool: Whether scrollables should absorb pointer events at this position.
no setter
userScrollDirection → ScrollDirection: The direction in which the user is trying to change pixels, relative to the viewport's RenderViewportBase.axisDirection.
no setterinherited
viewportDimension → double: The extent of the viewport along the axisDirection.
no setteroverride

Methods

absorb(ScrollPosition other) → void: Take any current applicable state from the given ScrollPosition.
addListener(VoidCallback listener) → void: Register a closure to be called when the object changes.
inherited
animateTo(double to, {required Duration duration, required Curve curve}) → Future<void>: Animates the position from its current value to the given value.
override
applyBoundaryConditions(double value) → double: Returns the overscroll by applying the boundary conditions.
applyContentDimensions(double minScrollExtent, double maxScrollExtent) → bool: Called when the viewport's content extents are established.
override
applyNewDimensions() → void: Notifies the activity that the dimensions of the underlying viewport or contents have changed.
applyViewportDimension(double viewportDimension) → bool: Called when the viewport's extents are established.
override
beginActivity(ScrollActivity? newActivity) → void: Change the current activity, disposing of the old one and sending scroll notifications as necessary.
copyWith({double? minScrollExtent, double? maxScrollExtent, double? pixels, double? viewportDimension, AxisDirection? axisDirection, double? devicePixelRatio}) → ScrollMetrics: Creates a ScrollMetrics that has the same properties as this object.
inherited
correctBy(double correction) → void: Apply a layout-time correction to the scroll offset.
override
correctForNewDimensions(ScrollMetrics oldPosition, ScrollMetrics newPosition) → bool: Verifies that the new content and viewport dimensions are acceptable.
correctPixels(double value) → void: Change the value of pixels to the new value, without notifying any customers.
debugFillDescription(List<String> description) → void: Add additional information to the given description for use by toString.
override
didEndScroll() → void: Called by beginActivity to report when an activity has ended.
didOverscrollBy(double value) → void: Called by setPixels to report overscroll when an attempt is made to change the pixels position. Overscroll is the amount of change that was not applied to the pixels value.
didStartScroll() → void: Called by beginActivity to report when an activity has started.
didUpdateScrollDirection(ScrollDirection direction) → void: Dispatches a notification that the userScrollDirection has changed.
didUpdateScrollMetrics() → void: Dispatches a notification that the ScrollMetrics have changed.
didUpdateScrollPositionBy(double delta) → void: Called by setPixels to report a change to the pixels position.
dispose() → void: Discards any resources used by the object. After this is called, the object is not in a usable state and should be discarded (calls to addListener will throw after the object is disposed).
override
drag(DragStartDetails details, VoidCallback dragCancelCallback) → Drag: Start a drag activity corresponding to the given DragStartDetails.
ensureVisible(RenderObject object, {double alignment = 0.0, Duration duration = Duration.zero, Curve curve = Curves.ease, ScrollPositionAlignmentPolicy alignmentPolicy = ScrollPositionAlignmentPolicy.explicit, RenderObject? targetRenderObject}) → Future<void>: Animates the position such that the given object is as visible as possible by just scrolling this position.
forcePixels(double value) → void: Change the value of pixels to the new value, and notify any customers, but without honoring normal conventions for changing the scroll offset.
hold(VoidCallback holdCancelCallback) → ScrollHoldController: Stop the current activity and start a HoldScrollActivity.
jumpTo(double value) → void: Jumps the scroll position from its current value to the given value, without animation, and without checking if the new value is in range.
override
jumpToWithoutSettling(double value) → void: Deprecated. Use jumpTo or a custom ScrollPosition instead.
moveTo(double to, {Duration? duration, Curve? curve, bool? clamp = true}) → Future<void>: Calls jumpTo if duration is null or Duration.zero, otherwise animateTo is called.
override
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void: Call all the registered listeners.
override
pointerScroll(double delta) → void: Changes the scrolling position based on a pointer signal from current value to delta without animation and without checking if new value is in range, taking min/max scroll extent into account.
recommendDeferredLoading(BuildContext context) → bool: Provides a heuristic to determine if expensive frame-bound tasks should be deferred.
removeListener(VoidCallback listener) → void: Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
restoreOffset(double offset, {bool initialRestore = false}) → void: Called by context to restore the scroll offset to the provided value.
restoreScrollOffset() → void: Called whenever the ScrollPosition is created, to restore the scroll offset if possible.
saveOffset() → void: Called whenever scrolling ends, to persist the current scroll offset for state restoration purposes.
saveScrollOffset() → void: Called whenever scrolling ends, to store the current scroll offset in a storage mechanism with a lifetime that matches the app's lifetime.
setPixels(double newPixels) → double: Update the scroll position (pixels) to a given pixel value.
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited