11fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell/* 21fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * Copyright (C) 2015 The Android Open Source Project 31fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 41fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * Licensed under the Apache License, Version 2.0 (the "License"); 51fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * you may not use this file except in compliance with the License. 61fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * You may obtain a copy of the License at 71fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 81fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * http://www.apache.org/licenses/LICENSE-2.0 91fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 101fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * Unless required by applicable law or agreed to in writing, software 111fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * distributed under the License is distributed on an "AS IS" BASIS, 121fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 131fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * See the License for the specific language governing permissions and 141fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * limitations under the License. 151fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell */ 161fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell 171fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell 181fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powellpackage android.support.v4.view; 191fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell 2076daed103193a1756535d1f59b165e98e1d17445Chris Banesimport android.support.annotation.NonNull; 2176daed103193a1756535d1f59b165e98e1d17445Chris Banesimport android.support.v4.view.ViewCompat.ScrollAxis; 221fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powellimport android.view.MotionEvent; 231fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powellimport android.view.VelocityTracker; 241fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powellimport android.view.View; 251fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powellimport android.view.ViewConfiguration; 261fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell 271fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell/** 281fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * This interface should be implemented by {@link android.view.ViewGroup ViewGroup} subclasses 291fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * that wish to support scrolling operations delegated by a nested child view. 301fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 311fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <p>Classes implementing this interface should create a final instance of a 321fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * {@link NestedScrollingParentHelper} as a field and delegate any View or ViewGroup methods 331fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * to the <code>NestedScrollingParentHelper</code> methods of the same signature.</p> 341fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 351fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <p>Views invoking nested scrolling functionality should always do so from the relevant 361fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * {@link ViewCompat}, {@link ViewGroupCompat} or {@link ViewParentCompat} compatibility 371fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * shim static methods. This ensures interoperability with nested scrolling views on Android 381fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 5.0 Lollipop and newer.</p> 391fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell */ 401fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powellpublic interface NestedScrollingParent { 411fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell /** 421fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * React to a descendant view initiating a nestable scroll operation, claiming the 431fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * nested scroll operation if appropriate. 441fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 451fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <p>This method will be called in response to a descendant view invoking 461fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * {@link ViewCompat#startNestedScroll(View, int)}. Each parent up the view hierarchy will be 471fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * given an opportunity to respond and claim the nested scrolling operation by returning 481fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <code>true</code>.</p> 491fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 501fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <p>This method may be overridden by ViewParent implementations to indicate when the view 511fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * is willing to support a nested scrolling operation that is about to begin. If it returns 521fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * true, this ViewParent will become the target view's nested scrolling parent for the duration 531fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * of the scroll operation in progress. When the nested scroll is finished this ViewParent 541fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * will receive a call to {@link #onStopNestedScroll(View)}. 551fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * </p> 561fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 571fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param child Direct child of this ViewParent containing target 581fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param target View that initiated the nested scroll 5976daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param axes Flags consisting of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL}, 601fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * {@link ViewCompat#SCROLL_AXIS_VERTICAL} or both 611fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @return true if this ViewParent accepts the nested scroll operation 621fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell */ 6376daed103193a1756535d1f59b165e98e1d17445Chris Banes boolean onStartNestedScroll(@NonNull View child, @NonNull View target, @ScrollAxis int axes); 641fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell 651fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell /** 661fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * React to the successful claiming of a nested scroll operation. 671fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 681fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <p>This method will be called after 691fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * {@link #onStartNestedScroll(View, View, int) onStartNestedScroll} returns true. It offers 701fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * an opportunity for the view and its superclasses to perform initial configuration 711fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * for the nested scroll. Implementations of this method should always call their superclass's 721fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * implementation of this method if one is present.</p> 731fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 741fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param child Direct child of this ViewParent containing target 751fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param target View that initiated the nested scroll 7676daed103193a1756535d1f59b165e98e1d17445Chris Banes * @param axes Flags consisting of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL}, 771fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * {@link ViewCompat#SCROLL_AXIS_VERTICAL} or both 781fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @see #onStartNestedScroll(View, View, int) 791fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @see #onStopNestedScroll(View) 801fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell */ 8176daed103193a1756535d1f59b165e98e1d17445Chris Banes void onNestedScrollAccepted(@NonNull View child, @NonNull View target, @ScrollAxis int axes); 821fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell 831fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell /** 841fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * React to a nested scroll operation ending. 851fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 861fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <p>Perform cleanup after a nested scrolling operation. 871fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * This method will be called when a nested scroll stops, for example when a nested touch 881fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * scroll ends with a {@link MotionEvent#ACTION_UP} or {@link MotionEvent#ACTION_CANCEL} event. 891fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * Implementations of this method should always call their superclass's implementation of this 901fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * method if one is present.</p> 911fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 921fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param target View that initiated the nested scroll 931fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell */ 9476daed103193a1756535d1f59b165e98e1d17445Chris Banes void onStopNestedScroll(@NonNull View target); 951fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell 961fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell /** 971fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * React to a nested scroll in progress. 981fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 991fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <p>This method will be called when the ViewParent's current nested scrolling child view 1001fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * dispatches a nested scroll event. To receive calls to this method the ViewParent must have 1011fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * previously returned <code>true</code> for a call to 1021fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * {@link #onStartNestedScroll(View, View, int)}.</p> 1031fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 1041fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <p>Both the consumed and unconsumed portions of the scroll distance are reported to the 1051fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * ViewParent. An implementation may choose to use the consumed portion to match or chase scroll 1061fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * position of multiple child elements, for example. The unconsumed portion may be used to 1071fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * allow continuous dragging of multiple scrolling or draggable elements, such as scrolling 1081fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * a list within a vertical drawer where the drawer begins dragging once the edge of inner 1091fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * scrolling content is reached.</p> 1101fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 1111fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param target The descendent view controlling the nested scroll 1121fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param dxConsumed Horizontal scroll distance in pixels already consumed by target 1131fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param dyConsumed Vertical scroll distance in pixels already consumed by target 1141fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param dxUnconsumed Horizontal scroll distance in pixels not consumed by target 1151fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param dyUnconsumed Vertical scroll distance in pixels not consumed by target 1161fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell */ 11776daed103193a1756535d1f59b165e98e1d17445Chris Banes void onNestedScroll(@NonNull View target, int dxConsumed, int dyConsumed, 1181fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell int dxUnconsumed, int dyUnconsumed); 1191fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell 1201fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell /** 1211fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * React to a nested scroll in progress before the target view consumes a portion of the scroll. 1221fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 1231fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <p>When working with nested scrolling often the parent view may want an opportunity 1241fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * to consume the scroll before the nested scrolling child does. An example of this is a 1251fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * drawer that contains a scrollable list. The user will want to be able to scroll the list 1261fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * fully into view before the list itself begins scrolling.</p> 1271fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 1281fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <p><code>onNestedPreScroll</code> is called when a nested scrolling child invokes 1291fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * {@link View#dispatchNestedPreScroll(int, int, int[], int[])}. The implementation should 1301fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * report how any pixels of the scroll reported by dx, dy were consumed in the 1311fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <code>consumed</code> array. Index 0 corresponds to dx and index 1 corresponds to dy. 1321fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * This parameter will never be null. Initial values for consumed[0] and consumed[1] 1331fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * will always be 0.</p> 1341fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 1351fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param target View that initiated the nested scroll 1361fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param dx Horizontal scroll distance in pixels 1371fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param dy Vertical scroll distance in pixels 1381fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param consumed Output. The horizontal and vertical scroll distance consumed by this parent 1391fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell */ 14076daed103193a1756535d1f59b165e98e1d17445Chris Banes void onNestedPreScroll(@NonNull View target, int dx, int dy, @NonNull int[] consumed); 1411fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell 1421fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell /** 1431fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * Request a fling from a nested scroll. 1441fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 1451fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <p>This method signifies that a nested scrolling child has detected suitable conditions 1461fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * for a fling. Generally this means that a touch scroll has ended with a 1471fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * {@link VelocityTracker velocity} in the direction of scrolling that meets or exceeds 1481fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * the {@link ViewConfiguration#getScaledMinimumFlingVelocity() minimum fling velocity} 1491fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * along a scrollable axis.</p> 1501fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 1511fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <p>If a nested scrolling child view would normally fling but it is at the edge of 1521fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * its own content, it can use this method to delegate the fling to its nested scrolling 1531fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * parent instead. The parent may optionally consume the fling or observe a child fling.</p> 1541fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 1551fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param target View that initiated the nested scroll 1561fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param velocityX Horizontal velocity in pixels per second 1571fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param velocityY Vertical velocity in pixels per second 1581fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param consumed true if the child consumed the fling, false otherwise 1591fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @return true if this parent consumed or otherwise reacted to the fling 1601fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell */ 16176daed103193a1756535d1f59b165e98e1d17445Chris Banes boolean onNestedFling(@NonNull View target, float velocityX, float velocityY, boolean consumed); 1621fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell 1631fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell /** 1641fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * React to a nested fling before the target view consumes it. 1651fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 1661fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <p>This method siginfies that a nested scrolling child has detected a fling with the given 1671fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * velocity along each axis. Generally this means that a touch scroll has ended with a 1681fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * {@link VelocityTracker velocity} in the direction of scrolling that meets or exceeds 1691fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * the {@link ViewConfiguration#getScaledMinimumFlingVelocity() minimum fling velocity} 1701fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * along a scrollable axis.</p> 1711fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 1721fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <p>If a nested scrolling parent is consuming motion as part of a 1731fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * {@link #onNestedPreScroll(View, int, int, int[]) pre-scroll}, it may be appropriate for 1741fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * it to also consume the pre-fling to complete that same motion. By returning 1751fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <code>true</code> from this method, the parent indicates that the child should not 1761fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * fling its own internal content as well.</p> 1771fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 1781fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param target View that initiated the nested scroll 1791fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param velocityX Horizontal velocity in pixels per second 1801fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @param velocityY Vertical velocity in pixels per second 1811fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @return true if this parent consumed the fling ahead of the target view 1821fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell */ 18376daed103193a1756535d1f59b165e98e1d17445Chris Banes boolean onNestedPreFling(@NonNull View target, float velocityX, float velocityY); 1841fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell 1851fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell /** 1861fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * Return the current axes of nested scrolling for this NestedScrollingParent. 1871fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 1881fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * <p>A NestedScrollingParent returning something other than {@link ViewCompat#SCROLL_AXIS_NONE} 1891fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * is currently acting as a nested scrolling parent for one or more descendant views in 1901fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * the hierarchy.</p> 1911fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * 1921fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @return Flags indicating the current axes of nested scrolling 1931fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @see ViewCompat#SCROLL_AXIS_HORIZONTAL 1941fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @see ViewCompat#SCROLL_AXIS_VERTICAL 1951fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell * @see ViewCompat#SCROLL_AXIS_NONE 1961fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell */ 19776daed103193a1756535d1f59b165e98e1d17445Chris Banes @ScrollAxis 19876daed103193a1756535d1f59b165e98e1d17445Chris Banes int getNestedScrollAxes(); 1991fcce4485ef99aca928ebfb877859c5ecd47716cAdam Powell} 200