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