scroll_controller.dart 5.78 KB
Newer Older
1 2 3 4 5 6 7
// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'dart:async';

import 'package:flutter/animation.dart';
8
import 'package:flutter/foundation.dart';
9 10 11 12
import 'package:meta/meta.dart';

import 'scroll_position.dart';

13
class ScrollController extends ChangeNotifier {
14
  ScrollController({
15
    this.initialScrollOffset: 0.0,
16 17 18
  }) {
    assert(initialScrollOffset != null);
  }
19 20 21

  /// The initial value to use for [offset].
  ///
22 23
  /// New [ScrollPosition] objects that are created and attached to this
  /// controller will have their offset initialized to this value.
24 25
  final double initialScrollOffset;

26 27
  final List<ScrollPosition> _positions = <ScrollPosition>[];

28 29 30 31 32 33 34 35
  /// 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;

36
  ScrollPosition get position {
37 38
    assert(_positions.isNotEmpty, 'ScrollController not attached to any scroll views.');
    assert(_positions.length == 1, 'ScrollController attached to multiple scroll views.');
39
    return _positions.single;
40 41
  }

42 43
  double get offset => position.pixels;

44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
  /// 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].
  Future<Null> animateTo(double offset, {
    @required Duration duration,
    @required Curve curve,
72 73
  }) {
    assert(_positions.isNotEmpty, 'ScrollController not attached to any scroll views.');
74
    final List<Future<Null>> animations = new List<Future<Null>>(_positions.length);
75 76 77 78
    for (int i = 0; i < _positions.length; i++)
      animations[i] = _positions[i].animateTo(offset, duration: duration, curve: curve);
    return Future.wait<Null>(animations).then((List<Null> _) => null);
  }
79 80 81 82 83 84 85 86 87 88 89 90 91

  /// 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.
92 93
  void jumpTo(double value) {
    assert(_positions.isNotEmpty, 'ScrollController not attached to any scroll views.');
94 95
    for (ScrollPosition position in new List<ScrollPosition>.from(_positions))
      position.jumpTo(value);
96
  }
97 98 99 100 101 102 103 104

  /// 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);
105
    position.addListener(notifyListeners);
106 107 108 109 110 111 112 113
  }

  /// 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));
114
    position.removeListener(notifyListeners);
115 116
    _positions.remove(position);
  }
117

118 119 120 121 122 123 124
  @override
  void dispose() {
    for (ScrollPosition position in _positions)
      position.removeListener(notifyListeners);
    super.dispose();
  }

125 126 127 128 129 130 131 132 133 134 135 136
  static ScrollPosition createDefaultScrollPosition(ScrollPhysics physics, AbstractScrollState state, ScrollPosition oldPosition) {
    return new ScrollPosition(
      physics: physics,
      state: state,
      oldPosition: oldPosition,
    );
  }

  ScrollPosition createScrollPosition(ScrollPhysics physics, AbstractScrollState state, ScrollPosition oldPosition) {
    return new ScrollPosition(
      physics: physics,
      state: state,
137
      initialPixels: initialScrollOffset,
138 139 140
      oldPosition: oldPosition,
    );
  }
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157

  @override
  String toString() {
    final StringBuffer result = new StringBuffer();
    result.write('$runtimeType#$hashCode(');
    if (initialScrollOffset != 0.0)
      result.write('initialScrollOffset: ${initialScrollOffset.toStringAsFixed(1)}, ');
    if (_positions.isEmpty) {
      result.write('no clients');
    } else if (_positions.length == 1) {
      result.write('one client, offset $offset');
    } else {
      result.write('${_positions.length} clients');
    }
    result.write(')');
    return result.toString();
  }
158
}