1/*
2 * Copyright (C) 2017 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.support.annotation.NonNull;
21import android.support.annotation.Nullable;
22import android.support.v4.view.ViewCompat.NestedScrollType;
23import android.support.v4.view.ViewCompat.ScrollAxis;
24import android.view.MotionEvent;
25import android.view.View;
26
27/**
28 * This interface should be implemented by {@link android.view.ViewGroup ViewGroup} subclasses
29 * that wish to support scrolling operations delegated by a nested child view.
30 *
31 * <p>Classes implementing this interface should create a final instance of a
32 * {@link NestedScrollingParentHelper} as a field and delegate any View or ViewGroup methods
33 * to the <code>NestedScrollingParentHelper</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 all versions
38 * of Android.</p>
39 */
40public interface NestedScrollingParent2 extends NestedScrollingParent {
41    /**
42     * React to a descendant view initiating a nestable scroll operation, claiming the
43     * nested scroll operation if appropriate.
44     *
45     * <p>This method will be called in response to a descendant view invoking
46     * {@link ViewCompat#startNestedScroll(View, int)}. Each parent up the view hierarchy will be
47     * given an opportunity to respond and claim the nested scrolling operation by returning
48     * <code>true</code>.</p>
49     *
50     * <p>This method may be overridden by ViewParent implementations to indicate when the view
51     * is willing to support a nested scrolling operation that is about to begin. If it returns
52     * true, this ViewParent will become the target view's nested scrolling parent for the duration
53     * of the scroll operation in progress. When the nested scroll is finished this ViewParent
54     * will receive a call to {@link #onStopNestedScroll(View, int)}.
55     * </p>
56     *
57     * @param child Direct child of this ViewParent containing target
58     * @param target View that initiated the nested scroll
59     * @param axes Flags consisting of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL},
60     *                         {@link ViewCompat#SCROLL_AXIS_VERTICAL} or both
61     * @param type the type of input which cause this scroll event
62     * @return true if this ViewParent accepts the nested scroll operation
63     */
64    boolean onStartNestedScroll(@NonNull View child, @NonNull View target, @ScrollAxis int axes,
65            @NestedScrollType int type);
66
67    /**
68     * React to the successful claiming of a nested scroll operation.
69     *
70     * <p>This method will be called after
71     * {@link #onStartNestedScroll(View, View, int, int) onStartNestedScroll} returns true. It
72     * offers an opportunity for the view and its superclasses to perform initial configuration
73     * for the nested scroll. Implementations of this method should always call their superclass's
74     * implementation of this method if one is present.</p>
75     *
76     * @param child Direct child of this ViewParent containing target
77     * @param target View that initiated the nested scroll
78     * @param axes Flags consisting of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL},
79     *                         {@link ViewCompat#SCROLL_AXIS_VERTICAL} or both
80     * @param type the type of input which cause this scroll event
81     * @see #onStartNestedScroll(View, View, int, int)
82     * @see #onStopNestedScroll(View, int)
83     */
84    void onNestedScrollAccepted(@NonNull View child, @NonNull View target, @ScrollAxis int axes,
85            @NestedScrollType int type);
86
87    /**
88     * React to a nested scroll operation ending.
89     *
90     * <p>Perform cleanup after a nested scrolling operation.
91     * This method will be called when a nested scroll stops, for example when a nested touch
92     * scroll ends with a {@link MotionEvent#ACTION_UP} or {@link MotionEvent#ACTION_CANCEL} event.
93     * Implementations of this method should always call their superclass's implementation of this
94     * method if one is present.</p>
95     *
96     * @param target View that initiated the nested scroll
97     * @param type the type of input which cause this scroll event
98     */
99    void onStopNestedScroll(@NonNull View target, @NestedScrollType int type);
100
101    /**
102     * React to a nested scroll in progress.
103     *
104     * <p>This method will be called when the ViewParent's current nested scrolling child view
105     * dispatches a nested scroll event. To receive calls to this method the ViewParent must have
106     * previously returned <code>true</code> for a call to
107     * {@link #onStartNestedScroll(View, View, int, int)}.</p>
108     *
109     * <p>Both the consumed and unconsumed portions of the scroll distance are reported to the
110     * ViewParent. An implementation may choose to use the consumed portion to match or chase scroll
111     * position of multiple child elements, for example. The unconsumed portion may be used to
112     * allow continuous dragging of multiple scrolling or draggable elements, such as scrolling
113     * a list within a vertical drawer where the drawer begins dragging once the edge of inner
114     * scrolling content is reached.</p>
115     *
116     * @param target The descendent view controlling the nested scroll
117     * @param dxConsumed Horizontal scroll distance in pixels already consumed by target
118     * @param dyConsumed Vertical scroll distance in pixels already consumed by target
119     * @param dxUnconsumed Horizontal scroll distance in pixels not consumed by target
120     * @param dyUnconsumed Vertical scroll distance in pixels not consumed by target
121     * @param type the type of input which cause this scroll event
122     */
123    void onNestedScroll(@NonNull View target, int dxConsumed, int dyConsumed,
124            int dxUnconsumed, int dyUnconsumed, @NestedScrollType int type);
125
126    /**
127     * React to a nested scroll in progress before the target view consumes a portion of the scroll.
128     *
129     * <p>When working with nested scrolling often the parent view may want an opportunity
130     * to consume the scroll before the nested scrolling child does. An example of this is a
131     * drawer that contains a scrollable list. The user will want to be able to scroll the list
132     * fully into view before the list itself begins scrolling.</p>
133     *
134     * <p><code>onNestedPreScroll</code> is called when a nested scrolling child invokes
135     * {@link View#dispatchNestedPreScroll(int, int, int[], int[])}. The implementation should
136     * report how any pixels of the scroll reported by dx, dy were consumed in the
137     * <code>consumed</code> array. Index 0 corresponds to dx and index 1 corresponds to dy.
138     * This parameter will never be null. Initial values for consumed[0] and consumed[1]
139     * will always be 0.</p>
140     *
141     * @param target View that initiated the nested scroll
142     * @param dx Horizontal scroll distance in pixels
143     * @param dy Vertical scroll distance in pixels
144     * @param consumed Output. The horizontal and vertical scroll distance consumed by this parent
145     * @param type the type of input which cause this scroll event
146     */
147    void onNestedPreScroll(@NonNull View target, int dx, int dy, @Nullable int[] consumed,
148            @NestedScrollType int type);
149
150}
151