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.View; 22 import android.view.ViewParent; 23 24 import androidx.core.view.ViewCompat.NestedScrollType; 25 import androidx.core.view.ViewCompat.ScrollAxis; 26 27 import org.jspecify.annotations.Nullable; 28 29 /** 30 * This interface should be implemented by {@link View View} subclasses that wish 31 * to support dispatching nested scrolling operations to a cooperating parent 32 * {@link android.view.ViewGroup ViewGroup}. 33 * 34 * <p>Classes implementing this interface should create a final instance of a 35 * {@link NestedScrollingChildHelper} as a field and delegate any View methods to the 36 * <code>NestedScrollingChildHelper</code> methods of the same signature.</p> 37 * 38 * <p>Views invoking nested scrolling functionality should always do so from the relevant 39 * {@link ViewCompat}, {@link ViewGroupCompat} or {@link ViewParentCompat} compatibility 40 * shim static methods. This ensures interoperability with nested scrolling views on all versions 41 * of Android.</p> 42 */ 43 public interface NestedScrollingChild2 extends NestedScrollingChild { 44 45 /** 46 * Begin a nestable scroll operation along the given axes, for the given input type. 47 * 48 * <p>A view starting a nested scroll promises to abide by the following contract:</p> 49 * 50 * <p>The view will call startNestedScroll upon initiating a scroll operation. In the case 51 * of a touch scroll type this corresponds to the initial {@link MotionEvent#ACTION_DOWN}. 52 * In the case of touch scrolling the nested scroll will be terminated automatically in 53 * the same manner as {@link ViewParent#requestDisallowInterceptTouchEvent(boolean)}. 54 * In the event of programmatic scrolling the caller must explicitly call 55 * {@link #stopNestedScroll(int)} to indicate the end of the nested scroll.</p> 56 * 57 * <p>If <code>startNestedScroll</code> returns true, a cooperative parent was found. 58 * If it returns false the caller may ignore the rest of this contract until the next scroll. 59 * Calling startNestedScroll while a nested scroll is already in progress will return true.</p> 60 * 61 * <p>At each incremental step of the scroll the caller should invoke 62 * {@link #dispatchNestedPreScroll(int, int, int[], int[], int) dispatchNestedPreScroll} 63 * once it has calculated the requested scrolling delta. If it returns true the nested scrolling 64 * parent at least partially consumed the scroll and the caller should adjust the amount it 65 * scrolls by.</p> 66 * 67 * <p>After applying the remainder of the scroll delta the caller should invoke 68 * {@link #dispatchNestedScroll(int, int, int, int, int[], int) dispatchNestedScroll}, passing 69 * both the delta consumed and the delta unconsumed. A nested scrolling parent may treat 70 * these values differently. See 71 * {@link NestedScrollingParent2#onNestedScroll(View, int, int, int, int, int)}. 72 * </p> 73 * 74 * @param axes Flags consisting of a combination of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL} 75 * and/or {@link ViewCompat#SCROLL_AXIS_VERTICAL}. 76 * @param type the type of input which cause this scroll event 77 * @return true if a cooperative parent was found and nested scrolling has been enabled for 78 * the current gesture. 79 * 80 * @see #stopNestedScroll(int) 81 * @see #dispatchNestedPreScroll(int, int, int[], int[], int) 82 * @see #dispatchNestedScroll(int, int, int, int, int[], int) 83 */ startNestedScroll(@crollAxis int axes, @NestedScrollType int type)84 boolean startNestedScroll(@ScrollAxis int axes, @NestedScrollType int type); 85 86 /** 87 * Stop a nested scroll in progress for the given input type. 88 * 89 * <p>Calling this method when a nested scroll is not currently in progress is harmless.</p> 90 * 91 * @param type the type of input which cause this scroll event 92 * @see #startNestedScroll(int, int) 93 */ stopNestedScroll(@estedScrollType int type)94 void stopNestedScroll(@NestedScrollType int type); 95 96 /** 97 * Returns true if this view has a nested scrolling parent for the given input type. 98 * 99 * <p>The presence of a nested scrolling parent indicates that this view has initiated 100 * a nested scroll and it was accepted by an ancestor view further up the view hierarchy.</p> 101 * 102 * @param type the type of input which cause this scroll event 103 * 104 * @return whether this view has a nested scrolling parent 105 */ hasNestedScrollingParent(@estedScrollType int type)106 boolean hasNestedScrollingParent(@NestedScrollType int type); 107 108 /** 109 * Dispatch one step of a nested scroll in progress. 110 * 111 * <p>Implementations of views that support nested scrolling should call this to report 112 * info about a scroll in progress to the current nested scrolling parent. If a nested scroll 113 * is not currently in progress or nested scrolling is not 114 * {@link #isNestedScrollingEnabled() enabled} for this view this method does nothing.</p> 115 * 116 * <p>Compatible View implementations should also call 117 * {@link #dispatchNestedPreScroll(int, int, int[], int[], int) dispatchNestedPreScroll} before 118 * consuming a component of the scroll event themselves.</p> 119 * 120 * @param dxConsumed Horizontal distance in pixels consumed by this view during this scroll step 121 * @param dyConsumed Vertical distance in pixels consumed by this view during this scroll step 122 * @param dxUnconsumed Horizontal scroll distance in pixels not consumed by this view 123 * @param dyUnconsumed Horizontal scroll distance in pixels not consumed by this view 124 * @param offsetInWindow Optional. If not null, on return this will contain the offset 125 * in local view coordinates of this view from before this operation 126 * to after it completes. View implementations may use this to adjust 127 * expected input coordinate tracking. 128 * @param type the type of input which cause this scroll event 129 * @return true if the event was dispatched, false if it could not be dispatched. 130 * @see #dispatchNestedPreScroll(int, int, int[], int[], int) 131 */ dispatchNestedScroll(int dxConsumed, int dyConsumed, int dxUnconsumed, int dyUnconsumed, int @Nullable [] offsetInWindow, @NestedScrollType int type)132 boolean dispatchNestedScroll(int dxConsumed, int dyConsumed, 133 int dxUnconsumed, int dyUnconsumed, int @Nullable [] offsetInWindow, 134 @NestedScrollType int type); 135 136 /** 137 * Dispatch one step of a nested scroll in progress before this view consumes any portion of it. 138 * 139 * <p>Nested pre-scroll events are to nested scroll events what touch intercept is to touch. 140 * <code>dispatchNestedPreScroll</code> offers an opportunity for the parent view in a nested 141 * scrolling operation to consume some or all of the scroll operation before the child view 142 * consumes it.</p> 143 * 144 * @param dx Horizontal scroll distance in pixels 145 * @param dy Vertical scroll distance in pixels 146 * @param consumed Output. If not null, consumed[0] will contain the consumed component of dx 147 * and consumed[1] the consumed dy. 148 * @param offsetInWindow Optional. If not null, on return this will contain the offset 149 * in local view coordinates of this view from before this operation 150 * to after it completes. View implementations may use this to adjust 151 * expected input coordinate tracking. 152 * @param type the type of input which cause this scroll event 153 * @return true if the parent consumed some or all of the scroll delta 154 * @see #dispatchNestedScroll(int, int, int, int, int[], int) 155 */ dispatchNestedPreScroll(int dx, int dy, int @Nullable [] consumed, int @Nullable [] offsetInWindow, @NestedScrollType int type)156 boolean dispatchNestedPreScroll(int dx, int dy, int @Nullable [] consumed, 157 int @Nullable [] offsetInWindow, @NestedScrollType int type); 158 } 159