primary_scroll_controller.dart 2.94 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 8 9
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'package:flutter/foundation.dart';

import 'framework.dart';
import 'scroll_controller.dart';

10 11 12 13 14 15 16 17 18
/// Associates a [ScrollController] with a subtree.
///
/// When a [ScrollView] has [ScrollView.primary] set to true and is not given
/// an explicit [ScrollController], the [ScrollView] uses [of] to find the
/// [ScrollController] associated with its subtree.
///
/// This mechanism can be used to provide default behavior for scroll views in a
/// subtree. For example, the [Scaffold] uses this mechanism to implement the
/// scroll-to-top gesture on iOS.
19 20 21 22 23 24 25 26 27 28 29 30 31
///
/// Another default behavior handled by the PrimaryScrollController is default
/// [ScrollAction]s. If a ScrollAction is not handled by an otherwise focused
/// part of the application, the ScrollAction will be evaluated using the scroll
/// view associated with a PrimaryScrollController, for example, when executing
/// [Shortcuts] key events like page up and down.
///
/// See also:
///   * [ScrollAction], an [Action] that scrolls the [Scrollable] that encloses
///     the current [primaryFocus] or is attached to the PrimaryScrollController.
///   * [Shortcuts], a widget that establishes a [ShortcutManager] to be used
///     by its descendants when invoking an [Action] via a keyboard key
///     combination that maps to an [Intent].
32
class PrimaryScrollController extends InheritedWidget {
33
  /// Creates a widget that associates a [ScrollController] with a subtree.
34
  const PrimaryScrollController({
35
    Key? key,
36
    required ScrollController this.controller,
37
    required Widget child,
38 39
  }) : assert(controller != null),
       super(key: key, child: child);
40

41
  /// Creates a subtree without an associated [ScrollController].
42
  const PrimaryScrollController.none({
43 44
    Key? key,
    required Widget child,
45 46 47
  }) : controller = null,
       super(key: key, child: child);

48
  /// The [ScrollController] associated with the subtree.
49 50 51 52 53
  ///
  /// See also:
  ///
  ///  * [ScrollView.controller], which discusses the purpose of specifying a
  ///    scroll controller.
54
  final ScrollController? controller;
55

56 57 58 59 60
  /// Returns the [ScrollController] most closely associated with the given
  /// context.
  ///
  /// Returns null if there is no [ScrollController] associated with the given
  /// context.
61 62
  static ScrollController? of(BuildContext context) {
    final PrimaryScrollController? result = context.dependOnInheritedWidgetOfExactType<PrimaryScrollController>();
63 64 65 66
    return result?.controller;
  }

  @override
67
  bool updateShouldNotify(PrimaryScrollController oldWidget) => controller != oldWidget.controller;
68 69

  @override
70 71
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
72
    properties.add(DiagnosticsProperty<ScrollController>('controller', controller, ifNull: 'no controller', showName: false));
73 74
  }
}