RangeMaintainingScrollPhysics class

Scroll physics that attempt to keep the scroll position in range when the contents change dimensions suddenly.

This attempts to maintain the amount of overscroll or underscroll already present, if the scroll position is already out of range and the extents have decreased, meaning that some content was removed. The reason for this condition is that when new content is added, keeping the same overscroll would mean that instead of showing it to the user, all of it is being skipped by jumping right to the max extent.

If the scroll activity is animating the scroll position, sudden changes to the scroll dimensions are allowed to happen (so as to prevent animations from jumping back and forth between in-range and out-of-range values).

These physics should be combined with other scroll physics, e.g. BouncingScrollPhysics or ClampingScrollPhysics, to obtain a complete description of typical scroll physics. See applyTo.

Implementation details

Specifically, these physics perform two adjustments.

The first is to maintain overscroll when the position is out of range.

The second is to enforce the boundary when the position is in range.

If the current velocity is non-zero, neither adjustment is made. The assumption is that there is an ongoing animation and therefore further changing the scroll position would disrupt the experience.

If the extents haven't changed, then the overscroll adjustment is not made. The assumption is that if the position is overscrolled, it is intentional, otherwise the position could not have reached that position. (Consider ClampingScrollPhysics vs BouncingScrollPhysics for example.)

If the position itself changed since the last animation frame, then the overscroll is not maintained. The assumption is similar to the previous case: the position would not have been placed out of range unless it was intentional.

In addition, if the position changed and the boundaries were and still are finite, then the boundary isn't enforced either, for the same reason. However, if any of the boundaries were or are now infinite, the boundary is enforced, on the assumption that infinite boundaries indicate a lazy-loading scroll view, which cannot enforce boundaries while the full list has not loaded.

If the range was out of range, then the boundary is not enforced even if the range is not maintained. If the range is maintained, then the distance between the old position and the old boundary is applied to the new boundary to obtain the new position.

If the range was in range, and the boundary is to be enforced, then the new position is obtained by deferring to the other physics, if any, and then clamped to the new range.



RangeMaintainingScrollPhysics({ScrollPhysics? parent})
Creates scroll physics that maintain the scroll position in range.


allowImplicitScrolling bool
Whether a viewport is allowed to change its scroll position implicitly in response to a call to RenderObject.showOnScreen.
no setterinherited
allowUserScrolling bool
Whether a viewport is allowed to change the scroll position as the result of user input.
no setterinherited
dragStartDistanceMotionThreshold double?
The minimum amount of pixel distance drags must move by to start motion the first time or after each time the drag motion stopped.
no setterinherited
hashCode int
The hash code for this object.
no setterinherited
maxFlingVelocity double
Scroll fling velocity magnitudes will be clamped to this value.
no setterinherited
minFlingDistance double
The minimum distance an input pointer drag must have moved to be considered a scroll fling gesture.
no setterinherited
minFlingVelocity double
The minimum velocity for an input pointer drag to be considered a scroll fling.
no setterinherited
parent ScrollPhysics?
If non-null, determines the default behavior for each method.
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
spring SpringDescription
The spring to use for ballistic simulations.
no setterinherited
tolerance Tolerance
Deprecated. Call toleranceFor instead.
no setterinherited


adjustPositionForNewDimensions({required ScrollMetrics oldPosition, required ScrollMetrics newPosition, required bool isScrolling, required double velocity}) double
Describes what the scroll position should be given new viewport dimensions.
applyBoundaryConditions(ScrollMetrics position, double value) double
Determines the overscroll by applying the boundary conditions.
applyPhysicsToUserOffset(ScrollMetrics position, double offset) double
Used by DragScrollActivity and other user-driven activities to convert an offset in logical pixels as provided by the DragUpdateDetails into a delta to apply (subtract from the current position) using ScrollActivityDelegate.setPixels.
applyTo(ScrollPhysics? ancestor) RangeMaintainingScrollPhysics
Combines this ScrollPhysics instance with the given physics.
buildParent(ScrollPhysics? ancestor) ScrollPhysics?
If parent is null then return ancestor, otherwise recursively build a ScrollPhysics that has ancestor as its parent.
carriedMomentum(double existingVelocity) double
Returns the velocity carried on repeated flings.
createBallisticSimulation(ScrollMetrics position, double velocity) Simulation?
Returns a simulation for ballistic scrolling starting from the given position with the given velocity.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
recommendDeferredLoading(double velocity, ScrollMetrics metrics, BuildContext context) bool
Provides a heuristic to determine if expensive frame-bound tasks should be deferred.
shouldAcceptUserOffset(ScrollMetrics position) bool
Whether the scrollable should let the user adjust the scroll offset, for example by dragging. If allowUserScrolling is false, the scrollable will never allow user input to change the scroll position.
toleranceFor(ScrollMetrics metrics) Tolerance
The tolerance to use for ballistic simulations.
toString() String
A string representation of this object.


operator ==(Object other) bool
The equality operator.