scroll_controller.dart 15 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4 5
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'package:flutter/animation.dart';
6
import 'package:flutter/foundation.dart';
7

8 9
import 'scroll_context.dart';
import 'scroll_physics.dart';
10
import 'scroll_position.dart';
11
import 'scroll_position_with_single_context.dart';
12

13 14 15 16 17 18 19 20 21 22 23 24
/// 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 [ScrollController] and override [createScrollPosition].
///
25 26
/// A [ScrollController] is a [Listenable]. It notifies its listeners whenever
/// any of the attached [ScrollPosition]s notify _their_ listeners (i.e.
27 28
/// whenever any of them scroll). It does not notify its listeners when the list
/// of attached [ScrollPosition]s changes.
29
///
30 31 32 33 34 35 36 37 38 39 40 41
/// Typically used with [ListView], [GridView], [CustomScrollView].
///
/// See also:
///
///  * [ListView], [GridView], [CustomScrollView], which can be controlled by a
///    [ScrollController].
///  * [Scrollable], which is the lower-level widget that creates and associates
///    [ScrollPosition] objects with [ScrollController] objects.
///  * [PageController], which is an analogous object for controlling a
///    [PageView].
///  * [ScrollPosition], which manages the scroll offset for an individual
///    scrolling widget.
42
///  * [ScrollNotification] and [NotificationListener], which can be used to watch
43
///    the scroll position without using a [ScrollController].
44
class ScrollController extends ChangeNotifier {
45 46
  /// Creates a controller for a scrollable widget.
  ///
47
  /// The values of `initialScrollOffset` and `keepScrollOffset` must not be null.
48
  ScrollController({
49 50
    double initialScrollOffset = 0.0,
    this.keepScrollOffset = true,
51
    this.debugLabel,
52
  }) : assert(initialScrollOffset != null),
53 54
       assert(keepScrollOffset != null),
       _initialScrollOffset = initialScrollOffset;
55 56 57

  /// The initial value to use for [offset].
  ///
58
  /// New [ScrollPosition] objects that are created and attached to this
59 60
  /// controller will have their offset initialized to this value
  /// if [keepScrollOffset] is false or a scroll offset hasn't been saved yet.
61 62
  ///
  /// Defaults to 0.0.
63
  double get initialScrollOffset => _initialScrollOffset;
64
  final double _initialScrollOffset;
65

66 67 68 69 70 71 72 73 74 75 76 77 78
  /// Each time a scroll completes, save the current scroll [offset] with
  /// [PageStorage] and restore it if this controller's scrollable is recreated.
  ///
  /// If this property is set to false, the scroll offset is never saved
  /// and [initialScrollOffset] is always used to initialize the scroll
  /// offset. If true (the default), the initial scroll offset is used the
  /// first time the controller's scrollable is created, since there's no
  /// scroll offset to restore yet. Subsequently the saved offset is
  /// restored and [initialScrollOffset] is ignored.
  ///
  /// See also:
  ///
  ///  * [PageStorageKey], which should be used when more than one
79
  ///    scrollable appears in the same route, to distinguish the [PageStorage]
80 81 82
  ///    locations used to save scroll offsets.
  final bool keepScrollOffset;

83 84
  /// A label that is used in the [toString] output. Intended to aid with
  /// identifying scroll controller instances in debug output.
85
  final String? debugLabel;
86

87 88 89 90 91
  /// The currently attached positions.
  ///
  /// This should not be mutated directly. [ScrollPosition] objects can be added
  /// and removed using [attach] and [detach].
  Iterable<ScrollPosition> get positions => _positions;
92 93
  final List<ScrollPosition> _positions = <ScrollPosition>[];

94 95 96 97 98 99 100 101
  /// Whether any [ScrollPosition] objects have attached themselves to the
  /// [ScrollController] using the [attach] method.
  ///
  /// If this is false, then members that interact with the [ScrollPosition],
  /// such as [position], [offset], [animateTo], and [jumpTo], must not be
  /// called.
  bool get hasClients => _positions.isNotEmpty;

102 103 104 105
  /// Returns the attached [ScrollPosition], from which the actual scroll offset
  /// of the [ScrollView] can be obtained.
  ///
  /// Calling this is only valid when only a single position is attached.
106
  ScrollPosition get position {
107 108
    assert(_positions.isNotEmpty, 'ScrollController not attached to any scroll views.');
    assert(_positions.length == 1, 'ScrollController attached to multiple scroll views.');
109
    return _positions.single;
110 111
  }

112 113 114
  /// The current scroll offset of the scrollable widget.
  ///
  /// Requires the controller to be controlling exactly one scrollable widget.
115 116
  double get offset => position.pixels;

117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141
  /// Animates the position from its current value to the given value.
  ///
  /// Any active animation is canceled. If the user is currently scrolling, that
  /// action is canceled.
  ///
  /// The returned [Future] will complete when the animation ends, whether it
  /// completed successfully or whether it was interrupted prematurely.
  ///
  /// An animation will be interrupted whenever the user attempts to scroll
  /// manually, or whenever another activity is started, or whenever the
  /// animation reaches the edge of the viewport and attempts to overscroll. (If
  /// the [ScrollPosition] does not overscroll but instead allows scrolling
  /// beyond the extents, then going beyond the extents will not interrupt the
  /// animation.)
  ///
  /// The animation is indifferent to changes to the viewport or content
  /// dimensions.
  ///
  /// Once the animation has completed, the scroll position will attempt to
  /// begin a ballistic activity in case its value is not stable (for example,
  /// if it is scrolled beyond the extents and in that situation the scroll
  /// position would normally bounce back).
  ///
  /// The duration must not be zero. To jump to a particular value without an
  /// animation, use [jumpTo].
142 143 144 145
  ///
  /// When calling [animateTo] in widget tests, `await`ing the returned
  /// [Future] may cause the test to hang and timeout. Instead, use
  /// [WidgetTester.pumpAndSettle].
146 147
  Future<void> animateTo(
    double offset, {
148 149 150
    required Duration duration,
    required Curve curve,
  }) async {
151
    assert(_positions.isNotEmpty, 'ScrollController not attached to any scroll views.');
152 153 154
    await Future.wait<void>(<Future<void>>[
      for (int i = 0; i < _positions.length; i += 1) _positions[i].animateTo(offset, duration: duration, curve: curve),
    ]);
155
  }
156 157 158 159 160 161 162 163 164 165 166 167 168

  /// Jumps the scroll position from its current value to the given value,
  /// without animation, and without checking if the new value is in range.
  ///
  /// Any active animation is canceled. If the user is currently scrolling, that
  /// action is canceled.
  ///
  /// If this method changes the scroll position, a sequence of start/update/end
  /// scroll notifications will be dispatched. No overscroll notifications can
  /// be generated by this method.
  ///
  /// Immediately after the jump, a ballistic activity is started, in case the
  /// value was out of range.
169 170
  void jumpTo(double value) {
    assert(_positions.isNotEmpty, 'ScrollController not attached to any scroll views.');
171
    for (final ScrollPosition position in List<ScrollPosition>.of(_positions)) {
172
      position.jumpTo(value);
173
    }
174
  }
175 176 177 178 179 180 181 182

  /// Register the given position with this controller.
  ///
  /// After this function returns, the [animateTo] and [jumpTo] methods on this
  /// controller will manipulate the given position.
  void attach(ScrollPosition position) {
    assert(!_positions.contains(position));
    _positions.add(position);
183
    position.addListener(notifyListeners);
184 185 186 187 188 189 190 191
  }

  /// Unregister the given position with this controller.
  ///
  /// After this function returns, the [animateTo] and [jumpTo] methods on this
  /// controller will not manipulate the given position.
  void detach(ScrollPosition position) {
    assert(_positions.contains(position));
192
    position.removeListener(notifyListeners);
193 194
    _positions.remove(position);
  }
195

196 197
  @override
  void dispose() {
198
    for (final ScrollPosition position in _positions) {
199
      position.removeListener(notifyListeners);
200
    }
201 202 203
    super.dispose();
  }

204 205 206 207 208 209 210 211 212
  /// Creates a [ScrollPosition] for use by a [Scrollable] widget.
  ///
  /// Subclasses can override this function to customize the [ScrollPosition]
  /// used by the scrollable widgets they control. For example, [PageController]
  /// overrides this function to return a page-oriented scroll position
  /// subclass that keeps the same page visible when the scrollable widget
  /// resizes.
  ///
  /// By default, returns a [ScrollPositionWithSingleContext].
213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229
  ///
  /// The arguments are generally passed to the [ScrollPosition] being created:
  ///
  ///  * `physics`: An instance of [ScrollPhysics] that determines how the
  ///    [ScrollPosition] should react to user interactions, how it should
  ///    simulate scrolling when released or flung, etc. The value will not be
  ///    null. It typically comes from the [ScrollView] or other widget that
  ///    creates the [Scrollable], or, if none was provided, from the ambient
  ///    [ScrollConfiguration].
  ///  * `context`: A [ScrollContext] used for communicating with the object
  ///    that is to own the [ScrollPosition] (typically, this is the
  ///    [Scrollable] itself).
  ///  * `oldPosition`: If this is not the first time a [ScrollPosition] has
  ///    been created for this [Scrollable], this will be the previous instance.
  ///    This is used when the environment has changed and the [Scrollable]
  ///    needs to recreate the [ScrollPosition] object. It is null the first
  ///    time the [ScrollPosition] is created.
230
  ScrollPosition createScrollPosition(
231 232
    ScrollPhysics physics,
    ScrollContext context,
233
    ScrollPosition? oldPosition,
234
  ) {
235
    return ScrollPositionWithSingleContext(
236
      physics: physics,
237
      context: context,
238
      initialPixels: initialScrollOffset,
239
      keepScrollOffset: keepScrollOffset,
240
      oldPosition: oldPosition,
241
      debugLabel: debugLabel,
242 243
    );
  }
244 245 246

  @override
  String toString() {
247 248
    final List<String> description = <String>[];
    debugFillDescription(description);
249
    return '${describeIdentity(this)}(${description.join(", ")})';
250 251
  }

252 253 254 255 256 257 258
  /// Add additional information to the given description for use by [toString].
  ///
  /// This method makes it easier for subclasses to coordinate to provide a
  /// high-quality [toString] implementation. The [toString] implementation on
  /// the [ScrollController] base class calls [debugFillDescription] to collect
  /// useful information from subclasses to incorporate into its return value.
  ///
259 260
  /// Implementations of this method should start with a call to the inherited
  /// method, as in `super.debugFillDescription(description)`.
261 262
  @mustCallSuper
  void debugFillDescription(List<String> description) {
263
    if (debugLabel != null) {
264
      description.add(debugLabel!);
265 266
    }
    if (initialScrollOffset != 0.0) {
267
      description.add('initialScrollOffset: ${initialScrollOffset.toStringAsFixed(1)}, ');
268
    }
269
    if (_positions.isEmpty) {
270
      description.add('no clients');
271
    } else if (_positions.length == 1) {
272
      // Don't actually list the client itself, since its toString may refer to us.
273
      description.add('one client, offset ${offset.toStringAsFixed(1)}');
274
    } else {
275
      description.add('${_positions.length} clients');
276 277
    }
  }
278
}
279 280

// Examples can assume:
281
// TrackingScrollController? _trackingScrollController;
282

283
/// A [ScrollController] whose [initialScrollOffset] tracks its most recently
284 285 286 287 288 289 290
/// updated [ScrollPosition].
///
/// This class can be used to synchronize the scroll offset of two or more
/// lazily created scroll views that share a single [TrackingScrollController].
/// It tracks the most recently updated scroll position and reports it as its
/// `initialScrollOffset`.
///
291
/// {@tool snippet}
292 293
///
/// In this example each [PageView] page contains a [ListView] and all three
294 295 296
/// [ListView]'s share a [TrackingScrollController]. The scroll offsets of all
/// three list views will track each other, to the extent that's possible given
/// the different list lengths.
297 298
///
/// ```dart
299
/// PageView(
300
///   children: <Widget>[
301
///     ListView(
302
///       controller: _trackingScrollController,
303
///       children: List<Widget>.generate(100, (int i) => Text('page 0 item $i')).toList(),
304
///     ),
305 306 307 308 309
///     ListView(
///       controller: _trackingScrollController,
///       children: List<Widget>.generate(200, (int i) => Text('page 1 item $i')).toList(),
///     ),
///     ListView(
310
///      controller: _trackingScrollController,
311
///      children: List<Widget>.generate(300, (int i) => Text('page 2 item $i')).toList(),
312 313 314 315
///     ),
///   ],
/// )
/// ```
316
/// {@end-tool}
317 318 319 320
///
/// In this example the `_trackingController` would have been created by the
/// stateful widget that built the widget tree.
class TrackingScrollController extends ScrollController {
321 322
  /// Creates a scroll controller that continually updates its
  /// [initialScrollOffset] to match the last scroll notification it received.
323
  TrackingScrollController({
324 325 326 327
    super.initialScrollOffset,
    super.keepScrollOffset,
    super.debugLabel,
  });
328

329
  final Map<ScrollPosition, VoidCallback> _positionToListener = <ScrollPosition, VoidCallback>{};
330 331
  ScrollPosition? _lastUpdated;
  double? _lastUpdatedOffset;
332 333

  /// The last [ScrollPosition] to change. Returns null if there aren't any
334 335
  /// attached scroll positions, or there hasn't been any scrolling yet, or the
  /// last [ScrollPosition] to change has since been removed.
336
  ScrollPosition? get mostRecentlyUpdatedPosition => _lastUpdated;
337

338 339 340 341 342 343
  /// Returns the scroll offset of the [mostRecentlyUpdatedPosition] or, if that
  /// is null, the initial scroll offset provided to the constructor.
  ///
  /// See also:
  ///
  ///  * [ScrollController.initialScrollOffset], which this overrides.
344
  @override
345
  double get initialScrollOffset => _lastUpdatedOffset ?? super.initialScrollOffset;
346 347 348 349 350

  @override
  void attach(ScrollPosition position) {
    super.attach(position);
    assert(!_positionToListener.containsKey(position));
351 352 353 354
    _positionToListener[position] = () {
      _lastUpdated = position;
      _lastUpdatedOffset = position.pixels;
    };
355
    position.addListener(_positionToListener[position]!);
356 357 358 359 360 361
  }

  @override
  void detach(ScrollPosition position) {
    super.detach(position);
    assert(_positionToListener.containsKey(position));
362
    position.removeListener(_positionToListener[position]!);
363
    _positionToListener.remove(position);
364
    if (_lastUpdated == position) {
365
      _lastUpdated = null;
366 367
    }
    if (_positionToListener.isEmpty) {
368
      _lastUpdatedOffset = null;
369
    }
370 371 372 373
  }

  @override
  void dispose() {
374
    for (final ScrollPosition position in positions) {
375
      assert(_positionToListener.containsKey(position));
376
      position.removeListener(_positionToListener[position]!);
377 378 379 380
    }
    super.dispose();
  }
}