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

import 'package:flutter/gestures.dart';
import 'package:flutter/rendering.dart';

8
import 'framework.dart';
9
import 'notification_listener.dart';
10
import 'scroll_metrics.dart';
11

12 13 14
/// Mixin for [Notification]s that track how many [RenderAbstractViewport] they
/// have bubbled through.
///
Adam Barth's avatar
Adam Barth committed
15
/// This is used by [ScrollNotification] and [OverscrollIndicatorNotification].
16
mixin ViewportNotificationMixin on Notification {
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
  /// The number of viewports that this notification has bubbled through.
  ///
  /// Typically listeners only respond to notifications with a [depth] of zero.
  ///
  /// Specifically, this is the number of [Widget]s representing
  /// [RenderAbstractViewport] render objects through which this notification
  /// has bubbled.
  int get depth => _depth;
  int _depth = 0;

  @override
  bool visitAncestor(Element element) {
    if (element is RenderObjectElement && element.renderObject is RenderAbstractViewport)
      _depth += 1;
    return super.visitAncestor(element);
  }

  @override
  void debugFillDescription(List<String> description) {
    super.debugFillDescription(description);
    description.add('depth: $depth (${ depth == 0 ? "local" : "remote"})');
  }
}

41 42 43 44 45 46 47 48 49 50 51 52 53 54
/// A [Notification] related to scrolling.
///
/// [Scrollable] widgets notify their ancestors about scrolling-related changes.
/// The notifications have the following lifecycle:
///
///  * A [ScrollStartNotification], which indicates that the widget has started
///    scrolling.
///  * Zero or more [ScrollUpdateNotification]s, which indicate that the widget
///    has changed its scroll position, mixed with zero or more
///    [OverscrollNotification]s, which indicate that the widget has not changed
///    its scroll position because the change would have caused its scroll
///    position to go outside its scroll bounds.
///  * Interspersed with the [ScrollUpdateNotification]s and
///    [OverscrollNotification]s are zero or more [UserScrollNotification]s,
55
///    which indicate that the user has changed the direction in which they are
56 57 58
///    scrolling.
///  * A [ScrollEndNotification], which indicates that the widget has stopped
///    scrolling.
59
///  * A [UserScrollNotification], with a [UserScrollNotification.direction] of
60 61 62 63 64 65 66
///    [ScrollDirection.idle].
///
/// Notifications bubble up through the tree, which means a given
/// [NotificationListener] will receive notifications for all descendant
/// [Scrollable] widgets. To focus on notifications from the nearest
/// [Scrollable] descendant, check that the [depth] property of the notification
/// is zero.
67 68 69 70 71 72 73 74 75 76 77 78
///
/// When a scroll notification is received by a [NotificationListener], the
/// listener will have already completed build and layout, and it is therefore
/// too late for that widget to call [State.setState]. Any attempt to adjust the
/// build or layout based on a scroll notification would result in a layout that
/// lagged one frame behind, which is a poor user experience. Scroll
/// notifications are therefore primarily useful for paint effects (since paint
/// happens after layout). The [GlowingOverscrollIndicator] and [Scrollbar]
/// widgets are examples of paint effects that use scroll notifications.
///
/// To drive layout based on the scroll position, consider listening to the
/// [ScrollPosition] directly (or indirectly via a [ScrollController]).
Adam Barth's avatar
Adam Barth committed
79
abstract class ScrollNotification extends LayoutChangedNotification with ViewportNotificationMixin {
80
  /// Initializes fields for subclasses.
Adam Barth's avatar
Adam Barth committed
81
  ScrollNotification({
82 83
    required this.metrics,
    required this.context,
84
  });
85

86
  /// A description of a [Scrollable]'s contents, useful for modeling the state
87
  /// of its viewport.
88
  final ScrollMetrics metrics;
89

90
  /// The build context of the widget that fired this notification.
91 92 93
  ///
  /// This can be used to find the scrollable's render objects to determine the
  /// size of the viewport, for instance.
94
  final BuildContext? context;
95 96 97 98

  @override
  void debugFillDescription(List<String> description) {
    super.debugFillDescription(description);
99
    description.add('$metrics');
100 101 102
  }
}

103 104 105 106 107 108
/// A notification that a [Scrollable] widget has started scrolling.
///
/// See also:
///
///  * [ScrollEndNotification], which indicates that scrolling has stopped.
///  * [ScrollNotification], which describes the notification lifecycle.
Adam Barth's avatar
Adam Barth committed
109
class ScrollStartNotification extends ScrollNotification {
110
  /// Creates a notification that a [Scrollable] widget has started scrolling.
111
  ScrollStartNotification({
112 113
    required ScrollMetrics metrics,
    required BuildContext? context,
114
    this.dragDetails,
115
  }) : super(metrics: metrics, context: context);
116

117 118 119 120
  /// If the [Scrollable] started scrolling because of a drag, the details about
  /// that drag start.
  ///
  /// Otherwise, null.
121
  final DragStartDetails? dragDetails;
122 123 124 125 126 127 128 129 130

  @override
  void debugFillDescription(List<String> description) {
    super.debugFillDescription(description);
    if (dragDetails != null)
      description.add('$dragDetails');
  }
}

131 132 133 134 135 136 137 138
/// A notification that a [Scrollable] widget has changed its scroll position.
///
/// See also:
///
///  * [OverscrollNotification], which indicates that a [Scrollable] widget
///    has not changed its scroll position because the change would have caused
///    its scroll position to go outside its scroll bounds.
///  * [ScrollNotification], which describes the notification lifecycle.
Adam Barth's avatar
Adam Barth committed
139
class ScrollUpdateNotification extends ScrollNotification {
140 141
  /// Creates a notification that a [Scrollable] widget has changed its scroll
  /// position.
142
  ScrollUpdateNotification({
143 144
    required ScrollMetrics metrics,
    required BuildContext context,
145 146
    this.dragDetails,
    this.scrollDelta,
147
  }) : super(metrics: metrics, context: context);
148

149 150 151 152
  /// If the [Scrollable] changed its scroll position because of a drag, the
  /// details about that drag update.
  ///
  /// Otherwise, null.
153
  final DragUpdateDetails? dragDetails;
154

Adam Barth's avatar
Adam Barth committed
155
  /// The distance by which the [Scrollable] was scrolled, in logical pixels.
156
  final double? scrollDelta;
157 158 159 160 161 162 163 164 165 166

  @override
  void debugFillDescription(List<String> description) {
    super.debugFillDescription(description);
    description.add('scrollDelta: $scrollDelta');
    if (dragDetails != null)
      description.add('$dragDetails');
  }
}

167 168 169 170 171 172 173 174 175
/// A notification that a [Scrollable] widget has not changed its scroll position
/// because the change would have caused its scroll position to go outside of
/// its scroll bounds.
///
/// See also:
///
///  * [ScrollUpdateNotification], which indicates that a [Scrollable] widget
///    has changed its scroll position.
///  * [ScrollNotification], which describes the notification lifecycle.
Adam Barth's avatar
Adam Barth committed
176
class OverscrollNotification extends ScrollNotification {
177 178
  /// Creates a notification that a [Scrollable] widget has changed its scroll
  /// position outside of its scroll bounds.
179
  OverscrollNotification({
180 181
    required ScrollMetrics metrics,
    required BuildContext context,
182
    this.dragDetails,
183
    required this.overscroll,
184
    this.velocity = 0.0,
185 186 187 188 189
  }) : assert(overscroll != null),
       assert(overscroll.isFinite),
       assert(overscroll != 0.0),
       assert(velocity != null),
       super(metrics: metrics, context: context);
190

191 192 193 194
  /// If the [Scrollable] overscrolled because of a drag, the details about that
  /// drag update.
  ///
  /// Otherwise, null.
195
  final DragUpdateDetails? dragDetails;
196

Adam Barth's avatar
Adam Barth committed
197
  /// The number of logical pixels that the [Scrollable] avoided scrolling.
198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220
  ///
  /// This will be negative for overscroll on the "start" side and positive for
  /// overscroll on the "end" side.
  final double overscroll;

  /// The velocity at which the [ScrollPosition] was changing when this
  /// overscroll happened.
  ///
  /// This will typically be 0.0 for touch-driven overscrolls, and positive
  /// for overscrolls that happened from a [BallisticScrollActivity] or
  /// [DrivenScrollActivity].
  final double velocity;

  @override
  void debugFillDescription(List<String> description) {
    super.debugFillDescription(description);
    description.add('overscroll: ${overscroll.toStringAsFixed(1)}');
    description.add('velocity: ${velocity.toStringAsFixed(1)}');
    if (dragDetails != null)
      description.add('$dragDetails');
  }
}

221 222 223 224 225 226
/// A notification that a [Scrollable] widget has stopped scrolling.
///
/// See also:
///
///  * [ScrollStartNotification], which indicates that scrolling has started.
///  * [ScrollNotification], which describes the notification lifecycle.
Adam Barth's avatar
Adam Barth committed
227
class ScrollEndNotification extends ScrollNotification {
228
  /// Creates a notification that a [Scrollable] widget has stopped scrolling.
229
  ScrollEndNotification({
230 231
    required ScrollMetrics metrics,
    required BuildContext context,
232
    this.dragDetails,
233
  }) : super(metrics: metrics, context: context);
234

235 236 237 238 239 240 241 242
  /// If the [Scrollable] stopped scrolling because of a drag, the details about
  /// that drag end.
  ///
  /// Otherwise, null.
  ///
  /// If a drag ends with some residual velocity, a typical [ScrollPhysics] will
  /// start a ballistic scroll, which delays the [ScrollEndNotification] until
  /// the ballistic simulation completes, at which time [dragDetails] will
243
  /// be null. If the residual velocity is too small to trigger ballistic
244 245
  /// scrolling, then the [ScrollEndNotification] will be dispatched immediately
  /// and [dragDetails] will be non-null.
246
  final DragEndDetails? dragDetails;
247 248 249 250 251 252 253 254 255

  @override
  void debugFillDescription(List<String> description) {
    super.debugFillDescription(description);
    if (dragDetails != null)
      description.add('$dragDetails');
  }
}

256 257 258 259 260 261
/// A notification that the user has changed the direction in which they are
/// scrolling.
///
/// See also:
///
///  * [ScrollNotification], which describes the notification lifecycle.
Adam Barth's avatar
Adam Barth committed
262
class UserScrollNotification extends ScrollNotification {
263 264
  /// Creates a notification that the user has changed the direction in which
  /// they are scrolling.
265
  UserScrollNotification({
266 267 268
    required ScrollMetrics metrics,
    required BuildContext context,
    required this.direction,
269
  }) : super(metrics: metrics, context: context);
270

271
  /// The direction in which the user is scrolling.
272 273 274 275 276 277 278 279
  final ScrollDirection direction;

  @override
  void debugFillDescription(List<String> description) {
    super.debugFillDescription(description);
    description.add('direction: $direction');
  }
}
280 281 282

/// A predicate for [ScrollNotification], used to customize widgets that
/// listen to notifications from their children.
283
typedef ScrollNotificationPredicate = bool Function(ScrollNotification notification);
284

285
/// A [ScrollNotificationPredicate] that checks whether
286
/// `notification.depth == 0`, which means that the notification did not bubble
287 288 289 290
/// through any intervening scrolling widgets.
bool defaultScrollNotificationPredicate(ScrollNotification notification) {
  return notification.depth == 0;
}