androidx.core.view.NestedScrollingChild
Subclasses:
NestedScrollingChild2, NestedScrollingChild3, NestedScrollView, SwipeRefreshLayout, WearableRecyclerView, VerticalGridView, BaseGridView, HorizontalGridView, RecyclerView
Gradle dependencies
compile group: 'androidx.core', name: 'core', version: '1.9.0-alpha04'
- groupId: androidx.core
- artifactId: core
- version: 1.9.0-alpha04
Artifact androidx.core:core:1.9.0-alpha04 it located at Google repository (https://maven.google.com/)
Androidx artifact mapping:
androidx.core:core com.android.support:support-compat
Androidx class mapping:
androidx.core.view.NestedScrollingChild android.support.v4.view.NestedScrollingChild
Overview
This interface should be implemented by View
subclasses that wish
to support dispatching nested scrolling operations to a cooperating parent
ViewGroup
.
Classes implementing this interface should create a final instance of a
NestedScrollingChildHelper as a field and delegate any View methods to the
NestedScrollingChildHelper
methods of the same signature.
Views invoking nested scrolling functionality should always do so from the relevant
ViewCompat, ViewGroupCompat or ViewParentCompat compatibility
shim static methods. This ensures interoperability with nested scrolling views on Android
5.0 Lollipop and newer.
Summary
Methods |
---|
public boolean | dispatchNestedFling(float velocityX, float velocityY, boolean consumed)
Dispatch a fling to a nested scrolling parent. |
public boolean | dispatchNestedPreFling(float velocityX, float velocityY)
Dispatch a fling to a nested scrolling parent before it is processed by this view. |
public boolean | dispatchNestedPreScroll(int dx, int dy, int[] consumed[], int[] offsetInWindow[])
Dispatch one step of a nested scroll in progress before this view consumes any portion of it. |
public boolean | dispatchNestedScroll(int dxConsumed, int dyConsumed, int dxUnconsumed, int dyUnconsumed, int[] offsetInWindow[])
Dispatch one step of a nested scroll in progress. |
public boolean | hasNestedScrollingParent()
Returns true if this view has a nested scrolling parent. |
public boolean | isNestedScrollingEnabled()
Returns true if nested scrolling is enabled for this view. |
public void | setNestedScrollingEnabled(boolean enabled)
Enable or disable nested scrolling for this view. |
public boolean | startNestedScroll(int axes)
Begin a nestable scroll operation along the given axes. |
public void | stopNestedScroll()
Stop a nested scroll in progress. |
Methods
public void
setNestedScrollingEnabled(boolean enabled)
Enable or disable nested scrolling for this view.
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 stopping
the nested scroll.
Parameters:
enabled: true to enable nested scrolling, false to disable
See also: NestedScrollingChild.isNestedScrollingEnabled()
public boolean
isNestedScrollingEnabled()
Returns true if nested scrolling is enabled for this view.
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.
Returns:
true if nested scrolling is enabled
See also: NestedScrollingChild.setNestedScrollingEnabled(boolean)
public boolean
startNestedScroll(int axes)
Begin a nestable scroll operation along the given axes.
A view starting a nested scroll promises to abide by the following contract:
The view will call startNestedScroll upon initiating a scroll operation. In the case
of a touch scroll this corresponds to the initial MotionEvent
.
In the case of touch scrolling the nested scroll will be terminated automatically in
the same manner as .
In the event of programmatic scrolling the caller must explicitly call
NestedScrollingChild.stopNestedScroll() to indicate the end of the nested scroll.
If startNestedScroll
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.
At each incremental step of the scroll the caller should invoke
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.
After applying the remainder of the scroll delta the caller should invoke
dispatchNestedScroll, passing
both the delta consumed and the delta unconsumed. A nested scrolling parent may treat
these values differently. See
NestedScrollingParent.onNestedScroll(View, int, int, int, int).
Parameters:
axes: Flags consisting of a combination of ViewCompat.SCROLL_AXIS_HORIZONTAL
and/or ViewCompat.SCROLL_AXIS_VERTICAL.
Returns:
true if a cooperative parent was found and nested scrolling has been enabled for
the current gesture.
See also: NestedScrollingChild.stopNestedScroll(), NestedScrollingChild.dispatchNestedPreScroll(int, int, int[], int[]), NestedScrollingChild.dispatchNestedScroll(int, int, int, int, int[])
public void
stopNestedScroll()
Stop a nested scroll in progress.
Calling this method when a nested scroll is not currently in progress is harmless.
See also: NestedScrollingChild.startNestedScroll(int)
public boolean
hasNestedScrollingParent()
Returns true if this view has a nested scrolling parent.
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.
Returns:
whether this view has a nested scrolling parent
public boolean
dispatchNestedScroll(int dxConsumed, int dyConsumed, int dxUnconsumed, int dyUnconsumed, int[] offsetInWindow[])
Dispatch one step of a nested scroll in progress.
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
enabled for this view this method does nothing.
Compatible View implementations should also call
dispatchNestedPreScroll before
consuming a component of the scroll event themselves.
Parameters:
dxConsumed: Horizontal distance in pixels consumed by this view during this scroll step
dyConsumed: Vertical distance in pixels consumed by this view during this scroll step
dxUnconsumed: Horizontal scroll distance in pixels not consumed by this view
dyUnconsumed: Horizontal scroll distance in pixels not consumed by this view
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.
Returns:
true if the event was dispatched, false if it could not be dispatched.
See also: NestedScrollingChild.dispatchNestedPreScroll(int, int, int[], int[])
public boolean
dispatchNestedPreScroll(int dx, int dy, int[] consumed[], int[] offsetInWindow[])
Dispatch one step of a nested scroll in progress before this view consumes any portion of it.
Nested pre-scroll events are to nested scroll events what touch intercept is to touch.
dispatchNestedPreScroll
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.
Parameters:
dx: Horizontal scroll distance in pixels
dy: Vertical scroll distance in pixels
consumed: Output. If not null, consumed[0] will contain the consumed component of dx
and consumed[1] the consumed dy.
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.
Returns:
true if the parent consumed some or all of the scroll delta
See also: NestedScrollingChild.dispatchNestedScroll(int, int, int, int, int[])
public boolean
dispatchNestedFling(float velocityX, float velocityY, boolean consumed)
Dispatch a fling to a nested scrolling parent.
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
in the direction of scrolling that meets or exceeds
the
along a scrollable axis.
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.
Parameters:
velocityX: Horizontal fling velocity in pixels per second
velocityY: Vertical fling velocity in pixels per second
consumed: true if the child consumed the fling, false otherwise
Returns:
true if the nested scrolling parent consumed or otherwise reacted to the fling
public boolean
dispatchNestedPreFling(float velocityX, float velocityY)
Dispatch a fling to a nested scrolling parent before it is processed by this view.
Nested pre-fling events are to nested fling events what touch intercept is to touch
and what nested pre-scroll is to nested scroll. dispatchNestedPreFling
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 true
, a nested
parent view consumed the fling and this view should not scroll as a result.
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:
- If a custom view is paged and needs to settle to a fixed page-point, do not
call
dispatchNestedPreFling
; consume the fling and settle to a valid
position regardless.
- If a nested parent does consume the fling, this view should not scroll at all,
even to settle back to a valid idle position.
Views should also not offer fling velocities to nested parent views along an axis
where scrolling is not currently supported; a
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.
Parameters:
velocityX: Horizontal fling velocity in pixels per second
velocityY: Vertical fling velocity in pixels per second
Returns:
true if a nested scrolling parent consumed the fling
Source
/*
* Copyright 2018 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 androidx.core.view;
import android.view.MotionEvent;
import android.view.VelocityTracker;
import android.view.View;
import android.view.ViewConfiguration;
import android.view.ViewParent;
import androidx.annotation.Nullable;
import androidx.core.view.ViewCompat.ScrollAxis;
/**
* 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(@ScrollAxis 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);
}