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 23 import androidx.core.view.ViewCompat.NestedScrollType; 24 import androidx.core.view.ViewCompat.ScrollAxis; 25 26 import org.jspecify.annotations.NonNull; 27 28 /** 29 * This interface should be implemented by {@link android.view.ViewGroup ViewGroup} subclasses 30 * that wish to support scrolling operations delegated by a nested child view. 31 * 32 * <p>Classes implementing this interface should create a final instance of a 33 * {@link NestedScrollingParentHelper} as a field and delegate any View or ViewGroup methods 34 * to the <code>NestedScrollingParentHelper</code> methods of the same signature.</p> 35 * 36 * <p>Views invoking nested scrolling functionality should always do so from the relevant 37 * {@link ViewCompat}, {@link ViewGroupCompat} or {@link ViewParentCompat} compatibility 38 * shim static methods. This ensures interoperability with nested scrolling views on all versions 39 * of Android.</p> 40 */ 41 public interface NestedScrollingParent2 extends NestedScrollingParent { 42 /** 43 * React to a descendant view initiating a nestable scroll operation, claiming the 44 * nested scroll operation if appropriate. 45 * 46 * <p>This method will be called in response to a descendant view invoking 47 * {@link ViewCompat#startNestedScroll(View, int)}. Each parent up the view hierarchy will be 48 * given an opportunity to respond and claim the nested scrolling operation by returning 49 * <code>true</code>.</p> 50 * 51 * <p>This method may be overridden by ViewParent implementations to indicate when the view 52 * is willing to support a nested scrolling operation that is about to begin. If it returns 53 * true, this ViewParent will become the target view's nested scrolling parent for the duration 54 * of the scroll operation in progress. When the nested scroll is finished this ViewParent 55 * will receive a call to {@link #onStopNestedScroll(View, int)}. 56 * </p> 57 * 58 * @param child Direct child of this ViewParent containing target 59 * @param target View that initiated the nested scroll 60 * @param axes Flags consisting of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL}, 61 * {@link ViewCompat#SCROLL_AXIS_VERTICAL} or both 62 * @param type the type of input which cause this scroll event 63 * @return true if this ViewParent accepts the nested scroll operation 64 */ onStartNestedScroll(@onNull View child, @NonNull View target, @ScrollAxis int axes, @NestedScrollType int type)65 boolean onStartNestedScroll(@NonNull View child, @NonNull View target, @ScrollAxis int axes, 66 @NestedScrollType int type); 67 68 /** 69 * React to the successful claiming of a nested scroll operation. 70 * 71 * <p>This method will be called after 72 * {@link #onStartNestedScroll(View, View, int, int) onStartNestedScroll} returns true. It 73 * offers an opportunity for the view and its superclasses to perform initial configuration 74 * for the nested scroll. Implementations of this method should always call their superclass's 75 * implementation of this method if one is present.</p> 76 * 77 * @param child Direct child of this ViewParent containing target 78 * @param target View that initiated the nested scroll 79 * @param axes Flags consisting of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL}, 80 * {@link ViewCompat#SCROLL_AXIS_VERTICAL} or both 81 * @param type the type of input which cause this scroll event 82 * @see #onStartNestedScroll(View, View, int, int) 83 * @see #onStopNestedScroll(View, int) 84 */ onNestedScrollAccepted(@onNull View child, @NonNull View target, @ScrollAxis int axes, @NestedScrollType int type)85 void onNestedScrollAccepted(@NonNull View child, @NonNull View target, @ScrollAxis int axes, 86 @NestedScrollType int type); 87 88 /** 89 * React to a nested scroll operation ending. 90 * 91 * <p>Perform cleanup after a nested scrolling operation. 92 * This method will be called when a nested scroll stops, for example when a nested touch 93 * scroll ends with a {@link MotionEvent#ACTION_UP} or {@link MotionEvent#ACTION_CANCEL} event. 94 * Implementations of this method should always call their superclass's implementation of this 95 * method if one is present.</p> 96 * 97 * @param target View that initiated the nested scroll 98 * @param type the type of input which cause this scroll event 99 */ onStopNestedScroll(@onNull View target, @NestedScrollType int type)100 void onStopNestedScroll(@NonNull View target, @NestedScrollType int type); 101 102 /** 103 * React to a nested scroll in progress. 104 * 105 * <p>This method will be called when the ViewParent's current nested scrolling child view 106 * dispatches a nested scroll event. To receive calls to this method the ViewParent must have 107 * previously returned <code>true</code> for a call to 108 * {@link #onStartNestedScroll(View, View, int, int)}.</p> 109 * 110 * <p>Both the consumed and unconsumed portions of the scroll distance are reported to the 111 * ViewParent. An implementation may choose to use the consumed portion to match or chase scroll 112 * position of multiple child elements, for example. The unconsumed portion may be used to 113 * allow continuous dragging of multiple scrolling or draggable elements, such as scrolling 114 * a list within a vertical drawer where the drawer begins dragging once the edge of inner 115 * scrolling content is reached.</p> 116 * 117 * @param target The descendent view controlling the nested scroll 118 * @param dxConsumed Horizontal scroll distance in pixels already consumed by target 119 * @param dyConsumed Vertical scroll distance in pixels already consumed by target 120 * @param dxUnconsumed Horizontal scroll distance in pixels not consumed by target 121 * @param dyUnconsumed Vertical scroll distance in pixels not consumed by target 122 * @param type the type of input which cause this scroll event 123 */ onNestedScroll(@onNull View target, int dxConsumed, int dyConsumed, int dxUnconsumed, int dyUnconsumed, @NestedScrollType int type)124 void onNestedScroll(@NonNull View target, int dxConsumed, int dyConsumed, 125 int dxUnconsumed, int dyUnconsumed, @NestedScrollType int type); 126 127 /** 128 * React to a nested scroll in progress before the target view consumes a portion of the scroll. 129 * 130 * <p>When working with nested scrolling often the parent view may want an opportunity 131 * to consume the scroll before the nested scrolling child does. An example of this is a 132 * drawer that contains a scrollable list. The user will want to be able to scroll the list 133 * fully into view before the list itself begins scrolling.</p> 134 * 135 * <p><code>onNestedPreScroll</code> is called when a nested scrolling child invokes 136 * {@link View#dispatchNestedPreScroll(int, int, int[], int[])}. The implementation should 137 * report how any pixels of the scroll reported by dx, dy were consumed in the 138 * <code>consumed</code> array. Index 0 corresponds to dx and index 1 corresponds to dy. 139 * This parameter will never be null. Initial values for consumed[0] and consumed[1] 140 * will always be 0.</p> 141 * 142 * @param target View that initiated the nested scroll 143 * @param dx Horizontal scroll distance in pixels 144 * @param dy Vertical scroll distance in pixels 145 * @param consumed Output. The horizontal and vertical scroll distance consumed by this parent 146 * @param type the type of input which cause this scroll event 147 */ onNestedPreScroll(@onNull View target, int dx, int dy, int @NonNull [] consumed, @NestedScrollType int type)148 void onNestedPreScroll(@NonNull View target, int dx, int dy, int @NonNull [] consumed, 149 @NestedScrollType int type); 150 151 } 152