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 18 package android.support.v4.view; 19 20 import android.support.annotation.NonNull; 21 import android.support.v4.view.ViewCompat.ScrollAxis; 22 import android.view.MotionEvent; 23 import android.view.VelocityTracker; 24 import android.view.View; 25 import android.view.ViewConfiguration; 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 Android 38 * 5.0 Lollipop and newer.</p> 39 */ 40 public interface 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)}. 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 * @return true if this ViewParent accepts the nested scroll operation 62 */ onStartNestedScroll(@onNull View child, @NonNull View target, @ScrollAxis int axes)63 boolean onStartNestedScroll(@NonNull View child, @NonNull View target, @ScrollAxis int axes); 64 65 /** 66 * React to the successful claiming of a nested scroll operation. 67 * 68 * <p>This method will be called after 69 * {@link #onStartNestedScroll(View, View, int) onStartNestedScroll} returns true. It offers 70 * an opportunity for the view and its superclasses to perform initial configuration 71 * for the nested scroll. Implementations of this method should always call their superclass's 72 * implementation of this method if one is present.</p> 73 * 74 * @param child Direct child of this ViewParent containing target 75 * @param target View that initiated the nested scroll 76 * @param axes Flags consisting of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL}, 77 * {@link ViewCompat#SCROLL_AXIS_VERTICAL} or both 78 * @see #onStartNestedScroll(View, View, int) 79 * @see #onStopNestedScroll(View) 80 */ onNestedScrollAccepted(@onNull View child, @NonNull View target, @ScrollAxis int axes)81 void onNestedScrollAccepted(@NonNull View child, @NonNull View target, @ScrollAxis int axes); 82 83 /** 84 * React to a nested scroll operation ending. 85 * 86 * <p>Perform cleanup after a nested scrolling operation. 87 * This method will be called when a nested scroll stops, for example when a nested touch 88 * scroll ends with a {@link MotionEvent#ACTION_UP} or {@link MotionEvent#ACTION_CANCEL} event. 89 * Implementations of this method should always call their superclass's implementation of this 90 * method if one is present.</p> 91 * 92 * @param target View that initiated the nested scroll 93 */ onStopNestedScroll(@onNull View target)94 void onStopNestedScroll(@NonNull View target); 95 96 /** 97 * React to a nested scroll in progress. 98 * 99 * <p>This method will be called when the ViewParent's current nested scrolling child view 100 * dispatches a nested scroll event. To receive calls to this method the ViewParent must have 101 * previously returned <code>true</code> for a call to 102 * {@link #onStartNestedScroll(View, View, int)}.</p> 103 * 104 * <p>Both the consumed and unconsumed portions of the scroll distance are reported to the 105 * ViewParent. An implementation may choose to use the consumed portion to match or chase scroll 106 * position of multiple child elements, for example. The unconsumed portion may be used to 107 * allow continuous dragging of multiple scrolling or draggable elements, such as scrolling 108 * a list within a vertical drawer where the drawer begins dragging once the edge of inner 109 * scrolling content is reached.</p> 110 * 111 * @param target The descendent view controlling the nested scroll 112 * @param dxConsumed Horizontal scroll distance in pixels already consumed by target 113 * @param dyConsumed Vertical scroll distance in pixels already consumed by target 114 * @param dxUnconsumed Horizontal scroll distance in pixels not consumed by target 115 * @param dyUnconsumed Vertical scroll distance in pixels not consumed by target 116 */ onNestedScroll(@onNull View target, int dxConsumed, int dyConsumed, int dxUnconsumed, int dyUnconsumed)117 void onNestedScroll(@NonNull View target, int dxConsumed, int dyConsumed, 118 int dxUnconsumed, int dyUnconsumed); 119 120 /** 121 * React to a nested scroll in progress before the target view consumes a portion of the scroll. 122 * 123 * <p>When working with nested scrolling often the parent view may want an opportunity 124 * to consume the scroll before the nested scrolling child does. An example of this is a 125 * drawer that contains a scrollable list. The user will want to be able to scroll the list 126 * fully into view before the list itself begins scrolling.</p> 127 * 128 * <p><code>onNestedPreScroll</code> is called when a nested scrolling child invokes 129 * {@link View#dispatchNestedPreScroll(int, int, int[], int[])}. The implementation should 130 * report how any pixels of the scroll reported by dx, dy were consumed in the 131 * <code>consumed</code> array. Index 0 corresponds to dx and index 1 corresponds to dy. 132 * This parameter will never be null. Initial values for consumed[0] and consumed[1] 133 * will always be 0.</p> 134 * 135 * @param target View that initiated the nested scroll 136 * @param dx Horizontal scroll distance in pixels 137 * @param dy Vertical scroll distance in pixels 138 * @param consumed Output. The horizontal and vertical scroll distance consumed by this parent 139 */ onNestedPreScroll(@onNull View target, int dx, int dy, @NonNull int[] consumed)140 void onNestedPreScroll(@NonNull View target, int dx, int dy, @NonNull int[] consumed); 141 142 /** 143 * Request a fling from a nested scroll. 144 * 145 * <p>This method signifies that a nested scrolling child has detected suitable conditions 146 * for a fling. Generally this means that a touch scroll has ended with a 147 * {@link VelocityTracker velocity} in the direction of scrolling that meets or exceeds 148 * the {@link ViewConfiguration#getScaledMinimumFlingVelocity() minimum fling velocity} 149 * along a scrollable axis.</p> 150 * 151 * <p>If a nested scrolling child view would normally fling but it is at the edge of 152 * its own content, it can use this method to delegate the fling to its nested scrolling 153 * parent instead. The parent may optionally consume the fling or observe a child fling.</p> 154 * 155 * @param target View that initiated the nested scroll 156 * @param velocityX Horizontal velocity in pixels per second 157 * @param velocityY Vertical velocity in pixels per second 158 * @param consumed true if the child consumed the fling, false otherwise 159 * @return true if this parent consumed or otherwise reacted to the fling 160 */ onNestedFling(@onNull View target, float velocityX, float velocityY, boolean consumed)161 boolean onNestedFling(@NonNull View target, float velocityX, float velocityY, boolean consumed); 162 163 /** 164 * React to a nested fling before the target view consumes it. 165 * 166 * <p>This method siginfies that a nested scrolling child has detected a fling with the given 167 * velocity along each axis. Generally this means that a touch scroll has ended with a 168 * {@link VelocityTracker velocity} in the direction of scrolling that meets or exceeds 169 * the {@link ViewConfiguration#getScaledMinimumFlingVelocity() minimum fling velocity} 170 * along a scrollable axis.</p> 171 * 172 * <p>If a nested scrolling parent is consuming motion as part of a 173 * {@link #onNestedPreScroll(View, int, int, int[]) pre-scroll}, it may be appropriate for 174 * it to also consume the pre-fling to complete that same motion. By returning 175 * <code>true</code> from this method, the parent indicates that the child should not 176 * fling its own internal content as well.</p> 177 * 178 * @param target View that initiated the nested scroll 179 * @param velocityX Horizontal velocity in pixels per second 180 * @param velocityY Vertical velocity in pixels per second 181 * @return true if this parent consumed the fling ahead of the target view 182 */ onNestedPreFling(@onNull View target, float velocityX, float velocityY)183 boolean onNestedPreFling(@NonNull View target, float velocityX, float velocityY); 184 185 /** 186 * Return the current axes of nested scrolling for this NestedScrollingParent. 187 * 188 * <p>A NestedScrollingParent returning something other than {@link ViewCompat#SCROLL_AXIS_NONE} 189 * is currently acting as a nested scrolling parent for one or more descendant views in 190 * the hierarchy.</p> 191 * 192 * @return Flags indicating the current axes of nested scrolling 193 * @see ViewCompat#SCROLL_AXIS_HORIZONTAL 194 * @see ViewCompat#SCROLL_AXIS_VERTICAL 195 * @see ViewCompat#SCROLL_AXIS_NONE 196 */ 197 @ScrollAxis getNestedScrollAxes()198 int getNestedScrollAxes(); 199 } 200