CrossScrollController class

Controls a scrollable widget.

Scroll controllers are typically stored as member variables in State objects and are reused in each State.build. A single scroll controller can be used to control multiple scrollable widgets, but some operations, such as reading the scroll offset, require the controller to be used with a single scrollable widget.

A scroll controller creates a ScrollPosition to manage the state specific to an individual Scrollable widget. To use a custom ScrollPosition, subclass CrossScrollController and override createScrollPosition.

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.

{@tool dartpad} 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.

** See code in examples/api/lib/widgets/scroll_position/scroll_controller_notification.0.dart ** {@end-tool}

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.

{@tool dartpad} 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.

** See code in examples/api/lib/widgets/scroll_position/scroll_controller_on_attach.0.dart ** {@end-tool}

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.

{@tool dartpad} 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.

** See code in examples/api/lib/widgets/scroll_position/scroll_metrics_notification.0.dart ** {@end-tool}

Typically used with ListView, GridView, CustomScrollView.

Constructors

CrossScrollController({Offset initialScrollOffset = const Offset(0.0, 0.0), bool keepScrollOffset = true, String? debugLabel, ScrollControllerCallback? onAttach, ScrollControllerCallback? onDetach})

Properties

debugLabel → String?: final
hasClients → bool: Check both Positions
no setter
hashCode → int: The hash code for this object.
no setterinherited
hasListeners → bool: Whether any listeners are currently registered.
no setterinherited
hCont ↔ ScrollController: getter/setter pair
initialScrollOffset → Offset: no setter
keepScrollOffset → bool: final
offsetX → double: The current scroll offset of the scrollable widget.
no setter
offsetY → double: no setter
onAttach → ScrollControllerCallback?: final
onDetach → ScrollControllerCallback?: final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
size ↔ Size: cell Size
getter/setter pair
vCont ↔ ScrollController: getter/setter pair
xPosition → ScrollPosition: no setter
xPositions → Iterable<ScrollPosition>: no setter
yPosition → ScrollPosition: no setter
yPositions → Iterable<ScrollPosition>: no setter

Methods

addListener(VoidCallback listener) → void: Register a closure to be called when the object changes.
inherited
animateXTo(double offset, {required Duration duration, required Curve curve}) → Future<void>: Animates the position from its current value to the given value.
animateYTo(double offset, {required Duration duration, required Curve curve}) → Future<void>
attachX(ScrollPosition position) → void: Register the given position with this controller.
attachY(ScrollPosition position) → void
createXScrollPosition(ScrollPhysics physics, ScrollContext context, ScrollPosition? oldPosition) → ScrollPosition: Creates a ScrollPosition for use by a Scrollable widget.
createYScrollPosition(ScrollPhysics physics, ScrollContext context, ScrollPosition? oldPosition) → ScrollPosition
detachX(ScrollPosition position) → void: Unregister the given position with this controller.
detachY(ScrollPosition position) → void
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
init({required ScrollController h, required ScrollController v, required Size cellSize}) → void: Initialize Data
jumpXTo(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.
jumpYTo(double value) → void
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void: Call all the registered listeners.
inherited
removeListener(VoidCallback listener) → void: Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
toString() → String: A string representation of this object.
inherited
xDebugFillDescription(List<String> description) → void
yDebugFillDescription(List<String> description) → void

Operators

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