scroll_configuration.dart 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 'package:flutter/foundation.dart';
6
import 'package:flutter/gestures.dart';
7
import 'package:flutter/rendering.dart';
8

9
import 'framework.dart';
10
import 'overscroll_indicator.dart';
11
import 'scroll_physics.dart';
12

13
const Color _kDefaultGlowColor = Color(0xFFFFFFFF);
14 15 16 17 18

/// Describes how [Scrollable] widgets should behave.
///
/// Used by [ScrollConfiguration] to configure the [Scrollable] widgets in a
/// subtree.
19
@immutable
Adam Barth's avatar
Adam Barth committed
20
class ScrollBehavior {
21
  /// Creates a description of how [Scrollable] widgets should behave.
Adam Barth's avatar
Adam Barth committed
22
  const ScrollBehavior();
23 24 25 26 27 28

  /// The platform whose scroll physics should be implemented.
  ///
  /// Defaults to the current platform.
  TargetPlatform getPlatform(BuildContext context) => defaultTargetPlatform;

29
  /// Wraps the given widget, which scrolls in the given [AxisDirection].
30
  ///
31 32 33
  /// For example, on Android, this method wraps the given widget with a
  /// [GlowingOverscrollIndicator] to provide visual feedback when the user
  /// overscrolls.
34
  Widget buildViewportChrome(BuildContext context, Widget child, AxisDirection axisDirection) {
35 36
    // When modifying this function, consider modifying the implementation in
    // _MaterialScrollBehavior as well.
37 38
    switch (getPlatform(context)) {
      case TargetPlatform.iOS:
39
      case TargetPlatform.linux:
40
      case TargetPlatform.macOS:
41
      case TargetPlatform.windows:
42 43 44
        return child;
      case TargetPlatform.android:
      case TargetPlatform.fuchsia:
45
        return GlowingOverscrollIndicator(
46 47
          child: child,
          axisDirection: axisDirection,
48
          color: _kDefaultGlowColor,
49 50 51 52
        );
    }
  }

53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
  /// Specifies the type of velocity tracker to use in the descendant
  /// [Scrollable]s' drag gesture recognizers, for estimating the velocity of a
  /// drag gesture.
  ///
  /// This can be used to, for example, apply different fling velocity
  /// estimation methods on different platforms, in order to match the
  /// platform's native behavior.
  ///
  /// Typically, the provided [GestureVelocityTrackerBuilder] should return a
  /// fresh velocity tracker. If null is returned, [Scrollable] creates a new
  /// [VelocityTracker] to track the newly added pointer that may develop into
  /// a drag gesture.
  ///
  /// The default implementation provides a new
  /// [IOSScrollViewFlingVelocityTracker] on iOS and macOS for each new pointer,
  /// and a new [VelocityTracker] on other platforms for each new pointer.
  GestureVelocityTrackerBuilder velocityTrackerBuilder(BuildContext context) {
    switch (getPlatform(context)) {
      case TargetPlatform.iOS:
      case TargetPlatform.macOS:
73
        return (PointerEvent event) => IOSScrollViewFlingVelocityTracker(event.kind);
74 75 76 77
      case TargetPlatform.android:
      case TargetPlatform.fuchsia:
      case TargetPlatform.linux:
      case TargetPlatform.windows:
78
        return (PointerEvent event) => VelocityTracker.withKind(event.kind);
79 80 81
    }
  }

82 83 84
  static const ScrollPhysics _bouncingPhysics = BouncingScrollPhysics(parent: RangeMaintainingScrollPhysics());
  static const ScrollPhysics _clampingPhysics = ClampingScrollPhysics(parent: RangeMaintainingScrollPhysics());

85
  /// The scroll physics to use for the platform given by [getPlatform].
86
  ///
87 88
  /// Defaults to [RangeMaintainingScrollPhysics] mixed with
  /// [BouncingScrollPhysics] on iOS and [ClampingScrollPhysics] on
89
  /// Android.
90 91 92
  ScrollPhysics getScrollPhysics(BuildContext context) {
    switch (getPlatform(context)) {
      case TargetPlatform.iOS:
93
      case TargetPlatform.macOS:
94
        return _bouncingPhysics;
95 96
      case TargetPlatform.android:
      case TargetPlatform.fuchsia:
97 98
      case TargetPlatform.linux:
      case TargetPlatform.windows:
99
        return _clampingPhysics;
100 101 102
    }
  }

Adam Barth's avatar
Adam Barth committed
103 104 105 106 107 108 109 110 111 112
  /// Called whenever a [ScrollConfiguration] is rebuilt with a new
  /// [ScrollBehavior] of the same [runtimeType].
  ///
  /// If the new instance represents different information than the old
  /// instance, then the method should return true, otherwise it should return
  /// false.
  ///
  /// If this method returns true, all the widgets that inherit from the
  /// [ScrollConfiguration] will rebuild using the new [ScrollBehavior]. If this
  /// method returns false, the rebuilds might be optimized away.
113
  bool shouldNotify(covariant ScrollBehavior oldDelegate) => false;
114 115

  @override
116
  String toString() => objectRuntimeType(this, 'ScrollBehavior');
117 118
}

119 120 121
/// Controls how [Scrollable] widgets behave in a subtree.
///
/// The scroll configuration determines the [ScrollPhysics] and viewport
122
/// decorations used by descendants of [child].
Adam Barth's avatar
Adam Barth committed
123
class ScrollConfiguration extends InheritedWidget {
124 125 126
  /// Creates a widget that controls how [Scrollable] widgets behave in a subtree.
  ///
  /// The [behavior] and [child] arguments must not be null.
Adam Barth's avatar
Adam Barth committed
127
  const ScrollConfiguration({
128 129 130
    Key? key,
    required this.behavior,
    required Widget child,
131 132
  }) : super(key: key, child: child);

133
  /// How [Scrollable] widgets that are descendants of [child] should behave.
Adam Barth's avatar
Adam Barth committed
134
  final ScrollBehavior behavior;
135

136
  /// The [ScrollBehavior] for [Scrollable] widgets in the given [BuildContext].
137 138 139
  ///
  /// If no [ScrollConfiguration] widget is in scope of the given `context`,
  /// a default [ScrollBehavior] instance is returned.
Adam Barth's avatar
Adam Barth committed
140
  static ScrollBehavior of(BuildContext context) {
141
    final ScrollConfiguration? configuration = context.dependOnInheritedWidgetOfExactType<ScrollConfiguration>();
Adam Barth's avatar
Adam Barth committed
142
    return configuration?.behavior ?? const ScrollBehavior();
143 144 145
  }

  @override
Adam Barth's avatar
Adam Barth committed
146
  bool updateShouldNotify(ScrollConfiguration oldWidget) {
147
    assert(behavior != null);
Adam Barth's avatar
Adam Barth committed
148 149
    return behavior.runtimeType != oldWidget.behavior.runtimeType
        || (behavior != oldWidget.behavior && behavior.shouldNotify(oldWidget.behavior));
150
  }
151 152

  @override
153 154
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
155
    properties.add(DiagnosticsProperty<ScrollBehavior>('behavior', behavior));
156
  }
157
}