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;
24import android.view.ViewParent;
25
26/**
27 * This interface should be implemented by {@link android.view.View View} subclasses that wish
28 * to support dispatching nested scrolling operations to a cooperating parent
29 * {@link android.view.ViewGroup ViewGroup}.
30 *
31 * <p>Classes implementing this interface should create a final instance of a
32 * {@link NestedScrollingChildHelper} as a field and delegate any View methods to the
33 * <code>NestedScrollingChildHelper</code> methods of the same signature.</p>
34 *
35 * <p>Views invoking nested scrolling functionality should always do so from the relevant
36 * {@link ViewCompat}, {@link ViewGroupCompat} or {@link ViewParentCompat} compatibility
37 * shim static methods. This ensures interoperability with nested scrolling views on Android
38 * 5.0 Lollipop and newer.</p>
39 */
40public interface NestedScrollingChild {
41    /**
42     * Enable or disable nested scrolling for this view.
43     *
44     * <p>If this property is set to true the view will be permitted to initiate nested
45     * scrolling operations with a compatible parent view in the current hierarchy. If this
46     * view does not implement nested scrolling this will have no effect. Disabling nested scrolling
47     * while a nested scroll is in progress has the effect of {@link #stopNestedScroll() stopping}
48     * the nested scroll.</p>
49     *
50     * @param enabled true to enable nested scrolling, false to disable
51     *
52     * @see #isNestedScrollingEnabled()
53     */
54    public void setNestedScrollingEnabled(boolean enabled);
55
56    /**
57     * Returns true if nested scrolling is enabled for this view.
58     *
59     * <p>If nested scrolling is enabled and this View class implementation supports it,
60     * this view will act as a nested scrolling child view when applicable, forwarding data
61     * about the scroll operation in progress to a compatible and cooperating nested scrolling
62     * parent.</p>
63     *
64     * @return true if nested scrolling is enabled
65     *
66     * @see #setNestedScrollingEnabled(boolean)
67     */
68    public boolean isNestedScrollingEnabled();
69
70    /**
71     * Begin a nestable scroll operation along the given axes.
72     *
73     * <p>A view starting a nested scroll promises to abide by the following contract:</p>
74     *
75     * <p>The view will call startNestedScroll upon initiating a scroll operation. In the case
76     * of a touch scroll this corresponds to the initial {@link MotionEvent#ACTION_DOWN}.
77     * In the case of touch scrolling the nested scroll will be terminated automatically in
78     * the same manner as {@link ViewParent#requestDisallowInterceptTouchEvent(boolean)}.
79     * In the event of programmatic scrolling the caller must explicitly call
80     * {@link #stopNestedScroll()} to indicate the end of the nested scroll.</p>
81     *
82     * <p>If <code>startNestedScroll</code> returns true, a cooperative parent was found.
83     * If it returns false the caller may ignore the rest of this contract until the next scroll.
84     * Calling startNestedScroll while a nested scroll is already in progress will return true.</p>
85     *
86     * <p>At each incremental step of the scroll the caller should invoke
87     * {@link #dispatchNestedPreScroll(int, int, int[], int[]) dispatchNestedPreScroll}
88     * once it has calculated the requested scrolling delta. If it returns true the nested scrolling
89     * parent at least partially consumed the scroll and the caller should adjust the amount it
90     * scrolls by.</p>
91     *
92     * <p>After applying the remainder of the scroll delta the caller should invoke
93     * {@link #dispatchNestedScroll(int, int, int, int, int[]) dispatchNestedScroll}, passing
94     * both the delta consumed and the delta unconsumed. A nested scrolling parent may treat
95     * these values differently. See
96     * {@link NestedScrollingParent#onNestedScroll(View, int, int, int, int)}.
97     * </p>
98     *
99     * @param axes Flags consisting of a combination of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL}
100     *             and/or {@link ViewCompat#SCROLL_AXIS_VERTICAL}.
101     * @return true if a cooperative parent was found and nested scrolling has been enabled for
102     *         the current gesture.
103     *
104     * @see #stopNestedScroll()
105     * @see #dispatchNestedPreScroll(int, int, int[], int[])
106     * @see #dispatchNestedScroll(int, int, int, int, int[])
107     */
108    public boolean startNestedScroll(int axes);
109
110    /**
111     * Stop a nested scroll in progress.
112     *
113     * <p>Calling this method when a nested scroll is not currently in progress is harmless.</p>
114     *
115     * @see #startNestedScroll(int)
116     */
117    public void stopNestedScroll();
118
119    /**
120     * Returns true if this view has a nested scrolling parent.
121     *
122     * <p>The presence of a nested scrolling parent indicates that this view has initiated
123     * a nested scroll and it was accepted by an ancestor view further up the view hierarchy.</p>
124     *
125     * @return whether this view has a nested scrolling parent
126     */
127    public boolean hasNestedScrollingParent();
128
129    /**
130     * Dispatch one step of a nested scroll in progress.
131     *
132     * <p>Implementations of views that support nested scrolling should call this to report
133     * info about a scroll in progress to the current nested scrolling parent. If a nested scroll
134     * is not currently in progress or nested scrolling is not
135     * {@link #isNestedScrollingEnabled() enabled} for this view this method does nothing.</p>
136     *
137     * <p>Compatible View implementations should also call
138     * {@link #dispatchNestedPreScroll(int, int, int[], int[]) dispatchNestedPreScroll} before
139     * consuming a component of the scroll event themselves.</p>
140     *
141     * @param dxConsumed Horizontal distance in pixels consumed by this view during this scroll step
142     * @param dyConsumed Vertical distance in pixels consumed by this view during this scroll step
143     * @param dxUnconsumed Horizontal scroll distance in pixels not consumed by this view
144     * @param dyUnconsumed Horizontal scroll distance in pixels not consumed by this view
145     * @param offsetInWindow Optional. If not null, on return this will contain the offset
146     *                       in local view coordinates of this view from before this operation
147     *                       to after it completes. View implementations may use this to adjust
148     *                       expected input coordinate tracking.
149     * @return true if the event was dispatched, false if it could not be dispatched.
150     * @see #dispatchNestedPreScroll(int, int, int[], int[])
151     */
152    public boolean dispatchNestedScroll(int dxConsumed, int dyConsumed,
153            int dxUnconsumed, int dyUnconsumed, int[] offsetInWindow);
154
155    /**
156     * Dispatch one step of a nested scroll in progress before this view consumes any portion of it.
157     *
158     * <p>Nested pre-scroll events are to nested scroll events what touch intercept is to touch.
159     * <code>dispatchNestedPreScroll</code> offers an opportunity for the parent view in a nested
160     * scrolling operation to consume some or all of the scroll operation before the child view
161     * consumes it.</p>
162     *
163     * @param dx Horizontal scroll distance in pixels
164     * @param dy Vertical scroll distance in pixels
165     * @param consumed Output. If not null, consumed[0] will contain the consumed component of dx
166     *                 and consumed[1] the consumed dy.
167     * @param offsetInWindow Optional. If not null, on return this will contain the offset
168     *                       in local view coordinates of this view from before this operation
169     *                       to after it completes. View implementations may use this to adjust
170     *                       expected input coordinate tracking.
171     * @return true if the parent consumed some or all of the scroll delta
172     * @see #dispatchNestedScroll(int, int, int, int, int[])
173     */
174    public boolean dispatchNestedPreScroll(int dx, int dy, int[] consumed, int[] offsetInWindow);
175
176    /**
177     * Dispatch a fling to a nested scrolling parent.
178     *
179     * <p>This method should be used to indicate that a nested scrolling child has detected
180     * suitable conditions for a fling. Generally this means that a touch scroll has ended with a
181     * {@link VelocityTracker velocity} in the direction of scrolling that meets or exceeds
182     * the {@link ViewConfiguration#getScaledMinimumFlingVelocity() minimum fling velocity}
183     * along a scrollable axis.</p>
184     *
185     * <p>If a nested scrolling child view would normally fling but it is at the edge of
186     * its own content, it can use this method to delegate the fling to its nested scrolling
187     * parent instead. The parent may optionally consume the fling or observe a child fling.</p>
188     *
189     * @param velocityX Horizontal fling velocity in pixels per second
190     * @param velocityY Vertical fling velocity in pixels per second
191     * @param consumed true if the child consumed the fling, false otherwise
192     * @return true if the nested scrolling parent consumed or otherwise reacted to the fling
193     */
194    public boolean dispatchNestedFling(float velocityX, float velocityY, boolean consumed);
195
196    /**
197     * Dispatch a fling to a nested scrolling parent before it is processed by this view.
198     *
199     * <p>Nested pre-fling events are to nested fling events what touch intercept is to touch
200     * and what nested pre-scroll is to nested scroll. <code>dispatchNestedPreFling</code>
201     * offsets an opportunity for the parent view in a nested fling to fully consume the fling
202     * before the child view consumes it. If this method returns <code>true</code>, a nested
203     * parent view consumed the fling and this view should not scroll as a result.</p>
204     *
205     * <p>For a better user experience, only one view in a nested scrolling chain should consume
206     * the fling at a time. If a parent view consumed the fling this method will return false.
207     * Custom view implementations should account for this in two ways:</p>
208     *
209     * <ul>
210     *     <li>If a custom view is paged and needs to settle to a fixed page-point, do not
211     *     call <code>dispatchNestedPreFling</code>; consume the fling and settle to a valid
212     *     position regardless.</li>
213     *     <li>If a nested parent does consume the fling, this view should not scroll at all,
214     *     even to settle back to a valid idle position.</li>
215     * </ul>
216     *
217     * <p>Views should also not offer fling velocities to nested parent views along an axis
218     * where scrolling is not currently supported; a {@link android.widget.ScrollView ScrollView}
219     * should not offer a horizontal fling velocity to its parents since scrolling along that
220     * axis is not permitted and carrying velocity along that motion does not make sense.</p>
221     *
222     * @param velocityX Horizontal fling velocity in pixels per second
223     * @param velocityY Vertical fling velocity in pixels per second
224     * @return true if a nested scrolling parent consumed the fling
225     */
226    public boolean dispatchNestedPreFling(float velocityX, float velocityY);
227}
228