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 18 package androidx.core.view; 19 20 import android.view.MotionEvent; 21 import android.view.VelocityTracker; 22 import android.view.View; 23 import android.view.ViewConfiguration; 24 import android.view.ViewParent; 25 26 import androidx.core.view.ViewCompat.ScrollAxis; 27 28 import org.jspecify.annotations.Nullable; 29 30 /** 31 * This interface should be implemented by {@link android.view.View View} subclasses that wish 32 * to support dispatching nested scrolling operations to a cooperating parent 33 * {@link android.view.ViewGroup ViewGroup}. 34 * 35 * <p>Classes implementing this interface should create a final instance of a 36 * {@link NestedScrollingChildHelper} as a field and delegate any View methods to the 37 * <code>NestedScrollingChildHelper</code> methods of the same signature.</p> 38 * 39 * <p>Views invoking nested scrolling functionality should always do so from the relevant 40 * {@link ViewCompat}, {@link ViewGroupCompat} or {@link ViewParentCompat} compatibility 41 * shim static methods. This ensures interoperability with nested scrolling views on Android 42 * 5.0 Lollipop and newer.</p> 43 */ 44 public interface NestedScrollingChild { 45 /** 46 * Enable or disable nested scrolling for this view. 47 * 48 * <p>If this property is set to true the view will be permitted to initiate nested 49 * scrolling operations with a compatible parent view in the current hierarchy. If this 50 * view does not implement nested scrolling this will have no effect. Disabling nested scrolling 51 * while a nested scroll is in progress has the effect of {@link #stopNestedScroll() stopping} 52 * the nested scroll.</p> 53 * 54 * @param enabled true to enable nested scrolling, false to disable 55 * 56 * @see #isNestedScrollingEnabled() 57 */ setNestedScrollingEnabled(boolean enabled)58 void setNestedScrollingEnabled(boolean enabled); 59 60 /** 61 * Returns true if nested scrolling is enabled for this view. 62 * 63 * <p>If nested scrolling is enabled and this View class implementation supports it, 64 * this view will act as a nested scrolling child view when applicable, forwarding data 65 * about the scroll operation in progress to a compatible and cooperating nested scrolling 66 * parent.</p> 67 * 68 * @return true if nested scrolling is enabled 69 * 70 * @see #setNestedScrollingEnabled(boolean) 71 */ isNestedScrollingEnabled()72 boolean isNestedScrollingEnabled(); 73 74 /** 75 * Begin a nestable scroll operation along the given axes. 76 * 77 * <p>A view starting a nested scroll promises to abide by the following contract:</p> 78 * 79 * <p>The view will call startNestedScroll upon initiating a scroll operation. In the case 80 * of a touch scroll this corresponds to the initial {@link MotionEvent#ACTION_DOWN}. 81 * In the case of touch scrolling the nested scroll will be terminated automatically in 82 * the same manner as {@link ViewParent#requestDisallowInterceptTouchEvent(boolean)}. 83 * In the event of programmatic scrolling the caller must explicitly call 84 * {@link #stopNestedScroll()} to indicate the end of the nested scroll.</p> 85 * 86 * <p>If <code>startNestedScroll</code> returns true, a cooperative parent was found. 87 * If it returns false the caller may ignore the rest of this contract until the next scroll. 88 * Calling startNestedScroll while a nested scroll is already in progress will return true.</p> 89 * 90 * <p>At each incremental step of the scroll the caller should invoke 91 * {@link #dispatchNestedPreScroll(int, int, int[], int[]) dispatchNestedPreScroll} 92 * once it has calculated the requested scrolling delta. If it returns true the nested scrolling 93 * parent at least partially consumed the scroll and the caller should adjust the amount it 94 * scrolls by.</p> 95 * 96 * <p>After applying the remainder of the scroll delta the caller should invoke 97 * {@link #dispatchNestedScroll(int, int, int, int, int[]) dispatchNestedScroll}, passing 98 * both the delta consumed and the delta unconsumed. A nested scrolling parent may treat 99 * these values differently. See 100 * {@link NestedScrollingParent#onNestedScroll(View, int, int, int, int)}. 101 * </p> 102 * 103 * @param axes Flags consisting of a combination of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL} 104 * and/or {@link ViewCompat#SCROLL_AXIS_VERTICAL}. 105 * @return true if a cooperative parent was found and nested scrolling has been enabled for 106 * the current gesture. 107 * 108 * @see #stopNestedScroll() 109 * @see #dispatchNestedPreScroll(int, int, int[], int[]) 110 * @see #dispatchNestedScroll(int, int, int, int, int[]) 111 */ startNestedScroll(@crollAxis int axes)112 boolean startNestedScroll(@ScrollAxis int axes); 113 114 /** 115 * Stop a nested scroll in progress. 116 * 117 * <p>Calling this method when a nested scroll is not currently in progress is harmless.</p> 118 * 119 * @see #startNestedScroll(int) 120 */ stopNestedScroll()121 void stopNestedScroll(); 122 123 /** 124 * Returns true if this view has a nested scrolling parent. 125 * 126 * <p>The presence of a nested scrolling parent indicates that this view has initiated 127 * a nested scroll and it was accepted by an ancestor view further up the view hierarchy.</p> 128 * 129 * @return whether this view has a nested scrolling parent 130 */ hasNestedScrollingParent()131 boolean hasNestedScrollingParent(); 132 133 /** 134 * Dispatch one step of a nested scroll in progress. 135 * 136 * <p>Implementations of views that support nested scrolling should call this to report 137 * info about a scroll in progress to the current nested scrolling parent. If a nested scroll 138 * is not currently in progress or nested scrolling is not 139 * {@link #isNestedScrollingEnabled() enabled} for this view this method does nothing.</p> 140 * 141 * <p>Compatible View implementations should also call 142 * {@link #dispatchNestedPreScroll(int, int, int[], int[]) dispatchNestedPreScroll} before 143 * consuming a component of the scroll event themselves.</p> 144 * 145 * @param dxConsumed Horizontal distance in pixels consumed by this view during this scroll step 146 * @param dyConsumed Vertical distance in pixels consumed by this view during this scroll step 147 * @param dxUnconsumed Horizontal scroll distance in pixels not consumed by this view 148 * @param dyUnconsumed Horizontal scroll distance in pixels not consumed by this view 149 * @param offsetInWindow Optional. If not null, on return this will contain the offset 150 * in local view coordinates of this view from before this operation 151 * to after it completes. View implementations may use this to adjust 152 * expected input coordinate tracking. 153 * @return true if the event was dispatched, false if it could not be dispatched. 154 * @see #dispatchNestedPreScroll(int, int, int[], int[]) 155 */ dispatchNestedScroll(int dxConsumed, int dyConsumed, int dxUnconsumed, int dyUnconsumed, int @Nullable [] offsetInWindow)156 boolean dispatchNestedScroll(int dxConsumed, int dyConsumed, 157 int dxUnconsumed, int dyUnconsumed, int @Nullable [] offsetInWindow); 158 159 /** 160 * Dispatch one step of a nested scroll in progress before this view consumes any portion of it. 161 * 162 * <p>Nested pre-scroll events are to nested scroll events what touch intercept is to touch. 163 * <code>dispatchNestedPreScroll</code> offers an opportunity for the parent view in a nested 164 * scrolling operation to consume some or all of the scroll operation before the child view 165 * consumes it.</p> 166 * 167 * @param dx Horizontal scroll distance in pixels 168 * @param dy Vertical scroll distance in pixels 169 * @param consumed Output. If not null, consumed[0] will contain the consumed component of dx 170 * and consumed[1] the consumed dy. 171 * @param offsetInWindow Optional. If not null, on return this will contain the offset 172 * in local view coordinates of this view from before this operation 173 * to after it completes. View implementations may use this to adjust 174 * expected input coordinate tracking. 175 * @return true if the parent consumed some or all of the scroll delta 176 * @see #dispatchNestedScroll(int, int, int, int, int[]) 177 */ dispatchNestedPreScroll(int dx, int dy, int @Nullable [] consumed, int @Nullable [] offsetInWindow)178 boolean dispatchNestedPreScroll(int dx, int dy, int @Nullable [] consumed, 179 int @Nullable [] offsetInWindow); 180 181 /** 182 * Dispatch a fling to a nested scrolling parent. 183 * 184 * <p>This method should be used to indicate that a nested scrolling child has detected 185 * suitable conditions for a fling. Generally this means that a touch scroll has ended with a 186 * {@link VelocityTracker velocity} in the direction of scrolling that meets or exceeds 187 * the {@link ViewConfiguration#getScaledMinimumFlingVelocity() minimum fling velocity} 188 * along a scrollable axis.</p> 189 * 190 * <p>If a nested scrolling child view would normally fling but it is at the edge of 191 * its own content, it can use this method to delegate the fling to its nested scrolling 192 * parent instead. The parent may optionally consume the fling or observe a child fling.</p> 193 * 194 * @param velocityX Horizontal fling velocity in pixels per second 195 * @param velocityY Vertical fling velocity in pixels per second 196 * @param consumed true if the child consumed the fling, false otherwise 197 * @return true if the nested scrolling parent consumed or otherwise reacted to the fling 198 */ dispatchNestedFling(float velocityX, float velocityY, boolean consumed)199 boolean dispatchNestedFling(float velocityX, float velocityY, boolean consumed); 200 201 /** 202 * Dispatch a fling to a nested scrolling parent before it is processed by this view. 203 * 204 * <p>Nested pre-fling events are to nested fling events what touch intercept is to touch 205 * and what nested pre-scroll is to nested scroll. <code>dispatchNestedPreFling</code> 206 * offsets an opportunity for the parent view in a nested fling to fully consume the fling 207 * before the child view consumes it. If this method returns <code>true</code>, a nested 208 * parent view consumed the fling and this view should not scroll as a result.</p> 209 * 210 * <p>For a better user experience, only one view in a nested scrolling chain should consume 211 * the fling at a time. If a parent view consumed the fling this method will return false. 212 * Custom view implementations should account for this in two ways:</p> 213 * 214 * <ul> 215 * <li>If a custom view is paged and needs to settle to a fixed page-point, do not 216 * call <code>dispatchNestedPreFling</code>; consume the fling and settle to a valid 217 * position regardless.</li> 218 * <li>If a nested parent does consume the fling, this view should not scroll at all, 219 * even to settle back to a valid idle position.</li> 220 * </ul> 221 * 222 * <p>Views should also not offer fling velocities to nested parent views along an axis 223 * where scrolling is not currently supported; a {@link android.widget.ScrollView ScrollView} 224 * should not offer a horizontal fling velocity to its parents since scrolling along that 225 * axis is not permitted and carrying velocity along that motion does not make sense.</p> 226 * 227 * @param velocityX Horizontal fling velocity in pixels per second 228 * @param velocityY Vertical fling velocity in pixels per second 229 * @return true if a nested scrolling parent consumed the fling 230 */ dispatchNestedPreFling(float velocityX, float velocityY)231 boolean dispatchNestedPreFling(float velocityX, float velocityY); 232 } 233