NestedScrollingChild2.java revision 9dede51868bbbe16aadcd65e04860bea8ea50e05 
1/*
2 * Copyright 2018 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 androidx.core.view;
19
20import android.view.MotionEvent;
21import android.view.View;
22import android.view.ViewParent;
23
24import androidx.annotation.Nullable;
25import androidx.core.view.ViewCompat.NestedScrollType;
26import androidx.core.view.ViewCompat.ScrollAxis;
27
28/**
29 * This interface should be implemented by {@link View View} subclasses that wish
30 * to support dispatching nested scrolling operations to a cooperating parent
31 * {@link android.view.ViewGroup ViewGroup}.
32 *
33 * <p>Classes implementing this interface should create a final instance of a
34 * {@link NestedScrollingChildHelper} as a field and delegate any View methods to the
35 * <code>NestedScrollingChildHelper</code> methods of the same signature.</p>
36 *
37 * <p>Views invoking nested scrolling functionality should always do so from the relevant
38 * {@link ViewCompat}, {@link ViewGroupCompat} or {@link ViewParentCompat} compatibility
39 * shim static methods. This ensures interoperability with nested scrolling views on all versions
40 * of Android.</p>
41 */
42public interface NestedScrollingChild2 extends NestedScrollingChild {
43
44    /**
45     * Begin a nestable scroll operation along the given axes, for the given input type.
46     *
47     * <p>A view starting a nested scroll promises to abide by the following contract:</p>
48     *
49     * <p>The view will call startNestedScroll upon initiating a scroll operation. In the case
50     * of a touch scroll type this corresponds to the initial {@link MotionEvent#ACTION_DOWN}.
51     * In the case of touch scrolling the nested scroll will be terminated automatically in
52     * the same manner as {@link ViewParent#requestDisallowInterceptTouchEvent(boolean)}.
53     * In the event of programmatic scrolling the caller must explicitly call
54     * {@link #stopNestedScroll(int)} to indicate the end of the nested scroll.</p>
55     *
56     * <p>If <code>startNestedScroll</code> returns true, a cooperative parent was found.
57     * If it returns false the caller may ignore the rest of this contract until the next scroll.
58     * Calling startNestedScroll while a nested scroll is already in progress will return true.</p>
59     *
60     * <p>At each incremental step of the scroll the caller should invoke
61     * {@link #dispatchNestedPreScroll(int, int, int[], int[], int) dispatchNestedPreScroll}
62     * once it has calculated the requested scrolling delta. If it returns true the nested scrolling
63     * parent at least partially consumed the scroll and the caller should adjust the amount it
64     * scrolls by.</p>
65     *
66     * <p>After applying the remainder of the scroll delta the caller should invoke
67     * {@link #dispatchNestedScroll(int, int, int, int, int[], int) dispatchNestedScroll}, passing
68     * both the delta consumed and the delta unconsumed. A nested scrolling parent may treat
69     * these values differently. See
70     * {@link NestedScrollingParent2#onNestedScroll(View, int, int, int, int, int)}.
71     * </p>
72     *
73     * @param axes Flags consisting of a combination of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL}
74     *             and/or {@link ViewCompat#SCROLL_AXIS_VERTICAL}.
75     * @param type the type of input which cause this scroll event
76     * @return true if a cooperative parent was found and nested scrolling has been enabled for
77     *         the current gesture.
78     *
79     * @see #stopNestedScroll(int)
80     * @see #dispatchNestedPreScroll(int, int, int[], int[], int)
81     * @see #dispatchNestedScroll(int, int, int, int, int[], int)
82     */
83    boolean startNestedScroll(@ScrollAxis int axes, @NestedScrollType int type);
84
85    /**
86     * Stop a nested scroll in progress for the given input type.
87     *
88     * <p>Calling this method when a nested scroll is not currently in progress is harmless.</p>
89     *
90     * @param type the type of input which cause this scroll event
91     * @see #startNestedScroll(int, int)
92     */
93    void stopNestedScroll(@NestedScrollType int type);
94
95    /**
96     * Returns true if this view has a nested scrolling parent for the given input type.
97     *
98     * <p>The presence of a nested scrolling parent indicates that this view has initiated
99     * a nested scroll and it was accepted by an ancestor view further up the view hierarchy.</p>
100     *
101     * @param type the type of input which cause this scroll event
102     *
103     * @return whether this view has a nested scrolling parent
104     */
105    boolean hasNestedScrollingParent(@NestedScrollType int type);
106
107    /**
108     * Dispatch one step of a nested scroll in progress.
109     *
110     * <p>Implementations of views that support nested scrolling should call this to report
111     * info about a scroll in progress to the current nested scrolling parent. If a nested scroll
112     * is not currently in progress or nested scrolling is not
113     * {@link #isNestedScrollingEnabled() enabled} for this view this method does nothing.</p>
114     *
115     * <p>Compatible View implementations should also call
116     * {@link #dispatchNestedPreScroll(int, int, int[], int[], int) dispatchNestedPreScroll} before
117     * consuming a component of the scroll event themselves.</p>
118     *
119     * @param dxConsumed Horizontal distance in pixels consumed by this view during this scroll step
120     * @param dyConsumed Vertical distance in pixels consumed by this view during this scroll step
121     * @param dxUnconsumed Horizontal scroll distance in pixels not consumed by this view
122     * @param dyUnconsumed Horizontal scroll distance in pixels not consumed by this view
123     * @param offsetInWindow Optional. If not null, on return this will contain the offset
124     *                       in local view coordinates of this view from before this operation
125     *                       to after it completes. View implementations may use this to adjust
126     *                       expected input coordinate tracking.
127     * @param type the type of input which cause this scroll event
128     * @return true if the event was dispatched, false if it could not be dispatched.
129     * @see #dispatchNestedPreScroll(int, int, int[], int[], int)
130     */
131    boolean dispatchNestedScroll(int dxConsumed, int dyConsumed,
132            int dxUnconsumed, int dyUnconsumed, @Nullable int[] offsetInWindow,
133            @NestedScrollType int type);
134
135    /**
136     * Dispatch one step of a nested scroll in progress before this view consumes any portion of it.
137     *
138     * <p>Nested pre-scroll events are to nested scroll events what touch intercept is to touch.
139     * <code>dispatchNestedPreScroll</code> offers an opportunity for the parent view in a nested
140     * scrolling operation to consume some or all of the scroll operation before the child view
141     * consumes it.</p>
142     *
143     * @param dx Horizontal scroll distance in pixels
144     * @param dy Vertical scroll distance in pixels
145     * @param consumed Output. If not null, consumed[0] will contain the consumed component of dx
146     *                 and consumed[1] the consumed dy.
147     * @param offsetInWindow Optional. If not null, on return this will contain the offset
148     *                       in local view coordinates of this view from before this operation
149     *                       to after it completes. View implementations may use this to adjust
150     *                       expected input coordinate tracking.
151     * @param type the type of input which cause this scroll event
152     * @return true if the parent consumed some or all of the scroll delta
153     * @see #dispatchNestedScroll(int, int, int, int, int[], int)
154     */
155    boolean dispatchNestedPreScroll(int dx, int dy, @Nullable int[] consumed,
156            @Nullable int[] offsetInWindow, @NestedScrollType int type);
157}
158