1// Copyright 2014 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5/// @docImport 'dart:ui';
6///
7/// @docImport 'page_storage.dart';
8/// @docImport 'scroll_configuration.dart';
9/// @docImport 'scroll_notification.dart';
10/// @docImport 'scroll_position.dart';
11/// @docImport 'scrollable.dart';
12/// @docImport 'viewport.dart';
13library;
14
15import 'package:flutter/rendering.dart';
16import 'package:flutter/scheduler.dart';
17
18import 'framework.dart';
19import 'ticker_provider.dart';
20
21/// An interface that [Scrollable] widgets implement in order to use
22/// [ScrollPosition].
23///
24/// See also:
25///
26/// * [ScrollableState], which is the most common implementation of this
27/// interface.
28/// * [ScrollPosition], which uses this interface to communicate with the
29/// scrollable widget.
30abstract class ScrollContext {
31 /// The [BuildContext] that should be used when dispatching
32 /// [ScrollNotification]s.
33 ///
34 /// This context is typically different that the context of the scrollable
35 /// widget itself. For example, [Scrollable] uses a context outside the
36 /// [Viewport] but inside the widgets created by
37 /// [ScrollBehavior.buildOverscrollIndicator] and [ScrollBehavior.buildScrollbar].
38 BuildContext? get notificationContext;
39
40 /// The [BuildContext] that should be used when searching for a [PageStorage].
41 ///
42 /// This context is typically the context of the scrollable widget itself. In
43 /// particular, it should involve any [GlobalKey]s that are dynamically
44 /// created as part of creating the scrolling widget, since those would be
45 /// different each time the widget is created.
46 // TODO(goderbauer): Deprecate this when state restoration supports all features of PageStorage.
47 BuildContext get storageContext;
48
49 /// A [TickerProvider] to use when animating the scroll position.
50 TickerProvider get vsync;
51
52 /// The direction in which the widget scrolls.
53 AxisDirection get axisDirection;
54
55 /// The [FlutterView.devicePixelRatio] of the view that the [Scrollable] this
56 /// [ScrollContext] is associated with is drawn into.
57 double get devicePixelRatio;
58
59 /// Whether the contents of the widget should ignore [PointerEvent] inputs.
60 ///
61 /// Setting this value to true prevents the use from interacting with the
62 /// contents of the widget with pointer events. The widget itself is still
63 /// interactive.
64 ///
65 /// For example, if the scroll position is being driven by an animation, it
66 /// might be appropriate to set this value to ignore pointer events to
67 /// prevent the user from accidentally interacting with the contents of the
68 /// widget as it animates. The user will still be able to touch the widget,
69 /// potentially stopping the animation.
70 void setIgnorePointer(bool value);
71
72 /// Whether the user can drag the widget, for example to initiate a scroll.
73 void setCanDrag(bool value);
74
75 /// Set the [SemanticsAction]s that should be expose to the semantics tree.
76 void setSemanticsActions(Set<SemanticsAction> actions);
77
78 /// Called by the [ScrollPosition] whenever scrolling ends to persist the
79 /// provided scroll `offset` for state restoration purposes.
80 ///
81 /// The [ScrollContext] may pass the value back to a [ScrollPosition] by
82 /// calling [ScrollPosition.restoreOffset] at a later point in time or after
83 /// the application has restarted to restore the scroll offset.
84 void saveOffset(double offset);
85}
86