176daed103193a1756535d1f59b165e98e1d17445Chris Banes/* 276daed103193a1756535d1f59b165e98e1d17445Chris Banes * Copyright (C) 2017 The Android Open Source Project 376daed103193a1756535d1f59b165e98e1d17445Chris Banes * 476daed103193a1756535d1f59b165e98e1d17445Chris Banes * Licensed under the Apache License, Version 2.0 (the "License"); 576daed103193a1756535d1f59b165e98e1d17445Chris Banes * you may not use this file except in compliance with the License. 676daed103193a1756535d1f59b165e98e1d17445Chris Banes * You may obtain a copy of the License at 776daed103193a1756535d1f59b165e98e1d17445Chris Banes * 876daed103193a1756535d1f59b165e98e1d17445Chris Banes * http://www.apache.org/licenses/LICENSE-2.0 976daed103193a1756535d1f59b165e98e1d17445Chris Banes * 1076daed103193a1756535d1f59b165e98e1d17445Chris Banes * Unless required by applicable law or agreed to in writing, software 1176daed103193a1756535d1f59b165e98e1d17445Chris Banes * distributed under the License is distributed on an "AS IS" BASIS, 1276daed103193a1756535d1f59b165e98e1d17445Chris Banes * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1376daed103193a1756535d1f59b165e98e1d17445Chris Banes * See the License for the specific language governing permissions and 1476daed103193a1756535d1f59b165e98e1d17445Chris Banes * limitations under the License. 1576daed103193a1756535d1f59b165e98e1d17445Chris Banes */ 1676daed103193a1756535d1f59b165e98e1d17445Chris Banes 1776daed103193a1756535d1f59b165e98e1d17445Chris Banes 1876daed103193a1756535d1f59b165e98e1d17445Chris Banespackage android.support.v4.view; 1976daed103193a1756535d1f59b165e98e1d17445Chris Banes 2076daed103193a1756535d1f59b165e98e1d17445Chris Banesimport android.support.annotation.Nullable; 2176daed103193a1756535d1f59b165e98e1d17445Chris Banesimport android.support.v4.view.ViewCompat.NestedScrollType; 2276daed103193a1756535d1f59b165e98e1d17445Chris Banesimport android.support.v4.view.ViewCompat.ScrollAxis; 2376daed103193a1756535d1f59b165e98e1d17445Chris Banesimport android.view.MotionEvent; 2476daed103193a1756535d1f59b165e98e1d17445Chris Banesimport android.view.View; 2576daed103193a1756535d1f59b165e98e1d17445Chris Banesimport android.view.ViewParent; 2676daed103193a1756535d1f59b165e98e1d17445Chris Banes 2776daed103193a1756535d1f59b165e98e1d17445Chris Banes/** 2876daed103193a1756535d1f59b165e98e1d17445Chris Banes * This interface should be implemented by {@link View View} subclasses that wish 2976daed103193a1756535d1f59b165e98e1d17445Chris Banes * to support dispatching nested scrolling operations to a cooperating parent 3076daed103193a1756535d1f59b165e98e1d17445Chris Banes * {@link android.view.ViewGroup ViewGroup}. 3176daed103193a1756535d1f59b165e98e1d17445Chris Banes * 3276daed103193a1756535d1f59b165e98e1d17445Chris Banes * <p>Classes implementing this interface should create a final instance of a 3376daed103193a1756535d1f59b165e98e1d17445Chris Banes * {@link NestedScrollingChildHelper} as a field and delegate any View methods to the 3476daed103193a1756535d1f59b165e98e1d17445Chris Banes * <code>NestedScrollingChildHelper</code> methods of the same signature.</p> 3576daed103193a1756535d1f59b165e98e1d17445Chris Banes * 3676daed103193a1756535d1f59b165e98e1d17445Chris Banes * <p>Views invoking nested scrolling functionality should always do so from the relevant 3776daed103193a1756535d1f59b165e98e1d17445Chris Banes * {@link ViewCompat}, {@link ViewGroupCompat} or {@link ViewParentCompat} compatibility 3876daed103193a1756535d1f59b165e98e1d17445Chris Banes * shim static methods. This ensures interoperability with nested scrolling views on all versions 3976daed103193a1756535d1f59b165e98e1d17445Chris Banes * of Android.</p> 4076daed103193a1756535d1f59b165e98e1d17445Chris Banes */ 4176daed103193a1756535d1f59b165e98e1d17445Chris Banespublic interface NestedScrollingChild2 extends NestedScrollingChild { 4276daed103193a1756535d1f59b165e98e1d17445Chris Banes 4376daed103193a1756535d1f59b165e98e1d17445Chris Banes /** 4476daed103193a1756535d1f59b165e98e1d17445Chris Banes * Begin a nestable scroll operation along the given axes, for the given input type. 4576daed103193a1756535d1f59b165e98e1d17445Chris Banes * 4676daed103193a1756535d1f59b165e98e1d17445Chris Banes * <p>A view starting a nested scroll promises to abide by the following contract:</p> 4776daed103193a1756535d1f59b165e98e1d17445Chris Banes * 4876daed103193a1756535d1f59b165e98e1d17445Chris Banes * <p>The view will call startNestedScroll upon initiating a scroll operation. In the case 4976daed103193a1756535d1f59b165e98e1d17445Chris Banes * of a touch scroll type this corresponds to the initial {@link MotionEvent#ACTION_DOWN}. 5076daed103193a1756535d1f59b165e98e1d17445Chris Banes * In the case of touch scrolling the nested scroll will be terminated automatically in 5176daed103193a1756535d1f59b165e98e1d17445Chris Banes * the same manner as {@link ViewParent#requestDisallowInterceptTouchEvent(boolean)}. 5276daed103193a1756535d1f59b165e98e1d17445Chris Banes * In the event of programmatic scrolling the caller must explicitly call 5376daed103193a1756535d1f59b165e98e1d17445Chris Banes * {@link #stopNestedScroll(int)} to indicate the end of the nested scroll.</p> 5476daed103193a1756535d1f59b165e98e1d17445Chris Banes * 5576daed103193a1756535d1f59b165e98e1d17445Chris Banes * <p>If <code>startNestedScroll</code> returns true, a cooperative parent was found. 5676daed103193a1756535d1f59b165e98e1d17445Chris Banes * If it returns false the caller may ignore the rest of this contract until the next scroll. 5776daed103193a1756535d1f59b165e98e1d17445Chris Banes * Calling startNestedScroll while a nested scroll is already in progress will return true.</p> 5876daed103193a1756535d1f59b165e98e1d17445Chris Banes * 5976daed103193a1756535d1f59b165e98e1d17445Chris Banes * <p>At each incremental step of the scroll the caller should invoke 6076daed103193a1756535d1f59b165e98e1d17445Chris Banes * {@link #dispatchNestedPreScroll(int, int, int[], int[], int) dispatchNestedPreScroll} 6176daed103193a1756535d1f59b165e98e1d17445Chris Banes * once it has calculated the requested scrolling delta. If it returns true the nested scrolling 6276daed103193a1756535d1f59b165e98e1d17445Chris Banes * parent at least partially consumed the scroll and the caller should adjust the amount it 6376daed103193a1756535d1f59b165e98e1d17445Chris Banes * scrolls by.</p> 6476daed103193a1756535d1f59b165e98e1d17445Chris Banes * 6576daed103193a1756535d1f59b165e98e1d17445Chris Banes * <p>After applying the remainder of the scroll delta the caller should invoke 6676daed103193a1756535d1f59b165e98e1d17445Chris Banes * {@link #dispatchNestedScroll(int, int, int, int, int[], int) dispatchNestedScroll}, passing 6776daed103193a1756535d1f59b165e98e1d17445Chris Banes * both the delta consumed and the delta unconsumed. A nested scrolling parent may treat 6876daed103193a1756535d1f59b165e98e1d17445Chris Banes * these values differently. See 6976daed103193a1756535d1f59b165e98e1d17445Chris Banes * {@link NestedScrollingParent2#onNestedScroll(View, int, int, int, int, int)}. 7076daed103193a1756535d1f59b165e98e1d17445Chris Banes * </p> 7176daed103193a1756535d1f59b165e98e1d17445Chris Banes * 7276daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param axes Flags consisting of a combination of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL} 7376daed103193a1756535d1f59b165e98e1d17445Chris Banes * and/or {@link ViewCompat#SCROLL_AXIS_VERTICAL}. 7476daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param type the type of input which cause this scroll event 7576daed103193a1756535d1f59b165e98e1d17445Chris Banes * @return true if a cooperative parent was found and nested scrolling has been enabled for 7676daed103193a1756535d1f59b165e98e1d17445Chris Banes * the current gesture. 7776daed103193a1756535d1f59b165e98e1d17445Chris Banes * 7876daed103193a1756535d1f59b165e98e1d17445Chris Banes * @see #stopNestedScroll(int) 7976daed103193a1756535d1f59b165e98e1d17445Chris Banes * @see #dispatchNestedPreScroll(int, int, int[], int[], int) 8076daed103193a1756535d1f59b165e98e1d17445Chris Banes * @see #dispatchNestedScroll(int, int, int, int, int[], int) 8176daed103193a1756535d1f59b165e98e1d17445Chris Banes */ 8276daed103193a1756535d1f59b165e98e1d17445Chris Banes boolean startNestedScroll(@ScrollAxis int axes, @NestedScrollType int type); 8376daed103193a1756535d1f59b165e98e1d17445Chris Banes 8476daed103193a1756535d1f59b165e98e1d17445Chris Banes /** 8576daed103193a1756535d1f59b165e98e1d17445Chris Banes * Stop a nested scroll in progress for the given input type. 8676daed103193a1756535d1f59b165e98e1d17445Chris Banes * 8776daed103193a1756535d1f59b165e98e1d17445Chris Banes * <p>Calling this method when a nested scroll is not currently in progress is harmless.</p> 8876daed103193a1756535d1f59b165e98e1d17445Chris Banes * 8976daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param type the type of input which cause this scroll event 9076daed103193a1756535d1f59b165e98e1d17445Chris Banes * @see #startNestedScroll(int, int) 9176daed103193a1756535d1f59b165e98e1d17445Chris Banes */ 9276daed103193a1756535d1f59b165e98e1d17445Chris Banes void stopNestedScroll(@NestedScrollType int type); 9376daed103193a1756535d1f59b165e98e1d17445Chris Banes 9476daed103193a1756535d1f59b165e98e1d17445Chris Banes /** 9576daed103193a1756535d1f59b165e98e1d17445Chris Banes * Returns true if this view has a nested scrolling parent for the given input type. 9676daed103193a1756535d1f59b165e98e1d17445Chris Banes * 9776daed103193a1756535d1f59b165e98e1d17445Chris Banes * <p>The presence of a nested scrolling parent indicates that this view has initiated 9876daed103193a1756535d1f59b165e98e1d17445Chris Banes * a nested scroll and it was accepted by an ancestor view further up the view hierarchy.</p> 9976daed103193a1756535d1f59b165e98e1d17445Chris Banes * 10076daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param type the type of input which cause this scroll event 10176daed103193a1756535d1f59b165e98e1d17445Chris Banes * 10276daed103193a1756535d1f59b165e98e1d17445Chris Banes * @return whether this view has a nested scrolling parent 10376daed103193a1756535d1f59b165e98e1d17445Chris Banes */ 10476daed103193a1756535d1f59b165e98e1d17445Chris Banes boolean hasNestedScrollingParent(@NestedScrollType int type); 10576daed103193a1756535d1f59b165e98e1d17445Chris Banes 10676daed103193a1756535d1f59b165e98e1d17445Chris Banes /** 10776daed103193a1756535d1f59b165e98e1d17445Chris Banes * Dispatch one step of a nested scroll in progress. 10876daed103193a1756535d1f59b165e98e1d17445Chris Banes * 10976daed103193a1756535d1f59b165e98e1d17445Chris Banes * <p>Implementations of views that support nested scrolling should call this to report 11076daed103193a1756535d1f59b165e98e1d17445Chris Banes * info about a scroll in progress to the current nested scrolling parent. If a nested scroll 11176daed103193a1756535d1f59b165e98e1d17445Chris Banes * is not currently in progress or nested scrolling is not 11276daed103193a1756535d1f59b165e98e1d17445Chris Banes * {@link #isNestedScrollingEnabled() enabled} for this view this method does nothing.</p> 11376daed103193a1756535d1f59b165e98e1d17445Chris Banes * 11476daed103193a1756535d1f59b165e98e1d17445Chris Banes * <p>Compatible View implementations should also call 11576daed103193a1756535d1f59b165e98e1d17445Chris Banes * {@link #dispatchNestedPreScroll(int, int, int[], int[], int) dispatchNestedPreScroll} before 11676daed103193a1756535d1f59b165e98e1d17445Chris Banes * consuming a component of the scroll event themselves.</p> 11776daed103193a1756535d1f59b165e98e1d17445Chris Banes * 11876daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param dxConsumed Horizontal distance in pixels consumed by this view during this scroll step 11976daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param dyConsumed Vertical distance in pixels consumed by this view during this scroll step 12076daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param dxUnconsumed Horizontal scroll distance in pixels not consumed by this view 12176daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param dyUnconsumed Horizontal scroll distance in pixels not consumed by this view 12276daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param offsetInWindow Optional. If not null, on return this will contain the offset 12376daed103193a1756535d1f59b165e98e1d17445Chris Banes * in local view coordinates of this view from before this operation 12476daed103193a1756535d1f59b165e98e1d17445Chris Banes * to after it completes. View implementations may use this to adjust 12576daed103193a1756535d1f59b165e98e1d17445Chris Banes * expected input coordinate tracking. 12676daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param type the type of input which cause this scroll event 12776daed103193a1756535d1f59b165e98e1d17445Chris Banes * @return true if the event was dispatched, false if it could not be dispatched. 12876daed103193a1756535d1f59b165e98e1d17445Chris Banes * @see #dispatchNestedPreScroll(int, int, int[], int[], int) 12976daed103193a1756535d1f59b165e98e1d17445Chris Banes */ 13076daed103193a1756535d1f59b165e98e1d17445Chris Banes boolean dispatchNestedScroll(int dxConsumed, int dyConsumed, 13176daed103193a1756535d1f59b165e98e1d17445Chris Banes int dxUnconsumed, int dyUnconsumed, @Nullable int[] offsetInWindow, 13276daed103193a1756535d1f59b165e98e1d17445Chris Banes @NestedScrollType int type); 13376daed103193a1756535d1f59b165e98e1d17445Chris Banes 13476daed103193a1756535d1f59b165e98e1d17445Chris Banes /** 13576daed103193a1756535d1f59b165e98e1d17445Chris Banes * Dispatch one step of a nested scroll in progress before this view consumes any portion of it. 13676daed103193a1756535d1f59b165e98e1d17445Chris Banes * 13776daed103193a1756535d1f59b165e98e1d17445Chris Banes * <p>Nested pre-scroll events are to nested scroll events what touch intercept is to touch. 13876daed103193a1756535d1f59b165e98e1d17445Chris Banes * <code>dispatchNestedPreScroll</code> offers an opportunity for the parent view in a nested 13976daed103193a1756535d1f59b165e98e1d17445Chris Banes * scrolling operation to consume some or all of the scroll operation before the child view 14076daed103193a1756535d1f59b165e98e1d17445Chris Banes * consumes it.</p> 14176daed103193a1756535d1f59b165e98e1d17445Chris Banes * 14276daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param dx Horizontal scroll distance in pixels 14376daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param dy Vertical scroll distance in pixels 14476daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param consumed Output. If not null, consumed[0] will contain the consumed component of dx 14576daed103193a1756535d1f59b165e98e1d17445Chris Banes * and consumed[1] the consumed dy. 14676daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param offsetInWindow Optional. If not null, on return this will contain the offset 14776daed103193a1756535d1f59b165e98e1d17445Chris Banes * in local view coordinates of this view from before this operation 14876daed103193a1756535d1f59b165e98e1d17445Chris Banes * to after it completes. View implementations may use this to adjust 14976daed103193a1756535d1f59b165e98e1d17445Chris Banes * expected input coordinate tracking. 15076daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param type the type of input which cause this scroll event 15176daed103193a1756535d1f59b165e98e1d17445Chris Banes * @return true if the parent consumed some or all of the scroll delta 15276daed103193a1756535d1f59b165e98e1d17445Chris Banes * @see #dispatchNestedScroll(int, int, int, int, int[], int) 15376daed103193a1756535d1f59b165e98e1d17445Chris Banes */ 15476daed103193a1756535d1f59b165e98e1d17445Chris Banes boolean dispatchNestedPreScroll(int dx, int dy, @Nullable int[] consumed, 15576daed103193a1756535d1f59b165e98e1d17445Chris Banes @Nullable int[] offsetInWindow, @NestedScrollType int type); 15676daed103193a1756535d1f59b165e98e1d17445Chris Banes} 157