| /* |
| * Copyright (C) 2017 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package com.android.internal.widget; |
| |
| import android.annotation.Nullable; |
| import android.view.MotionEvent; |
| import android.view.VelocityTracker; |
| import android.view.View; |
| import android.view.ViewConfiguration; |
| import android.view.ViewParent; |
| |
| /** |
| * This interface should be implemented by {@link android.view.View View} subclasses that wish |
| * to support dispatching nested scrolling operations to a cooperating parent |
| * {@link android.view.ViewGroup ViewGroup}. |
| * |
| * <p>Classes implementing this interface should create a final instance of a |
| * {@link NestedScrollingChildHelper} as a field and delegate any View methods to the |
| * <code>NestedScrollingChildHelper</code> methods of the same signature.</p> |
| * |
| * <p>Views invoking nested scrolling functionality should always do so from the relevant |
| * {@link ViewCompat}, {@link ViewGroupCompat} or {@link ViewParentCompat} compatibility |
| * shim static methods. This ensures interoperability with nested scrolling views on Android |
| * 5.0 Lollipop and newer.</p> |
| */ |
| public interface NestedScrollingChild { |
| /** |
| * Enable or disable nested scrolling for this view. |
| * |
| * <p>If this property is set to true the view will be permitted to initiate nested |
| * scrolling operations with a compatible parent view in the current hierarchy. If this |
| * view does not implement nested scrolling this will have no effect. Disabling nested scrolling |
| * while a nested scroll is in progress has the effect of {@link #stopNestedScroll() stopping} |
| * the nested scroll.</p> |
| * |
| * @param enabled true to enable nested scrolling, false to disable |
| * |
| * @see #isNestedScrollingEnabled() |
| */ |
| void setNestedScrollingEnabled(boolean enabled); |
| |
| /** |
| * Returns true if nested scrolling is enabled for this view. |
| * |
| * <p>If nested scrolling is enabled and this View class implementation supports it, |
| * this view will act as a nested scrolling child view when applicable, forwarding data |
| * about the scroll operation in progress to a compatible and cooperating nested scrolling |
| * parent.</p> |
| * |
| * @return true if nested scrolling is enabled |
| * |
| * @see #setNestedScrollingEnabled(boolean) |
| */ |
| boolean isNestedScrollingEnabled(); |
| |
| /** |
| * Begin a nestable scroll operation along the given axes. |
| * |
| * <p>A view starting a nested scroll promises to abide by the following contract:</p> |
| * |
| * <p>The view will call startNestedScroll upon initiating a scroll operation. In the case |
| * of a touch scroll this corresponds to the initial {@link MotionEvent#ACTION_DOWN}. |
| * In the case of touch scrolling the nested scroll will be terminated automatically in |
| * the same manner as {@link ViewParent#requestDisallowInterceptTouchEvent(boolean)}. |
| * In the event of programmatic scrolling the caller must explicitly call |
| * {@link #stopNestedScroll()} to indicate the end of the nested scroll.</p> |
| * |
| * <p>If <code>startNestedScroll</code> returns true, a cooperative parent was found. |
| * If it returns false the caller may ignore the rest of this contract until the next scroll. |
| * Calling startNestedScroll while a nested scroll is already in progress will return true.</p> |
| * |
| * <p>At each incremental step of the scroll the caller should invoke |
| * {@link #dispatchNestedPreScroll(int, int, int[], int[]) dispatchNestedPreScroll} |
| * once it has calculated the requested scrolling delta. If it returns true the nested scrolling |
| * parent at least partially consumed the scroll and the caller should adjust the amount it |
| * scrolls by.</p> |
| * |
| * <p>After applying the remainder of the scroll delta the caller should invoke |
| * {@link #dispatchNestedScroll(int, int, int, int, int[]) dispatchNestedScroll}, passing |
| * both the delta consumed and the delta unconsumed. A nested scrolling parent may treat |
| * these values differently. See |
| * {@link NestedScrollingParent#onNestedScroll(View, int, int, int, int)}. |
| * </p> |
| * |
| * @param axes Flags consisting of a combination of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL} |
| * and/or {@link ViewCompat#SCROLL_AXIS_VERTICAL}. |
| * @return true if a cooperative parent was found and nested scrolling has been enabled for |
| * the current gesture. |
| * |
| * @see #stopNestedScroll() |
| * @see #dispatchNestedPreScroll(int, int, int[], int[]) |
| * @see #dispatchNestedScroll(int, int, int, int, int[]) |
| */ |
| boolean startNestedScroll(int axes); |
| |
| /** |
| * Stop a nested scroll in progress. |
| * |
| * <p>Calling this method when a nested scroll is not currently in progress is harmless.</p> |
| * |
| * @see #startNestedScroll(int) |
| */ |
| void stopNestedScroll(); |
| |
| /** |
| * Returns true if this view has a nested scrolling parent. |
| * |
| * <p>The presence of a nested scrolling parent indicates that this view has initiated |
| * a nested scroll and it was accepted by an ancestor view further up the view hierarchy.</p> |
| * |
| * @return whether this view has a nested scrolling parent |
| */ |
| boolean hasNestedScrollingParent(); |
| |
| /** |
| * Dispatch one step of a nested scroll in progress. |
| * |
| * <p>Implementations of views that support nested scrolling should call this to report |
| * info about a scroll in progress to the current nested scrolling parent. If a nested scroll |
| * is not currently in progress or nested scrolling is not |
| * {@link #isNestedScrollingEnabled() enabled} for this view this method does nothing.</p> |
| * |
| * <p>Compatible View implementations should also call |
| * {@link #dispatchNestedPreScroll(int, int, int[], int[]) dispatchNestedPreScroll} before |
| * consuming a component of the scroll event themselves.</p> |
| * |
| * @param dxConsumed Horizontal distance in pixels consumed by this view during this scroll step |
| * @param dyConsumed Vertical distance in pixels consumed by this view during this scroll step |
| * @param dxUnconsumed Horizontal scroll distance in pixels not consumed by this view |
| * @param dyUnconsumed Horizontal scroll distance in pixels not consumed by this view |
| * @param offsetInWindow Optional. If not null, on return this will contain the offset |
| * in local view coordinates of this view from before this operation |
| * to after it completes. View implementations may use this to adjust |
| * expected input coordinate tracking. |
| * @return true if the event was dispatched, false if it could not be dispatched. |
| * @see #dispatchNestedPreScroll(int, int, int[], int[]) |
| */ |
| boolean dispatchNestedScroll(int dxConsumed, int dyConsumed, |
| int dxUnconsumed, int dyUnconsumed, @Nullable int[] offsetInWindow); |
| |
| /** |
| * Dispatch one step of a nested scroll in progress before this view consumes any portion of it. |
| * |
| * <p>Nested pre-scroll events are to nested scroll events what touch intercept is to touch. |
| * <code>dispatchNestedPreScroll</code> offers an opportunity for the parent view in a nested |
| * scrolling operation to consume some or all of the scroll operation before the child view |
| * consumes it.</p> |
| * |
| * @param dx Horizontal scroll distance in pixels |
| * @param dy Vertical scroll distance in pixels |
| * @param consumed Output. If not null, consumed[0] will contain the consumed component of dx |
| * and consumed[1] the consumed dy. |
| * @param offsetInWindow Optional. If not null, on return this will contain the offset |
| * in local view coordinates of this view from before this operation |
| * to after it completes. View implementations may use this to adjust |
| * expected input coordinate tracking. |
| * @return true if the parent consumed some or all of the scroll delta |
| * @see #dispatchNestedScroll(int, int, int, int, int[]) |
| */ |
| boolean dispatchNestedPreScroll(int dx, int dy, @Nullable int[] consumed, |
| @Nullable int[] offsetInWindow); |
| |
| /** |
| * Dispatch a fling to a nested scrolling parent. |
| * |
| * <p>This method should be used to indicate that a nested scrolling child has detected |
| * suitable conditions for a fling. Generally this means that a touch scroll has ended with a |
| * {@link VelocityTracker velocity} in the direction of scrolling that meets or exceeds |
| * the {@link ViewConfiguration#getScaledMinimumFlingVelocity() minimum fling velocity} |
| * along a scrollable axis.</p> |
| * |
| * <p>If a nested scrolling child view would normally fling but it is at the edge of |
| * its own content, it can use this method to delegate the fling to its nested scrolling |
| * parent instead. The parent may optionally consume the fling or observe a child fling.</p> |
| * |
| * @param velocityX Horizontal fling velocity in pixels per second |
| * @param velocityY Vertical fling velocity in pixels per second |
| * @param consumed true if the child consumed the fling, false otherwise |
| * @return true if the nested scrolling parent consumed or otherwise reacted to the fling |
| */ |
| boolean dispatchNestedFling(float velocityX, float velocityY, boolean consumed); |
| |
| /** |
| * Dispatch a fling to a nested scrolling parent before it is processed by this view. |
| * |
| * <p>Nested pre-fling events are to nested fling events what touch intercept is to touch |
| * and what nested pre-scroll is to nested scroll. <code>dispatchNestedPreFling</code> |
| * offsets an opportunity for the parent view in a nested fling to fully consume the fling |
| * before the child view consumes it. If this method returns <code>true</code>, a nested |
| * parent view consumed the fling and this view should not scroll as a result.</p> |
| * |
| * <p>For a better user experience, only one view in a nested scrolling chain should consume |
| * the fling at a time. If a parent view consumed the fling this method will return false. |
| * Custom view implementations should account for this in two ways:</p> |
| * |
| * <ul> |
| * <li>If a custom view is paged and needs to settle to a fixed page-point, do not |
| * call <code>dispatchNestedPreFling</code>; consume the fling and settle to a valid |
| * position regardless.</li> |
| * <li>If a nested parent does consume the fling, this view should not scroll at all, |
| * even to settle back to a valid idle position.</li> |
| * </ul> |
| * |
| * <p>Views should also not offer fling velocities to nested parent views along an axis |
| * where scrolling is not currently supported; a {@link android.widget.ScrollView ScrollView} |
| * should not offer a horizontal fling velocity to its parents since scrolling along that |
| * axis is not permitted and carrying velocity along that motion does not make sense.</p> |
| * |
| * @param velocityX Horizontal fling velocity in pixels per second |
| * @param velocityY Vertical fling velocity in pixels per second |
| * @return true if a nested scrolling parent consumed the fling |
| */ |
| boolean dispatchNestedPreFling(float velocityX, float velocityY); |
| } |
