1/*
2 * Copyright (C) 2015 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17
18package android.support.v4.view;
19
20import android.view.MotionEvent;
21import android.view.VelocityTracker;
22import android.view.View;
23import android.view.ViewConfiguration;
24
25/**
26 * This interface should be implemented by {@link android.view.ViewGroup ViewGroup} subclasses
27 * that wish to support scrolling operations delegated by a nested child view.
28 *
29 * <p>Classes implementing this interface should create a final instance of a
30 * {@link NestedScrollingParentHelper} as a field and delegate any View or ViewGroup methods
31 * to the <code>NestedScrollingParentHelper</code> methods of the same signature.</p>
32 *
33 * <p>Views invoking nested scrolling functionality should always do so from the relevant
34 * {@link ViewCompat}, {@link ViewGroupCompat} or {@link ViewParentCompat} compatibility
35 * shim static methods. This ensures interoperability with nested scrolling views on Android
36 * 5.0 Lollipop and newer.</p>
37 */
38public interface NestedScrollingParent {
39    /**
40     * React to a descendant view initiating a nestable scroll operation, claiming the
41     * nested scroll operation if appropriate.
42     *
43     * <p>This method will be called in response to a descendant view invoking
44     * {@link ViewCompat#startNestedScroll(View, int)}. Each parent up the view hierarchy will be
45     * given an opportunity to respond and claim the nested scrolling operation by returning
46     * <code>true</code>.</p>
47     *
48     * <p>This method may be overridden by ViewParent implementations to indicate when the view
49     * is willing to support a nested scrolling operation that is about to begin. If it returns
50     * true, this ViewParent will become the target view's nested scrolling parent for the duration
51     * of the scroll operation in progress. When the nested scroll is finished this ViewParent
52     * will receive a call to {@link #onStopNestedScroll(View)}.
53     * </p>
54     *
55     * @param child Direct child of this ViewParent containing target
56     * @param target View that initiated the nested scroll
57     * @param nestedScrollAxes Flags consisting of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL},
58     *                         {@link ViewCompat#SCROLL_AXIS_VERTICAL} or both
59     * @return true if this ViewParent accepts the nested scroll operation
60     */
61    public boolean onStartNestedScroll(View child, View target, int nestedScrollAxes);
62
63    /**
64     * React to the successful claiming of a nested scroll operation.
65     *
66     * <p>This method will be called after
67     * {@link #onStartNestedScroll(View, View, int) onStartNestedScroll} returns true. It offers
68     * an opportunity for the view and its superclasses to perform initial configuration
69     * for the nested scroll. Implementations of this method should always call their superclass's
70     * implementation of this method if one is present.</p>
71     *
72     * @param child Direct child of this ViewParent containing target
73     * @param target View that initiated the nested scroll
74     * @param nestedScrollAxes Flags consisting of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL},
75     *                         {@link ViewCompat#SCROLL_AXIS_VERTICAL} or both
76     * @see #onStartNestedScroll(View, View, int)
77     * @see #onStopNestedScroll(View)
78     */
79    public void onNestedScrollAccepted(View child, View target, int nestedScrollAxes);
80
81    /**
82     * React to a nested scroll operation ending.
83     *
84     * <p>Perform cleanup after a nested scrolling operation.
85     * This method will be called when a nested scroll stops, for example when a nested touch
86     * scroll ends with a {@link MotionEvent#ACTION_UP} or {@link MotionEvent#ACTION_CANCEL} event.
87     * Implementations of this method should always call their superclass's implementation of this
88     * method if one is present.</p>
89     *
90     * @param target View that initiated the nested scroll
91     */
92    public void onStopNestedScroll(View target);
93
94    /**
95     * React to a nested scroll in progress.
96     *
97     * <p>This method will be called when the ViewParent's current nested scrolling child view
98     * dispatches a nested scroll event. To receive calls to this method the ViewParent must have
99     * previously returned <code>true</code> for a call to
100     * {@link #onStartNestedScroll(View, View, int)}.</p>
101     *
102     * <p>Both the consumed and unconsumed portions of the scroll distance are reported to the
103     * ViewParent. An implementation may choose to use the consumed portion to match or chase scroll
104     * position of multiple child elements, for example. The unconsumed portion may be used to
105     * allow continuous dragging of multiple scrolling or draggable elements, such as scrolling
106     * a list within a vertical drawer where the drawer begins dragging once the edge of inner
107     * scrolling content is reached.</p>
108     *
109     * @param target The descendent view controlling the nested scroll
110     * @param dxConsumed Horizontal scroll distance in pixels already consumed by target
111     * @param dyConsumed Vertical scroll distance in pixels already consumed by target
112     * @param dxUnconsumed Horizontal scroll distance in pixels not consumed by target
113     * @param dyUnconsumed Vertical scroll distance in pixels not consumed by target
114     */
115    public void onNestedScroll(View target, int dxConsumed, int dyConsumed,
116            int dxUnconsumed, int dyUnconsumed);
117
118    /**
119     * React to a nested scroll in progress before the target view consumes a portion of the scroll.
120     *
121     * <p>When working with nested scrolling often the parent view may want an opportunity
122     * to consume the scroll before the nested scrolling child does. An example of this is a
123     * drawer that contains a scrollable list. The user will want to be able to scroll the list
124     * fully into view before the list itself begins scrolling.</p>
125     *
126     * <p><code>onNestedPreScroll</code> is called when a nested scrolling child invokes
127     * {@link View#dispatchNestedPreScroll(int, int, int[], int[])}. The implementation should
128     * report how any pixels of the scroll reported by dx, dy were consumed in the
129     * <code>consumed</code> array. Index 0 corresponds to dx and index 1 corresponds to dy.
130     * This parameter will never be null. Initial values for consumed[0] and consumed[1]
131     * will always be 0.</p>
132     *
133     * @param target View that initiated the nested scroll
134     * @param dx Horizontal scroll distance in pixels
135     * @param dy Vertical scroll distance in pixels
136     * @param consumed Output. The horizontal and vertical scroll distance consumed by this parent
137     */
138    public void onNestedPreScroll(View target, int dx, int dy, int[] consumed);
139
140    /**
141     * Request a fling from a nested scroll.
142     *
143     * <p>This method signifies that a nested scrolling child has detected suitable conditions
144     * for a fling. Generally this means that a touch scroll has ended with a
145     * {@link VelocityTracker velocity} in the direction of scrolling that meets or exceeds
146     * the {@link ViewConfiguration#getScaledMinimumFlingVelocity() minimum fling velocity}
147     * along a scrollable axis.</p>
148     *
149     * <p>If a nested scrolling child view would normally fling but it is at the edge of
150     * its own content, it can use this method to delegate the fling to its nested scrolling
151     * parent instead. The parent may optionally consume the fling or observe a child fling.</p>
152     *
153     * @param target View that initiated the nested scroll
154     * @param velocityX Horizontal velocity in pixels per second
155     * @param velocityY Vertical velocity in pixels per second
156     * @param consumed true if the child consumed the fling, false otherwise
157     * @return true if this parent consumed or otherwise reacted to the fling
158     */
159    public boolean onNestedFling(View target, float velocityX, float velocityY, boolean consumed);
160
161    /**
162     * React to a nested fling before the target view consumes it.
163     *
164     * <p>This method siginfies that a nested scrolling child has detected a fling with the given
165     * velocity along each axis. Generally this means that a touch scroll has ended with a
166     * {@link VelocityTracker velocity} in the direction of scrolling that meets or exceeds
167     * the {@link ViewConfiguration#getScaledMinimumFlingVelocity() minimum fling velocity}
168     * along a scrollable axis.</p>
169     *
170     * <p>If a nested scrolling parent is consuming motion as part of a
171     * {@link #onNestedPreScroll(View, int, int, int[]) pre-scroll}, it may be appropriate for
172     * it to also consume the pre-fling to complete that same motion. By returning
173     * <code>true</code> from this method, the parent indicates that the child should not
174     * fling its own internal content as well.</p>
175     *
176     * @param target View that initiated the nested scroll
177     * @param velocityX Horizontal velocity in pixels per second
178     * @param velocityY Vertical velocity in pixels per second
179     * @return true if this parent consumed the fling ahead of the target view
180     */
181    public boolean onNestedPreFling(View target, float velocityX, float velocityY);
182
183    /**
184     * Return the current axes of nested scrolling for this NestedScrollingParent.
185     *
186     * <p>A NestedScrollingParent returning something other than {@link ViewCompat#SCROLL_AXIS_NONE}
187     * is currently acting as a nested scrolling parent for one or more descendant views in
188     * the hierarchy.</p>
189     *
190     * @return Flags indicating the current axes of nested scrolling
191     * @see ViewCompat#SCROLL_AXIS_HORIZONTAL
192     * @see ViewCompat#SCROLL_AXIS_VERTICAL
193     * @see ViewCompat#SCROLL_AXIS_NONE
194     */
195    public int getNestedScrollAxes();
196}
197