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

5
import 'dart:async';
6
import 'dart:math' as math;
7
import 'dart:ui';
8

9
import 'package:flutter/gestures.dart';
10
import 'package:flutter/rendering.dart';
11
import 'package:flutter/scheduler.dart';
12
import 'package:flutter/painting.dart';
13

14
import 'actions.dart';
15
import 'basic.dart';
16
import 'focus_manager.dart';
17 18
import 'framework.dart';
import 'gesture_detector.dart';
19
import 'notification_listener.dart';
20
import 'scroll_configuration.dart';
21
import 'scroll_context.dart';
22
import 'scroll_controller.dart';
23
import 'scroll_metrics.dart';
24
import 'scroll_physics.dart';
25
import 'scroll_position.dart';
26
import 'scroll_position_with_single_context.dart';
27
import 'ticker_provider.dart';
28 29 30 31
import 'viewport.dart';

export 'package:flutter/physics.dart' show Tolerance;

32 33
/// Signature used by [Scrollable] to build the viewport through which the
/// scrollable content is displayed.
34
typedef ViewportBuilder = Widget Function(BuildContext context, ViewportOffset position);
35

36 37 38 39 40 41 42 43 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 72 73 74
/// A widget that scrolls.
///
/// [Scrollable] implements the interaction model for a scrollable widget,
/// including gesture recognition, but does not have an opinion about how the
/// viewport, which actually displays the children, is constructed.
///
/// It's rare to construct a [Scrollable] directly. Instead, consider [ListView]
/// or [GridView], which combine scrolling, viewporting, and a layout model. To
/// combine layout models (or to use a custom layout mode), consider using
/// [CustomScrollView].
///
/// The static [Scrollable.of] and [Scrollable.ensureVisible] functions are
/// often used to interact with the [Scrollable] widget inside a [ListView] or
/// a [GridView].
///
/// To further customize scrolling behavior with a [Scrollable]:
///
/// 1. You can provide a [viewportBuilder] to customize the child model. For
///    example, [SingleChildScrollView] uses a viewport that displays a single
///    box child whereas [CustomScrollView] uses a [Viewport] or a
///    [ShrinkWrappingViewport], both of which display a list of slivers.
///
/// 2. You can provide a custom [ScrollController] that creates a custom
///    [ScrollPosition] subclass. For example, [PageView] uses a
///    [PageController], which creates a page-oriented scroll position subclass
///    that keeps the same page visible when the [Scrollable] resizes.
///
/// See also:
///
///  * [ListView], which is a commonly used [ScrollView] that displays a
///    scrolling, linear list of child widgets.
///  * [PageView], which is a scrolling list of child widgets that are each the
///    size of the viewport.
///  * [GridView], which is a [ScrollView] that displays a scrolling, 2D array
///    of child widgets.
///  * [CustomScrollView], which is a [ScrollView] that creates custom scroll
///    effects using slivers.
///  * [SingleChildScrollView], which is a scrollable widget that has a single
///    child.
75
///  * [ScrollNotification] and [NotificationListener], which can be used to watch
76
///    the scroll position without using a [ScrollController].
Adam Barth's avatar
Adam Barth committed
77
class Scrollable extends StatefulWidget {
78 79 80
  /// Creates a widget that scrolls.
  ///
  /// The [axisDirection] and [viewportBuilder] arguments must not be null.
81
  const Scrollable({
82
    Key key,
83
    this.axisDirection = AxisDirection.down,
84
    this.controller,
Adam Barth's avatar
Adam Barth committed
85
    this.physics,
86
    @required this.viewportBuilder,
87
    this.incrementCalculator,
88
    this.excludeFromSemantics = false,
89
    this.semanticChildCount,
90
    this.dragStartBehavior = DragStartBehavior.start,
91
  }) : assert(axisDirection != null),
92
       assert(dragStartBehavior != null),
93
       assert(viewportBuilder != null),
94
       assert(excludeFromSemantics != null),
95
       assert(semanticChildCount == null || semanticChildCount >= 0),
96
       super (key: key);
97

98 99 100 101 102 103 104 105 106 107
  /// The direction in which this widget scrolls.
  ///
  /// For example, if the [axisDirection] is [AxisDirection.down], increasing
  /// the scroll position will cause content below the bottom of the viewport to
  /// become visible through the viewport. Similarly, if [axisDirection] is
  /// [AxisDirection.right], increasing the scroll position will cause content
  /// beyond the right edge of the viewport to become visible through the
  /// viewport.
  ///
  /// Defaults to [AxisDirection.down].
108 109
  final AxisDirection axisDirection;

110 111 112
  /// An object that can be used to control the position to which this widget is
  /// scrolled.
  ///
113 114 115 116 117 118 119 120
  /// A [ScrollController] serves several purposes. It can be used to control
  /// the initial scroll position (see [ScrollController.initialScrollOffset]).
  /// It can be used to control whether the scroll view should automatically
  /// save and restore its scroll position in the [PageStorage] (see
  /// [ScrollController.keepScrollOffset]). It can be used to read the current
  /// scroll position (see [ScrollController.offset]), or change it (see
  /// [ScrollController.animateTo]).
  ///
121 122 123 124
  /// See also:
  ///
  ///  * [ensureVisible], which animates the scroll position to reveal a given
  ///    [BuildContext].
125 126
  final ScrollController controller;

127 128 129 130 131
  /// How the widgets should respond to user input.
  ///
  /// For example, determines how the widget continues to animate after the
  /// user stops dragging the scroll view.
  ///
132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147
  /// Defaults to matching platform conventions via the physics provided from
  /// the ambient [ScrollConfiguration].
  ///
  /// The physics can be changed dynamically, but new physics will only take
  /// effect if the _class_ of the provided object changes. Merely constructing
  /// a new instance with a different configuration is insufficient to cause the
  /// physics to be reapplied. (This is because the final object used is
  /// generated dynamically, which can be relatively expensive, and it would be
  /// inefficient to speculatively create this object each frame to see if the
  /// physics should be updated.)
  ///
  /// See also:
  ///
  ///  * [AlwaysScrollableScrollPhysics], which can be used to indicate that the
  ///    scrollable should react to scroll requests (and possible overscroll)
  ///    even if the scrollable's contents fit without scrolling being necessary.
Adam Barth's avatar
Adam Barth committed
148 149
  final ScrollPhysics physics;

150 151 152 153 154 155 156 157 158 159
  /// Builds the viewport through which the scrollable content is displayed.
  ///
  /// A typical viewport uses the given [ViewportOffset] to determine which part
  /// of its content is actually visible through the viewport.
  ///
  /// See also:
  ///
  ///  * [Viewport], which is a viewport that displays a list of slivers.
  ///  * [ShrinkWrappingViewport], which is a viewport that displays a list of
  ///    slivers and sizes itself based on the size of the slivers.
160
  final ViewportBuilder viewportBuilder;
161

162 163 164 165 166 167 168 169 170 171 172 173 174
  /// An optional function that will be called to calculate the distance to
  /// scroll when the scrollable is asked to scroll via the keyboard using a
  /// [ScrollAction].
  ///
  /// If not supplied, the [Scrollable] will scroll a default amount when a
  /// keyboard navigation key is pressed (e.g. pageUp/pageDown, control-upArrow,
  /// etc.), or otherwise invoked by a [ScrollAction].
  ///
  /// If [incrementCalculator] is null, the default for
  /// [ScrollIncrementType.page] is 80% of the size of the scroll window, and
  /// for [ScrollIncrementType.line], 50 logical pixels.
  final ScrollIncrementCalculator incrementCalculator;

175 176 177 178 179 180 181 182 183 184 185 186 187
  /// Whether the scroll actions introduced by this [Scrollable] are exposed
  /// in the semantics tree.
  ///
  /// Text fields with an overflow are usually scrollable to make sure that the
  /// user can get to the beginning/end of the entered text. However, these
  /// scrolling actions are generally not exposed to the semantics layer.
  ///
  /// See also:
  ///
  ///  * [GestureDetector.excludeFromSemantics], which is used to accomplish the
  ///    exclusion.
  final bool excludeFromSemantics;

188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204
  /// The number of children that will contribute semantic information.
  ///
  /// The value will be null if the number of children is unknown or unbounded.
  ///
  /// Some subtypes of [ScrollView] can infer this value automatically. For
  /// example [ListView] will use the number of widgets in the child list,
  /// while the [new ListView.separated] constructor will use half that amount.
  ///
  /// For [CustomScrollView] and other types which do not receive a builder
  /// or list of widgets, the child count must be explicitly provided.
  ///
  /// See also:
  ///
  ///  * [CustomScrollView], for an explanation of scroll semantics.
  ///  * [SemanticsConfiguration.scrollChildCount], the corresponding semantics property.
  final int semanticChildCount;

205
  // TODO(jslavitz): Set the DragStartBehavior default to be start across all widgets.
206 207 208 209 210 211 212 213 214 215 216
  /// {@template flutter.widgets.scrollable.dragStartBehavior}
  /// Determines the way that drag start behavior is handled.
  ///
  /// If set to [DragStartBehavior.start], scrolling drag behavior will
  /// begin upon the detection of a drag gesture. If set to
  /// [DragStartBehavior.down] it will begin when a down event is first detected.
  ///
  /// In general, setting this to [DragStartBehavior.start] will make drag
  /// animation smoother and setting it to [DragStartBehavior.down] will make
  /// drag behavior feel slightly more reactive.
  ///
217
  /// By default, the drag start behavior is [DragStartBehavior.start].
218 219 220
  ///
  /// See also:
  ///
221 222 223
  ///  * [DragGestureRecognizer.dragStartBehavior], which gives an example for
  ///    the different behaviors.
  ///
224 225 226
  /// {@endtemplate}
  final DragStartBehavior dragStartBehavior;

227 228 229
  /// The axis along which the scroll view scrolls.
  ///
  /// Determined by the [axisDirection].
230 231 232
  Axis get axis => axisDirectionToAxis(axisDirection);

  @override
233
  ScrollableState createState() => ScrollableState();
234 235

  @override
236 237
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
238 239
    properties.add(EnumProperty<AxisDirection>('axisDirection', axisDirection));
    properties.add(DiagnosticsProperty<ScrollPhysics>('physics', physics));
240
  }
241 242 243 244 245 246

  /// The state from the closest instance of this class that encloses the given context.
  ///
  /// Typical usage is as follows:
  ///
  /// ```dart
Adam Barth's avatar
Adam Barth committed
247
  /// ScrollableState scrollable = Scrollable.of(context);
248
  /// ```
249 250 251
  ///
  /// Calling this method will create a dependency on the closest [Scrollable]
  /// in the [context], if there is one.
Adam Barth's avatar
Adam Barth committed
252
  static ScrollableState of(BuildContext context) {
253
    final _ScrollableScope widget = context.dependOnInheritedWidgetOfExactType<_ScrollableScope>();
254
    return widget?.scrollable;
255 256
  }

257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277
  /// Provides a heuristic to determine if expensive frame-bound tasks should be
  /// deferred for the [context] at a specific point in time.
  ///
  /// Calling this method does _not_ create a dependency on any other widget.
  /// This also means that the value returned is only good for the point in time
  /// when it is called, and callers will not get updated if the value changes.
  ///
  /// The heuristic used is determined by the [physics] of this [Scrollable]
  /// via [ScrollPhysics.recommendDeferredScrolling]. That method is called with
  /// the current [activity]'s [ScrollActivity.velocity].
  ///
  /// If there is no [Scrollable] in the widget tree above the [context], this
  /// method returns false.
  static bool recommendDeferredLoadingForContext(BuildContext context) {
    final _ScrollableScope widget = context.getElementForInheritedWidgetOfExactType<_ScrollableScope>()?.widget as _ScrollableScope;
    if (widget == null) {
      return false;
    }
    return widget.position.recommendDeferredLoading(context);
  }

278 279
  /// Scrolls the scrollables that enclose the given context so as to make the
  /// given context visible.
280 281
  static Future<void> ensureVisible(
    BuildContext context, {
282 283 284
    double alignment = 0.0,
    Duration duration = Duration.zero,
    Curve curve = Curves.ease,
285
    ScrollPositionAlignmentPolicy alignmentPolicy = ScrollPositionAlignmentPolicy.explicit,
286
  }) {
287
    final List<Future<void>> futures = <Future<void>>[];
288

Adam Barth's avatar
Adam Barth committed
289
    ScrollableState scrollable = Scrollable.of(context);
290
    while (scrollable != null) {
291 292 293 294 295
      futures.add(scrollable.position.ensureVisible(
        context.findRenderObject(),
        alignment: alignment,
        duration: duration,
        curve: curve,
296
        alignmentPolicy: alignmentPolicy,
297
      ));
298
      context = scrollable.context;
Adam Barth's avatar
Adam Barth committed
299
      scrollable = Scrollable.of(context);
300 301
    }

302
    if (futures.isEmpty || duration == Duration.zero)
303
      return Future<void>.value();
304
    if (futures.length == 1)
305
      return futures.single;
306
    return Future.wait<void>(futures).then<void>((List<void> _) => null);
307
  }
308 309
}

310 311 312
// Enable Scrollable.of() to work as if ScrollableState was an inherited widget.
// ScrollableState.build() always rebuilds its _ScrollableScope.
class _ScrollableScope extends InheritedWidget {
313
  const _ScrollableScope({
314 315 316
    Key key,
    @required this.scrollable,
    @required this.position,
317
    @required Widget child,
318 319 320
  }) : assert(scrollable != null),
       assert(child != null),
       super(key: key, child: child);
321 322 323 324 325 326 327 328 329 330

  final ScrollableState scrollable;
  final ScrollPosition position;

  @override
  bool updateShouldNotify(_ScrollableScope old) {
    return position != old.position;
  }
}

Adam Barth's avatar
Adam Barth committed
331
/// State object for a [Scrollable] widget.
332
///
Adam Barth's avatar
Adam Barth committed
333
/// To manipulate a [Scrollable] widget's scroll position, use the object
334 335
/// obtained from the [position] property.
///
Adam Barth's avatar
Adam Barth committed
336 337
/// To be informed of when a [Scrollable] widget is scrolling, use a
/// [NotificationListener] to listen for [ScrollNotification] notifications.
338 339
///
/// This class is not intended to be subclassed. To specialize the behavior of a
Adam Barth's avatar
Adam Barth committed
340 341
/// [Scrollable], provide it with a [ScrollPhysics].
class ScrollableState extends State<Scrollable> with TickerProviderStateMixin
342 343
    implements ScrollContext {
  /// The manager for this [Scrollable] widget's viewport position.
344
  ///
Adam Barth's avatar
Adam Barth committed
345
  /// To control what kind of [ScrollPosition] is created for a [Scrollable],
346 347
  /// provide it with custom [ScrollController] that creates the appropriate
  /// [ScrollPosition] in its [ScrollController.createScrollPosition] method.
348 349 350
  ScrollPosition get position => _position;
  ScrollPosition _position;

351 352 353
  @override
  AxisDirection get axisDirection => widget.axisDirection;

Adam Barth's avatar
Adam Barth committed
354
  ScrollBehavior _configuration;
355
  ScrollPhysics _physics;
356

357
  // Only call this from places that will definitely trigger a rebuild.
358
  void _updatePosition() {
Adam Barth's avatar
Adam Barth committed
359
    _configuration = ScrollConfiguration.of(context);
360
    _physics = _configuration.getScrollPhysics(context);
361 362 363
    if (widget.physics != null)
      _physics = widget.physics.applyTo(_physics);
    final ScrollController controller = widget.controller;
364 365
    final ScrollPosition oldPosition = position;
    if (oldPosition != null) {
366
      controller?.detach(oldPosition);
367 368 369
      // It's important that we not dispose the old position until after the
      // viewport has had a chance to unregister its listeners from the old
      // position. So, schedule a microtask to do it.
370 371
      scheduleMicrotask(oldPosition.dispose);
    }
372

373
    _position = controller?.createScrollPosition(_physics, this, oldPosition)
374
      ?? ScrollPositionWithSingleContext(physics: _physics, context: this, oldPosition: oldPosition);
375
    assert(position != null);
376
    controller?.attach(position);
377 378 379
  }

  @override
380 381
  void didChangeDependencies() {
    super.didChangeDependencies();
382 383 384
    _updatePosition();
  }

385
  bool _shouldUpdatePosition(Scrollable oldWidget) {
386 387 388 389 390 391 392 393 394 395
    ScrollPhysics newPhysics = widget.physics;
    ScrollPhysics oldPhysics = oldWidget.physics;
    do {
      if (newPhysics?.runtimeType != oldPhysics?.runtimeType)
        return true;
      newPhysics = newPhysics?.parent;
      oldPhysics = oldPhysics?.parent;
    } while (newPhysics != null || oldPhysics != null);

    return widget.controller?.runtimeType != oldWidget.controller?.runtimeType;
396 397
  }

398
  @override
399 400
  void didUpdateWidget(Scrollable oldWidget) {
    super.didUpdateWidget(oldWidget);
401

402 403 404
    if (widget.controller != oldWidget.controller) {
      oldWidget.controller?.detach(position);
      widget.controller?.attach(position);
405 406
    }

407
    if (_shouldUpdatePosition(oldWidget))
408 409 410 411 412
      _updatePosition();
  }

  @override
  void dispose() {
413
    widget.controller?.detach(position);
414 415 416 417 418
    position.dispose();
    super.dispose();
  }


419 420
  // SEMANTICS

421
  final GlobalKey _scrollSemanticsKey = GlobalKey();
422 423 424 425 426 427 428 429 430

  @override
  @protected
  void setSemanticsActions(Set<SemanticsAction> actions) {
    if (_gestureDetectorKey.currentState != null)
      _gestureDetectorKey.currentState.replaceSemanticsActions(actions);
  }


431 432
  // GESTURE RECOGNITION AND POINTER IGNORING

433 434
  final GlobalKey<RawGestureDetectorState> _gestureDetectorKey = GlobalKey<RawGestureDetectorState>();
  final GlobalKey _ignorePointerKey = GlobalKey();
435 436 437 438 439 440 441 442

  // This field is set during layout, and then reused until the next time it is set.
  Map<Type, GestureRecognizerFactory> _gestureRecognizers = const <Type, GestureRecognizerFactory>{};
  bool _shouldIgnorePointer = false;

  bool _lastCanDrag;
  Axis _lastAxisDirection;

443 444 445
  @override
  @protected
  void setCanDrag(bool canDrag) {
446
    if (canDrag == _lastCanDrag && (!canDrag || widget.axis == _lastAxisDirection))
447 448 449 450
      return;
    if (!canDrag) {
      _gestureRecognizers = const <Type, GestureRecognizerFactory>{};
    } else {
451
      switch (widget.axis) {
452 453
        case Axis.vertical:
          _gestureRecognizers = <Type, GestureRecognizerFactory>{
454 455
            VerticalDragGestureRecognizer: GestureRecognizerFactoryWithHandlers<VerticalDragGestureRecognizer>(
              () => VerticalDragGestureRecognizer(),
456 457 458 459 460 461 462 463 464
              (VerticalDragGestureRecognizer instance) {
                instance
                  ..onDown = _handleDragDown
                  ..onStart = _handleDragStart
                  ..onUpdate = _handleDragUpdate
                  ..onEnd = _handleDragEnd
                  ..onCancel = _handleDragCancel
                  ..minFlingDistance = _physics?.minFlingDistance
                  ..minFlingVelocity = _physics?.minFlingVelocity
465 466
                  ..maxFlingVelocity = _physics?.maxFlingVelocity
                  ..dragStartBehavior = widget.dragStartBehavior;
467 468
              },
            ),
469 470 471 472
          };
          break;
        case Axis.horizontal:
          _gestureRecognizers = <Type, GestureRecognizerFactory>{
473 474
            HorizontalDragGestureRecognizer: GestureRecognizerFactoryWithHandlers<HorizontalDragGestureRecognizer>(
              () => HorizontalDragGestureRecognizer(),
475 476 477 478 479 480 481 482 483
              (HorizontalDragGestureRecognizer instance) {
                instance
                  ..onDown = _handleDragDown
                  ..onStart = _handleDragStart
                  ..onUpdate = _handleDragUpdate
                  ..onEnd = _handleDragEnd
                  ..onCancel = _handleDragCancel
                  ..minFlingDistance = _physics?.minFlingDistance
                  ..minFlingVelocity = _physics?.minFlingVelocity
484 485
                  ..maxFlingVelocity = _physics?.maxFlingVelocity
                  ..dragStartBehavior = widget.dragStartBehavior;
486 487
              },
            ),
488 489 490 491 492
          };
          break;
      }
    }
    _lastCanDrag = canDrag;
493
    _lastAxisDirection = widget.axis;
494 495 496 497
    if (_gestureDetectorKey.currentState != null)
      _gestureDetectorKey.currentState.replaceGestureRecognizers(_gestureRecognizers);
  }

498 499 500 501 502 503
  @override
  TickerProvider get vsync => this;

  @override
  @protected
  void setIgnorePointer(bool value) {
504 505 506 507
    if (_shouldIgnorePointer == value)
      return;
    _shouldIgnorePointer = value;
    if (_ignorePointerKey.currentContext != null) {
508
      final RenderIgnorePointer renderBox = _ignorePointerKey.currentContext.findRenderObject() as RenderIgnorePointer;
509 510 511 512
      renderBox.ignoring = _shouldIgnorePointer;
    }
  }

513
  @override
514
  BuildContext get notificationContext => _gestureDetectorKey.currentContext;
515

516 517 518
  @override
  BuildContext get storageContext => context;

519 520
  // TOUCH HANDLERS

521
  Drag _drag;
522
  ScrollHoldController _hold;
523 524 525

  void _handleDragDown(DragDownDetails details) {
    assert(_drag == null);
526 527
    assert(_hold == null);
    _hold = position.hold(_disposeHold);
528 529 530
  }

  void _handleDragStart(DragStartDetails details) {
Ian Hickson's avatar
Ian Hickson committed
531 532 533
    // It's possible for _hold to become null between _handleDragDown and
    // _handleDragStart, for example if some user code calls jumpTo or otherwise
    // triggers a new activity to begin.
534
    assert(_drag == null);
535
    _drag = position.drag(details, _disposeDrag);
536
    assert(_drag != null);
537
    assert(_hold == null);
538 539 540
  }

  void _handleDragUpdate(DragUpdateDetails details) {
541
    // _drag might be null if the drag activity ended and called _disposeDrag.
542
    assert(_hold == null || _drag == null);
543
    _drag?.update(details);
544 545 546
  }

  void _handleDragEnd(DragEndDetails details) {
547
    // _drag might be null if the drag activity ended and called _disposeDrag.
548
    assert(_hold == null || _drag == null);
549
    _drag?.end(details);
550 551 552
    assert(_drag == null);
  }

553
  void _handleDragCancel() {
554
    // _hold might be null if the drag started.
555
    // _drag might be null if the drag activity ended and called _disposeDrag.
556 557
    assert(_hold == null || _drag == null);
    _hold?.cancel();
558
    _drag?.cancel();
559
    assert(_hold == null);
560 561 562
    assert(_drag == null);
  }

563 564 565 566
  void _disposeHold() {
    _hold = null;
  }

567
  void _disposeDrag() {
568 569 570
    _drag = null;
  }

571 572 573 574 575
  // SCROLL WHEEL

  // Returns the offset that should result from applying [event] to the current
  // position, taking min/max scroll extent into account.
  double _targetScrollOffsetForPointerScroll(PointerScrollEvent event) {
576
    double delta = widget.axis == Axis.horizontal
577 578
        ? event.scrollDelta.dx
        : event.scrollDelta.dy;
579 580 581 582 583

    if (axisDirectionIsReversed(widget.axisDirection)) {
      delta *= -1;
    }

584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599
    return math.min(math.max(position.pixels + delta, position.minScrollExtent),
        position.maxScrollExtent);
  }

  void _receivedPointerSignal(PointerSignalEvent event) {
    if (event is PointerScrollEvent && position != null) {
      final double targetScrollOffset = _targetScrollOffsetForPointerScroll(event);
      // Only express interest in the event if it would actually result in a scroll.
      if (targetScrollOffset != position.pixels) {
        GestureBinding.instance.pointerSignalResolver.register(event, _handlePointerScroll);
      }
    }
  }

  void _handlePointerScroll(PointerEvent event) {
    assert(event is PointerScrollEvent);
600 601 602
    if (_physics != null && !_physics.shouldAcceptUserOffset(position)) {
      return;
    }
603
    final double targetScrollOffset = _targetScrollOffsetForPointerScroll(event as PointerScrollEvent);
604 605 606 607
    if (targetScrollOffset != position.pixels) {
      position.jumpTo(targetScrollOffset);
    }
  }
608 609 610 611 612 613

  // DESCRIPTION

  @override
  Widget build(BuildContext context) {
    assert(position != null);
614 615 616 617 618 619 620 621 622 623 624 625
    // _ScrollableScope must be placed above the BuildContext returned by notificationContext
    // so that we can get this ScrollableState by doing the following:
    //
    // ScrollNotification notification;
    // Scrollable.of(notification.context)
    //
    // Since notificationContext is pointing to _gestureDetectorKey.context, _ScrollableScope
    // must be placed above the widget using it: RawGestureDetector
    Widget result = _ScrollableScope(
      scrollable: this,
      position: position,
      // TODO(ianh): Having all these global keys is sad.
626 627 628 629 630 631 632 633 634 635 636 637 638 639 640
      child: Listener(
        onPointerSignal: _receivedPointerSignal,
        child: RawGestureDetector(
          key: _gestureDetectorKey,
          gestures: _gestureRecognizers,
          behavior: HitTestBehavior.opaque,
          excludeFromSemantics: widget.excludeFromSemantics,
          child: Semantics(
            explicitChildNodes: !widget.excludeFromSemantics,
            child: IgnorePointer(
              key: _ignorePointerKey,
              ignoring: _shouldIgnorePointer,
              ignoringSemantics: false,
              child: widget.viewportBuilder(context, position),
            ),
641
          ),
642
        ),
643 644
      ),
    );
645 646

    if (!widget.excludeFromSemantics) {
647
      result = _ScrollSemantics(
Ian Hickson's avatar
Ian Hickson committed
648
        key: _scrollSemanticsKey,
649
        child: result,
650
        position: position,
651
        allowImplicitScrolling: widget?.physics?.allowImplicitScrolling ?? _physics.allowImplicitScrolling,
652
        semanticChildCount: widget.semanticChildCount,
653 654 655
      );
    }

656
    return _configuration.buildViewportChrome(context, result, widget.axisDirection);
657 658 659
  }

  @override
660 661
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
662
    properties.add(DiagnosticsProperty<ScrollPosition>('position', position));
663 664
  }
}
665

Ian Hickson's avatar
Ian Hickson committed
666
/// With [_ScrollSemantics] certain child [SemanticsNode]s can be
667 668 669 670 671 672 673 674 675 676 677 678 679
/// excluded from the scrollable area for semantics purposes.
///
/// Nodes, that are to be excluded, have to be tagged with
/// [RenderViewport.excludeFromScrolling] and the [RenderAbstractViewport] in
/// use has to add the [RenderViewport.useTwoPaneSemantics] tag to its
/// [SemanticsConfiguration] by overriding
/// [RenderObject.describeSemanticsConfiguration].
///
/// If the tag [RenderViewport.useTwoPaneSemantics] is present on the viewport,
/// two semantics nodes will be used to represent the [Scrollable]: The outer
/// node will contain all children, that are excluded from scrolling. The inner
/// node, which is annotated with the scrolling actions, will house the
/// scrollable children.
Ian Hickson's avatar
Ian Hickson committed
680 681
class _ScrollSemantics extends SingleChildRenderObjectWidget {
  const _ScrollSemantics({
682 683
    Key key,
    @required this.position,
684
    @required this.allowImplicitScrolling,
685
    @required this.semanticChildCount,
686
    Widget child,
687
  }) : assert(position != null),
688
       assert(semanticChildCount == null || semanticChildCount >= 0),
689
       super(key: key, child: child);
690 691

  final ScrollPosition position;
692
  final bool allowImplicitScrolling;
693
  final int semanticChildCount;
694 695

  @override
Ian Hickson's avatar
Ian Hickson committed
696
  _RenderScrollSemantics createRenderObject(BuildContext context) {
697
    return _RenderScrollSemantics(
698 699
      position: position,
      allowImplicitScrolling: allowImplicitScrolling,
700
      semanticChildCount: semanticChildCount,
701 702 703
    );
  }

704
  @override
Ian Hickson's avatar
Ian Hickson committed
705
  void updateRenderObject(BuildContext context, _RenderScrollSemantics renderObject) {
706 707
    renderObject
      ..allowImplicitScrolling = allowImplicitScrolling
708 709
      ..position = position
      ..semanticChildCount = semanticChildCount;
710
  }
711 712
}

Ian Hickson's avatar
Ian Hickson committed
713 714
class _RenderScrollSemantics extends RenderProxyBox {
  _RenderScrollSemantics({
715
    @required ScrollPosition position,
716
    @required bool allowImplicitScrolling,
717
    @required int semanticChildCount,
718
    RenderBox child,
719 720
  }) : _position = position,
       _allowImplicitScrolling = allowImplicitScrolling,
721
       _semanticChildCount = semanticChildCount,
722 723
       assert(position != null),
       super(child) {
724 725 726 727 728 729 730 731 732 733 734 735 736 737 738
    position.addListener(markNeedsSemanticsUpdate);
  }

  /// Whether this render object is excluded from the semantic tree.
  ScrollPosition get position => _position;
  ScrollPosition _position;
  set position(ScrollPosition value) {
    assert(value != null);
    if (value == _position)
      return;
    _position.removeListener(markNeedsSemanticsUpdate);
    _position = value;
    _position.addListener(markNeedsSemanticsUpdate);
    markNeedsSemanticsUpdate();
  }
739

740 741 742 743 744 745 746 747 748 749
  /// Whether this node can be scrolled implicitly.
  bool get allowImplicitScrolling => _allowImplicitScrolling;
  bool _allowImplicitScrolling;
  set allowImplicitScrolling(bool value) {
    if (value == _allowImplicitScrolling)
      return;
    _allowImplicitScrolling = value;
    markNeedsSemanticsUpdate();
  }

750 751 752 753 754 755 756 757 758
  int get semanticChildCount => _semanticChildCount;
  int _semanticChildCount;
  set semanticChildCount(int value) {
    if (value == semanticChildCount)
      return;
    _semanticChildCount = value;
    markNeedsSemanticsUpdate();
  }

759 760 761 762
  @override
  void describeSemanticsConfiguration(SemanticsConfiguration config) {
    super.describeSemanticsConfiguration(config);
    config.isSemanticBoundary = true;
763 764
    if (position.haveDimensions) {
      config
765
          ..hasImplicitScrolling = allowImplicitScrolling
766 767
          ..scrollPosition = _position.pixels
          ..scrollExtentMax = _position.maxScrollExtent
768 769
          ..scrollExtentMin = _position.minScrollExtent
          ..scrollChildCount = semanticChildCount;
770
    }
771 772 773 774 775 776 777 778 779 780 781
  }

  SemanticsNode _innerNode;

  @override
  void assembleSemanticsNode(SemanticsNode node, SemanticsConfiguration config, Iterable<SemanticsNode> children) {
    if (children.isEmpty || !children.first.isTagged(RenderViewport.useTwoPaneSemantics)) {
      super.assembleSemanticsNode(node, config, children);
      return;
    }

782
    _innerNode ??= SemanticsNode(showOnScreen: showOnScreen);
783 784 785 786
    _innerNode
      ..isMergedIntoParent = node.isPartOfNodeMerging
      ..rect = Offset.zero & node.rect.size;

787
    int firstVisibleIndex;
788 789
    final List<SemanticsNode> excluded = <SemanticsNode>[_innerNode];
    final List<SemanticsNode> included = <SemanticsNode>[];
790
    for (final SemanticsNode child in children) {
791
      assert(child.isTagged(RenderViewport.useTwoPaneSemantics));
792
      if (child.isTagged(RenderViewport.excludeFromScrolling)) {
793
        excluded.add(child);
794
      } else {
795 796
        if (!child.hasFlag(SemanticsFlag.isHidden))
          firstVisibleIndex ??= child.indexInParent;
797
        included.add(child);
798
      }
799
    }
800
    config.scrollIndex = firstVisibleIndex;
801 802 803 804
    node.updateWith(config: null, childrenInInversePaintOrder: excluded);
    _innerNode.updateWith(config: config, childrenInInversePaintOrder: included);
  }

805 806 807 808
  @override
  void clearSemantics() {
    super.clearSemantics();
    _innerNode = null;
809 810
  }
}
811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038

/// A typedef for a function that can calculate the offset for a type of scroll
/// increment given a [ScrollIncrementDetails].
///
/// This function is used as the type for [Scrollable.incrementCalculator],
/// which is called from a [ScrollAction].
typedef ScrollIncrementCalculator = double Function(ScrollIncrementDetails details);

/// Describes the type of scroll increment that will be performed by a
/// [ScrollAction] on a [Scrollable].
///
/// This is used to configure a [ScrollIncrementDetails] object to pass to a
/// [ScrollIncrementCalculator] function on a [Scrollable].
///
/// {@template flutter.widgets.scrollable.scroll_increment_type.intent}
/// This indicates the *intent* of the scroll, not necessarily the size. Not all
/// scrollable areas will have the concept of a "line" or "page", but they can
/// respond to the different standard key bindings that cause scrolling, which
/// are bound to keys that people use to indicate a "line" scroll (e.g.
/// control-arrowDown keys) or a "page" scroll (e.g. pageDown key). It is
/// recommended that at least the relative magnitudes of the scrolls match
/// expectations.
/// {@endtemplate}
enum ScrollIncrementType {
  /// Indicates that the [ScrollIncrementCalculator] should return the scroll
  /// distance it should move when the user requests to scroll by a "line".
  ///
  /// The distance a "line" scrolls refers to what should happen when the key
  /// binding for "scroll down/up by a line" is triggered. It's up to the
  /// [ScrollIncrementCalculator] function to decide what that means for a
  /// particular scrollable.
  line,

  /// Indicates that the [ScrollIncrementCalculator] should return the scroll
  /// distance it should move when the user requests to scroll by a "page".
  ///
  /// The distance a "page" scrolls refers to what should happen when the key
  /// binding for "scroll down/up by a page" is triggered. It's up to the
  /// [ScrollIncrementCalculator] function to decide what that means for a
  /// particular scrollable.
  page,
}

/// A details object that describes the type of scroll increment being requested
/// of a [ScrollIncrementCalculator] function, as well as the current metrics
/// for the scrollable.
class ScrollIncrementDetails {
  /// A const constructor for a [ScrollIncrementDetails].
  ///
  /// All of the arguments must not be null, and are required.
  const ScrollIncrementDetails({
    @required this.type,
    @required this.metrics,
  })  : assert(type != null),
        assert(metrics != null);

  /// The type of scroll this is (e.g. line, page, etc.).
  ///
  /// {@macro flutter.widgets.scrollable.scroll_increment_type.intent}
  final ScrollIncrementType type;

  /// The current metrics of the scrollable that is being scrolled.
  final ScrollMetrics metrics;
}

/// An [Intent] that represents scrolling the nearest scrollable by an amount
/// appropriate for the [type] specified.
///
/// The actual amount of the scroll is determined by the
/// [Scrollable.incrementCalculator], or by its defaults if that is not
/// specified.
class ScrollIntent extends Intent {
  /// Creates a const [ScrollIntent] that requests scrolling in the given
  /// [direction], with the given [type].
  ///
  /// If [reversed] is specified, then the scroll will happen in the opposite
  /// direction from the normal scroll direction.
  const ScrollIntent({
    @required this.direction,
    this.type = ScrollIncrementType.line,
  })  : assert(direction != null),
        assert(type != null),
        super(ScrollAction.key);

  /// The direction in which to scroll the scrollable containing the focused
  /// widget.
  final AxisDirection direction;

  /// The type of scrolling that is intended.
  final ScrollIncrementType type;

  @override
  bool isEnabled(BuildContext context) {
    return Scrollable.of(context) != null;
  }
}

/// An [Action] that scrolls the [Scrollable] that encloses the current
/// [primaryFocus] by the amount configured in the [ScrollIntent] given to it.
///
/// If [Scrollable.incrementCalculator] is null for the scrollable, the default
/// for a [ScrollIntent.type] set to [ScrollIncrementType.page] is 80% of the
/// size of the scroll window, and for [ScrollIncrementType.line], 50 logical
/// pixels.
class ScrollAction extends Action {
  /// Creates a const [ScrollAction].
  ScrollAction() : super(key);

  /// The [LocalKey] that uniquely connects this action to a [ScrollIntent].
  static const LocalKey key = ValueKey<Type>(ScrollAction);

  // Returns the scroll increment for a single scroll request, for use when
  // scrolling using a hardware keyboard.
  //
  // Must not be called when the position is null, or when any of the position
  // metrics (pixels, viewportDimension, maxScrollExtent, minScrollExtent) are
  // null. The type and state arguments must not be null, and the widget must
  // have already been laid out so that the position fields are valid.
  double _calculateScrollIncrement(ScrollableState state, { ScrollIncrementType type = ScrollIncrementType.line }) {
    assert(type != null);
    assert(state.position != null);
    assert(state.position.pixels != null);
    assert(state.position.viewportDimension != null);
    assert(state.position.maxScrollExtent != null);
    assert(state.position.minScrollExtent != null);
    assert(state.widget.physics == null || state.widget.physics.shouldAcceptUserOffset(state.position));
    if (state.widget.incrementCalculator != null) {
      return state.widget.incrementCalculator(
        ScrollIncrementDetails(
          type: type,
          metrics: state.position,
        ),
      );
    }
    switch (type) {
      case ScrollIncrementType.line:
        return 50.0;
      case ScrollIncrementType.page:
        return 0.8 * state.position.viewportDimension;
    }
    return 0.0;
  }

  // Find out how much of an increment to move by, taking the different
  // directions into account.
  double _getIncrement(ScrollableState state, ScrollIntent intent) {
    final double increment = _calculateScrollIncrement(state, type: intent.type);
    switch (intent.direction) {
      case AxisDirection.down:
        switch (state.axisDirection) {
          case AxisDirection.up:
            return -increment;
            break;
          case AxisDirection.down:
            return increment;
            break;
          case AxisDirection.right:
          case AxisDirection.left:
            return 0.0;
        }
        break;
      case AxisDirection.up:
        switch (state.axisDirection) {
          case AxisDirection.up:
            return increment;
            break;
          case AxisDirection.down:
            return -increment;
            break;
          case AxisDirection.right:
          case AxisDirection.left:
            return 0.0;
        }
        break;
      case AxisDirection.left:
        switch (state.axisDirection) {
          case AxisDirection.right:
            return -increment;
            break;
          case AxisDirection.left:
            return increment;
            break;
          case AxisDirection.up:
          case AxisDirection.down:
            return 0.0;
        }
        break;
      case AxisDirection.right:
        switch (state.axisDirection) {
          case AxisDirection.right:
            return increment;
            break;
          case AxisDirection.left:
            return -increment;
            break;
          case AxisDirection.up:
          case AxisDirection.down:
            return 0.0;
        }
        break;
    }
    return 0.0;
  }

  @override
  void invoke(FocusNode node, ScrollIntent intent) {
    final ScrollableState state = Scrollable.of(node.context);
    assert(state != null, '$ScrollAction was invoked on a context that has no scrollable parent');
    assert(state.position.pixels != null, 'Scrollable must be laid out before it can be scrolled via a ScrollAction');
    assert(state.position.viewportDimension != null);
    assert(state.position.maxScrollExtent != null);
    assert(state.position.minScrollExtent != null);

    // Don't do anything if the user isn't allowed to scroll.
    if (state.widget.physics != null && !state.widget.physics.shouldAcceptUserOffset(state.position)) {
      return;
    }
    final double increment = _getIncrement(state, intent);
    if (increment == 0.0) {
      return;
    }
    state.position.moveTo(
      state.position.pixels + increment,
      duration: const Duration(milliseconds: 100),
      curve: Curves.easeInOut,
    );
  }
}