v4/java/android/support/v4/view/NestedScrollingParent.java - platform/frameworks/support - Git at Google

 /*
  * Copyright (C) 2015 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 android.support.v4.view;

 import android.view.MotionEvent;
 import android.view.VelocityTracker;
 import android.view.View;
 import android.view.ViewConfiguration;

 /**
  * This interface should be implemented by {@link android.view.ViewGroup ViewGroup} subclasses
  * that wish to support scrolling operations delegated by a nested child view.
  *
  * <p>Classes implementing this interface should create a final instance of a
  * {@link NestedScrollingParentHelper} as a field and delegate any View or ViewGroup methods
  * to the <code>NestedScrollingParentHelper</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 NestedScrollingParent {
     /**
      * React to a descendant view initiating a nestable scroll operation, claiming the
      * nested scroll operation if appropriate.
      *
      * <p>This method will be called in response to a descendant view invoking
      * {@link ViewCompat#startNestedScroll(View, int)}. Each parent up the view hierarchy will be
      * given an opportunity to respond and claim the nested scrolling operation by returning
      * <code>true</code>.</p>
      *
      * <p>This method may be overridden by ViewParent implementations to indicate when the view
      * is willing to support a nested scrolling operation that is about to begin. If it returns
      * true, this ViewParent will become the target view's nested scrolling parent for the duration
      * of the scroll operation in progress. When the nested scroll is finished this ViewParent
      * will receive a call to {@link #onStopNestedScroll(View)}.
      * </p>
      *
      * @param child Direct child of this ViewParent containing target
      * @param target View that initiated the nested scroll
      * @param nestedScrollAxes Flags consisting of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL},
      *                         {@link ViewCompat#SCROLL_AXIS_VERTICAL} or both
      * @return true if this ViewParent accepts the nested scroll operation
      */
     public boolean onStartNestedScroll(View child, View target, int nestedScrollAxes);

     /**
      * React to the successful claiming of a nested scroll operation.
      *
      * <p>This method will be called after
      * {@link #onStartNestedScroll(View, View, int) onStartNestedScroll} returns true. It offers
      * an opportunity for the view and its superclasses to perform initial configuration
      * for the nested scroll. Implementations of this method should always call their superclass's
      * implementation of this method if one is present.</p>
      *
      * @param child Direct child of this ViewParent containing target
      * @param target View that initiated the nested scroll
      * @param nestedScrollAxes Flags consisting of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL},
      *                         {@link ViewCompat#SCROLL_AXIS_VERTICAL} or both
      * @see #onStartNestedScroll(View, View, int)
      * @see #onStopNestedScroll(View)
      */
     public void onNestedScrollAccepted(View child, View target, int nestedScrollAxes);

     /**
      * React to a nested scroll operation ending.
      *
      * <p>Perform cleanup after a nested scrolling operation.
      * This method will be called when a nested scroll stops, for example when a nested touch
      * scroll ends with a {@link MotionEvent#ACTION_UP} or {@link MotionEvent#ACTION_CANCEL} event.
      * Implementations of this method should always call their superclass's implementation of this
      * method if one is present.</p>
      *
      * @param target View that initiated the nested scroll
      */
     public void onStopNestedScroll(View target);

     /**
      * React to a nested scroll in progress.
      *
      * <p>This method will be called when the ViewParent's current nested scrolling child view
      * dispatches a nested scroll event. To receive calls to this method the ViewParent must have
      * previously returned <code>true</code> for a call to
      * {@link #onStartNestedScroll(View, View, int)}.</p>
      *
      * <p>Both the consumed and unconsumed portions of the scroll distance are reported to the
      * ViewParent. An implementation may choose to use the consumed portion to match or chase scroll
      * position of multiple child elements, for example. The unconsumed portion may be used to
      * allow continuous dragging of multiple scrolling or draggable elements, such as scrolling
      * a list within a vertical drawer where the drawer begins dragging once the edge of inner
      * scrolling content is reached.</p>
      *
      * @param target The descendent view controlling the nested scroll
      * @param dxConsumed Horizontal scroll distance in pixels already consumed by target
      * @param dyConsumed Vertical scroll distance in pixels already consumed by target
      * @param dxUnconsumed Horizontal scroll distance in pixels not consumed by target
      * @param dyUnconsumed Vertical scroll distance in pixels not consumed by target
      */
     public void onNestedScroll(View target, int dxConsumed, int dyConsumed,
             int dxUnconsumed, int dyUnconsumed);

     /**
      * React to a nested scroll in progress before the target view consumes a portion of the scroll.
      *
      * <p>When working with nested scrolling often the parent view may want an opportunity
      * to consume the scroll before the nested scrolling child does. An example of this is a
      * drawer that contains a scrollable list. The user will want to be able to scroll the list
      * fully into view before the list itself begins scrolling.</p>
      *
      * <p><code>onNestedPreScroll</code> is called when a nested scrolling child invokes
      * {@link View#dispatchNestedPreScroll(int, int, int[], int[])}. The implementation should
      * report how any pixels of the scroll reported by dx, dy were consumed in the
      * <code>consumed</code> array. Index 0 corresponds to dx and index 1 corresponds to dy.
      * This parameter will never be null. Initial values for consumed[0] and consumed[1]
      * will always be 0.</p>
      *
      * @param target View that initiated the nested scroll
      * @param dx Horizontal scroll distance in pixels
      * @param dy Vertical scroll distance in pixels
      * @param consumed Output. The horizontal and vertical scroll distance consumed by this parent
      */
     public void onNestedPreScroll(View target, int dx, int dy, int[] consumed);

     /**
      * Request a fling from a nested scroll.
      *
      * <p>This method signifies 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 target View that initiated the nested scroll
      * @param velocityX Horizontal velocity in pixels per second
      * @param velocityY Vertical velocity in pixels per second
      * @param consumed true if the child consumed the fling, false otherwise
      * @return true if this parent consumed or otherwise reacted to the fling
      */
     public boolean onNestedFling(View target, float velocityX, float velocityY, boolean consumed);

     /**
      * React to a nested fling before the target view consumes it.
      *
      * <p>This method siginfies that a nested scrolling child has detected a fling with the given
      * velocity along each axis. 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 parent is consuming motion as part of a
      * {@link #onNestedPreScroll(View, int, int, int[]) pre-scroll}, it may be appropriate for
      * it to also consume the pre-fling to complete that same motion. By returning
      * <code>true</code> from this method, the parent indicates that the child should not
      * fling its own internal content as well.</p>
      *
      * @param target View that initiated the nested scroll
      * @param velocityX Horizontal velocity in pixels per second
      * @param velocityY Vertical velocity in pixels per second
      * @return true if this parent consumed the fling ahead of the target view
      */
     public boolean onNestedPreFling(View target, float velocityX, float velocityY);

     /**
      * Return the current axes of nested scrolling for this NestedScrollingParent.
      *
      * <p>A NestedScrollingParent returning something other than {@link ViewCompat#SCROLL_AXIS_NONE}
      * is currently acting as a nested scrolling parent for one or more descendant views in
      * the hierarchy.</p>
      *
      * @return Flags indicating the current axes of nested scrolling
      * @see ViewCompat#SCROLL_AXIS_HORIZONTAL
      * @see ViewCompat#SCROLL_AXIS_VERTICAL
      * @see ViewCompat#SCROLL_AXIS_NONE
      */
     public int getNestedScrollAxes();
 }
	/*
	* Copyright (C) 2015 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 android.support.v4.view;

	import android.view.MotionEvent;
	import android.view.VelocityTracker;
	import android.view.View;
	import android.view.ViewConfiguration;

	/**
	* This interface should be implemented by {@link android.view.ViewGroup ViewGroup} subclasses
	* that wish to support scrolling operations delegated by a nested child view.
	*
	* <p>Classes implementing this interface should create a final instance of a
	* {@link NestedScrollingParentHelper} as a field and delegate any View or ViewGroup methods
	* to the <code>NestedScrollingParentHelper</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 NestedScrollingParent {
	/**
	* React to a descendant view initiating a nestable scroll operation, claiming the
	* nested scroll operation if appropriate.
	*
	* <p>This method will be called in response to a descendant view invoking
	* {@link ViewCompat#startNestedScroll(View, int)}. Each parent up the view hierarchy will be
	* given an opportunity to respond and claim the nested scrolling operation by returning
	* <code>true</code>.</p>
	*
	* <p>This method may be overridden by ViewParent implementations to indicate when the view
	* is willing to support a nested scrolling operation that is about to begin. If it returns
	* true, this ViewParent will become the target view's nested scrolling parent for the duration
	* of the scroll operation in progress. When the nested scroll is finished this ViewParent
	* will receive a call to {@link #onStopNestedScroll(View)}.
	* </p>
	*
	* @param child Direct child of this ViewParent containing target
	* @param target View that initiated the nested scroll
	* @param nestedScrollAxes Flags consisting of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL},
	* {@link ViewCompat#SCROLL_AXIS_VERTICAL} or both
	* @return true if this ViewParent accepts the nested scroll operation
	*/
	public boolean onStartNestedScroll(View child, View target, int nestedScrollAxes);

	/**
	* React to the successful claiming of a nested scroll operation.
	*
	* <p>This method will be called after
	* {@link #onStartNestedScroll(View, View, int) onStartNestedScroll} returns true. It offers
	* an opportunity for the view and its superclasses to perform initial configuration
	* for the nested scroll. Implementations of this method should always call their superclass's
	* implementation of this method if one is present.</p>
	*
	* @param child Direct child of this ViewParent containing target
	* @param target View that initiated the nested scroll
	* @param nestedScrollAxes Flags consisting of {@link ViewCompat#SCROLL_AXIS_HORIZONTAL},
	* {@link ViewCompat#SCROLL_AXIS_VERTICAL} or both
	* @see #onStartNestedScroll(View, View, int)
	* @see #onStopNestedScroll(View)
	*/
	public void onNestedScrollAccepted(View child, View target, int nestedScrollAxes);

	/**
	* React to a nested scroll operation ending.
	*
	* <p>Perform cleanup after a nested scrolling operation.
	* This method will be called when a nested scroll stops, for example when a nested touch
	* scroll ends with a {@link MotionEvent#ACTION_UP} or {@link MotionEvent#ACTION_CANCEL} event.
	* Implementations of this method should always call their superclass's implementation of this
	* method if one is present.</p>
	*
	* @param target View that initiated the nested scroll
	*/
	public void onStopNestedScroll(View target);

	/**
	* React to a nested scroll in progress.
	*
	* <p>This method will be called when the ViewParent's current nested scrolling child view
	* dispatches a nested scroll event. To receive calls to this method the ViewParent must have
	* previously returned <code>true</code> for a call to
	* {@link #onStartNestedScroll(View, View, int)}.</p>
	*
	* <p>Both the consumed and unconsumed portions of the scroll distance are reported to the
	* ViewParent. An implementation may choose to use the consumed portion to match or chase scroll
	* position of multiple child elements, for example. The unconsumed portion may be used to
	* allow continuous dragging of multiple scrolling or draggable elements, such as scrolling
	* a list within a vertical drawer where the drawer begins dragging once the edge of inner
	* scrolling content is reached.</p>
	*
	* @param target The descendent view controlling the nested scroll
	* @param dxConsumed Horizontal scroll distance in pixels already consumed by target
	* @param dyConsumed Vertical scroll distance in pixels already consumed by target
	* @param dxUnconsumed Horizontal scroll distance in pixels not consumed by target
	* @param dyUnconsumed Vertical scroll distance in pixels not consumed by target
	*/
	public void onNestedScroll(View target, int dxConsumed, int dyConsumed,
	int dxUnconsumed, int dyUnconsumed);

	/**
	* React to a nested scroll in progress before the target view consumes a portion of the scroll.
	*
	* <p>When working with nested scrolling often the parent view may want an opportunity
	* to consume the scroll before the nested scrolling child does. An example of this is a
	* drawer that contains a scrollable list. The user will want to be able to scroll the list
	* fully into view before the list itself begins scrolling.</p>
	*
	* <p><code>onNestedPreScroll</code> is called when a nested scrolling child invokes
	* {@link View#dispatchNestedPreScroll(int, int, int[], int[])}. The implementation should
	* report how any pixels of the scroll reported by dx, dy were consumed in the
	* <code>consumed</code> array. Index 0 corresponds to dx and index 1 corresponds to dy.
	* This parameter will never be null. Initial values for consumed[0] and consumed[1]
	* will always be 0.</p>
	*
	* @param target View that initiated the nested scroll
	* @param dx Horizontal scroll distance in pixels
	* @param dy Vertical scroll distance in pixels
	* @param consumed Output. The horizontal and vertical scroll distance consumed by this parent
	*/
	public void onNestedPreScroll(View target, int dx, int dy, int[] consumed);

	/**
	* Request a fling from a nested scroll.
	*
	* <p>This method signifies 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 target View that initiated the nested scroll
	* @param velocityX Horizontal velocity in pixels per second
	* @param velocityY Vertical velocity in pixels per second
	* @param consumed true if the child consumed the fling, false otherwise
	* @return true if this parent consumed or otherwise reacted to the fling
	*/
	public boolean onNestedFling(View target, float velocityX, float velocityY, boolean consumed);

	/**
	* React to a nested fling before the target view consumes it.
	*
	* <p>This method siginfies that a nested scrolling child has detected a fling with the given
	* velocity along each axis. 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 parent is consuming motion as part of a
	* {@link #onNestedPreScroll(View, int, int, int[]) pre-scroll}, it may be appropriate for
	* it to also consume the pre-fling to complete that same motion. By returning
	* <code>true</code> from this method, the parent indicates that the child should not
	* fling its own internal content as well.</p>
	*
	* @param target View that initiated the nested scroll
	* @param velocityX Horizontal velocity in pixels per second
	* @param velocityY Vertical velocity in pixels per second
	* @return true if this parent consumed the fling ahead of the target view
	*/
	public boolean onNestedPreFling(View target, float velocityX, float velocityY);

	/**
	* Return the current axes of nested scrolling for this NestedScrollingParent.
	*
	* <p>A NestedScrollingParent returning something other than {@link ViewCompat#SCROLL_AXIS_NONE}
	* is currently acting as a nested scrolling parent for one or more descendant views in
	* the hierarchy.</p>
	*
	* @return Flags indicating the current axes of nested scrolling
	* @see ViewCompat#SCROLL_AXIS_HORIZONTAL
	* @see ViewCompat#SCROLL_AXIS_VERTICAL
	* @see ViewCompat#SCROLL_AXIS_NONE
	*/
	public int getNestedScrollAxes();
	}