CupertinoSliverRefreshControl class

A sliver widget implementing the iOS-style pull to refresh content control.

When inserted as the first sliver in a scroll view or behind other slivers that still lets the scrollable overscroll in front of this sliver (such as the CupertinoSliverNavigationBar, this widget will:

Let the user draw inside the overscrolled area via the passed in builder.
Trigger the provided onRefresh function when overscrolled far enough to pass refreshTriggerPullDistance.
Continue to hold refreshIndicatorExtent amount of space for the builder to keep drawing inside of as the Future returned by onRefresh processes.
Scroll away once the onRefresh Future completes.

The builder function will be informed of the current RefreshIndicatorMode when invoking it, except in the RefreshIndicatorMode.inactive state when no space is available and nothing needs to be built. The builder function will otherwise be continuously invoked as the amount of space available changes from overscroll, as the sliver scrolls away after the onRefresh task is done, etc.

Only one refresh can be triggered until the previous refresh has completed and the indicator sliver has retracted at least 90% of the way back.

Can only be used in downward-scrolling vertical lists that overscrolls. In other words, refreshes can't be triggered with Scrollables using ClampingScrollPhysics which is the default on Android. To allow overscroll on Android, use an overscrolling physics such as BouncingScrollPhysics. This can be done via:

Providing a BouncingScrollPhysics (possibly in combination with a AlwaysScrollableScrollPhysics) while constructing the scrollable.
By inserting a ScrollConfiguration with BouncingScrollPhysics above the scrollable.
By using CupertinoApp, which always uses a ScrollConfiguration with BouncingScrollPhysics regardless of platform.

In a typical application, this sliver should be inserted between the app bar sliver such as CupertinoSliverNavigationBar and your main scrollable content's sliver.

When the user scrolls past refreshTriggerPullDistance, this sample shows the default iOS pull to refresh indicator for 1 second and adds a new item to the top of the list view.

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

Constructors

CupertinoSliverRefreshControl({Key? key, double refreshTriggerPullDistance = _defaultRefreshTriggerPullDistance, double refreshIndicatorExtent = _defaultRefreshIndicatorExtent, RefreshControlIndicatorBuilder? builder = buildRefreshIndicator, RefreshCallback? onRefresh}): Create a new refresh control for inserting into a list of slivers.
const

Properties

builder → RefreshControlIndicatorBuilder?: A builder that's called as this sliver's size changes, and as the state changes.
final
hashCode → int: The hash code for this object.
no setterinherited
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
onRefresh → RefreshCallback?: Callback invoked when pulled by refreshTriggerPullDistance.
final
refreshIndicatorExtent → double: The amount of space the refresh indicator sliver will keep holding while onRefresh's Future is still running.
final
refreshTriggerPullDistance → double: The amount of overscroll the scrollable must be dragged to trigger a reload.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

createElement() → StatefulElement: Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<CupertinoSliverRefreshControl>: Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String: A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a one-line detailed description of the object.
inherited
toStringShort() → String: A short, textual description of this widget.
inherited

Operators

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

Static Methods

buildRefreshIndicator(BuildContext context, RefreshIndicatorMode refreshState, double pulledExtent, double refreshTriggerPullDistance, double refreshIndicatorExtent) → Widget: Builds a refresh indicator that reflects the standard iOS pull-to-refresh behavior. Specifically, this entails presenting an activity indicator that changes depending on the current refreshState. As the user initially drags down, the indicator will gradually reveal individual ticks until the refresh becomes armed. At this point, the animated activity indicator will begin rotating. Once the refresh has completed, the activity indicator shrinks away as the space allocation animates back to closed.
state(BuildContext context) → RefreshIndicatorMode: Retrieve the current state of the CupertinoSliverRefreshControl. The same as the state that gets passed into the builder function. Used for testing.