android-35/android/widget/DifferentialMotionFlingHelper.java - platform/prebuilts/fullsdk/sources - Git at Google

 /*
  * Copyright 2023 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.widget;

 import android.annotation.Nullable;
 import android.content.Context;
 import android.view.MotionEvent;
 import android.view.VelocityTracker;
 import android.view.ViewConfiguration;
 import android.widget.flags.FeatureFlags;
 import android.widget.flags.FeatureFlagsImpl;

 import com.android.internal.annotations.VisibleForTesting;

 /**
  * Helper for controlling differential motion flings.
  *
  * <p><b>Differential motion</b> here refers to motions that report change in position instead of
  * absolution position. For instance, differential data points of 2, -1, 5 represent: there was
  * a movement by "2" units, then by "-1" units, then by "5" units. Examples of motions reported
  * differentially include motions from {@link MotionEvent#AXIS_SCROLL}.
  *
  * <p>The client should call {@link #onMotionEvent} when a differential motion event happens on
  * the target View (that is, the View on which we want to fling), and this class processes the event
  * to orchestrate fling.
  *
  * <p>Note that this helper class currently works to control fling only in one direction at a time.
  * As such, it works independently of horizontal/vertical orientations. It requests its client to
  * start/stop fling, and it's up to the client to choose the fling direction based on its specific
  * internal configurations and/or preferences.
  *
  * @hide
  */
 public class DifferentialMotionFlingHelper {
     private final Context mContext;
     private final DifferentialMotionFlingTarget mTarget;

     private final FlingVelocityThresholdCalculator mVelocityThresholdCalculator;
     private final DifferentialVelocityProvider mVelocityProvider;

     private final FeatureFlags mWidgetFeatureFlags;

     @Nullable private VelocityTracker mVelocityTracker;

     private float mLastFlingVelocity;

     private int mLastProcessedAxis = -1;
     private int mLastProcessedSource = -1;
     private int mLastProcessedDeviceId = -1;

     // Initialize min and max to +infinity and 0, to effectively disable fling at start.
     private final int[] mFlingVelocityThresholds = new int[] {Integer.MAX_VALUE, 0};

     /** Interface to calculate the fling velocity thresholds. Helps fake during testing. */
     @VisibleForTesting
     public interface FlingVelocityThresholdCalculator {
         /**
          * Calculates the fling velocity thresholds (in pixels/second) and puts them in a provided
          * store.
          *
          * @param context the context associated with the View that may be flung.
          * @param store an at-least size-2 int array. The method will overwrite positions 0 and 1
          *             with the min and max fling velocities, respectively.
          * @param event the event that may trigger fling.
          * @param axis the axis being processed for the event.
          */
         void calculateFlingVelocityThresholds(
                 Context context, int[] store, MotionEvent event, int axis);
     }

     /**
      * Interface to provide velocity. Helps fake during testing.
      *
      * <p>The client should call {@link #getCurrentVelocity(VelocityTracker, MotionEvent, int)} each
      * time it wants to consider a {@link MotionEvent} towards the latest velocity, and the
      * interface handles providing velocity that accounts for the latest and all past events.
      */
     @VisibleForTesting
     public interface DifferentialVelocityProvider {
         /**
          * Returns the latest velocity.
          *
          * @param vt the {@link VelocityTracker} to be used to compute velocity.
          * @param event the latest event to be considered in the velocity computations.
          * @param axis the axis being processed for the event.
          * @return the calculated, latest velocity.
          */
         float getCurrentVelocity(VelocityTracker vt, MotionEvent event, int axis);
     }

     /**
      * Represents an entity that may be flung by a differential motion or an entity that initiates
      * fling on a target View.
      */
     public interface DifferentialMotionFlingTarget {
         /**
          * Start flinging on the target View by a given velocity.
          *
          * @param velocity the fling velocity, in pixels/second.
          * @return {@code true} if fling was successfully initiated, {@code false} otherwise.
          */
         boolean startDifferentialMotionFling(float velocity);

         /** Stop any ongoing fling on the target View that is caused by a differential motion. */
         void stopDifferentialMotionFling();

         /**
          * Returns the scaled scroll factor to be used for differential motions. This is the
          * value that the raw {@link MotionEvent} values should be multiplied with to get pixels.
          *
          * <p>This usually is one of the values provided by {@link ViewConfiguration}. It is
          * up to the client to choose and provide any value as per its internal configuration.
          *
          * @see ViewConfiguration#getScaledHorizontalScrollFactor()
          * @see ViewConfiguration#getScaledVerticalScrollFactor()
          */
         float getScaledScrollFactor();
     }

     /** Constructs an instance for a given {@link DifferentialMotionFlingTarget}. */
     public DifferentialMotionFlingHelper(
             Context context,
             DifferentialMotionFlingTarget target) {
         this(context,
                 target,
                 DifferentialMotionFlingHelper::calculateFlingVelocityThresholds,
                 DifferentialMotionFlingHelper::getCurrentVelocity,
                 /* widgetFeatureFlags= */ new FeatureFlagsImpl());
     }

     @VisibleForTesting
     public DifferentialMotionFlingHelper(
             Context context,
             DifferentialMotionFlingTarget target,
             FlingVelocityThresholdCalculator velocityThresholdCalculator,
             DifferentialVelocityProvider velocityProvider,
             FeatureFlags widgetFeatureFlags) {
         mContext = context;
         mTarget = target;
         mVelocityThresholdCalculator = velocityThresholdCalculator;
         mVelocityProvider = velocityProvider;
         mWidgetFeatureFlags = widgetFeatureFlags;
     }

     /**
      * Called to report when a differential motion happens on the View that's the target for fling.
      *
      * @param event the {@link MotionEvent} being reported.
      * @param axis the axis being processed by the target View.
      */
     public void onMotionEvent(MotionEvent event, int axis) {
         if (!mWidgetFeatureFlags.enablePlatformWidgetDifferentialMotionFling()) {
             return;
         }
         boolean flingParamsChanged = calculateFlingVelocityThresholds(event, axis);
         if (mFlingVelocityThresholds[0] == Integer.MAX_VALUE) {
             // Integer.MAX_VALUE means that the device does not support fling for the current
             // configuration. Do not proceed any further.
             recycleVelocityTracker();
             return;
         }

         float scaledVelocity =
                 getCurrentVelocity(event, axis) * mTarget.getScaledScrollFactor();

         float velocityDirection = Math.signum(scaledVelocity);
         // Stop ongoing fling if there has been state changes affecting fling, or if the current
         // velocity (if non-zero) is opposite of the velocity that last caused fling.
         if (flingParamsChanged
                 || (velocityDirection != Math.signum(mLastFlingVelocity)
                     && velocityDirection != 0)) {
             mTarget.stopDifferentialMotionFling();
         }

         if (Math.abs(scaledVelocity) < mFlingVelocityThresholds[0]) {
             return;
         }

         // Clamp the scaled velocity between [-max, max].
         // e.g. if max=100, and vel=200
         // vel = max(-100, min(200, 100)) = max(-100, 100) = 100
         // e.g. if max=100, and vel=-200
         // vel = max(-100, min(-200, 100)) = max(-100, -200) = -100
         scaledVelocity =
                 Math.max(
                         -mFlingVelocityThresholds[1],
                         Math.min(scaledVelocity, mFlingVelocityThresholds[1]));

         boolean flung = mTarget.startDifferentialMotionFling(scaledVelocity);
         mLastFlingVelocity = flung ? scaledVelocity : 0;
     }

     /**
      * Calculates fling velocity thresholds based on the provided event and axis, and returns {@code
      * true} if there has been a change of any params that may affect fling velocity thresholds.
      */
     private boolean calculateFlingVelocityThresholds(MotionEvent event, int axis) {
         int source = event.getSource();
         int deviceId = event.getDeviceId();
         if (mLastProcessedSource != source
                 || mLastProcessedDeviceId != deviceId
                 || mLastProcessedAxis != axis) {
             mVelocityThresholdCalculator.calculateFlingVelocityThresholds(
                     mContext, mFlingVelocityThresholds, event, axis);
             // Save data about this processing so that we don't have to re-process fling thresholds
             // for similar parameters.
             mLastProcessedSource = source;
             mLastProcessedDeviceId = deviceId;
             mLastProcessedAxis = axis;
             return true;
         }
         return false;
     }

     private static void calculateFlingVelocityThresholds(
             Context context, int[] buffer, MotionEvent event, int axis) {
         int source = event.getSource();
         int deviceId = event.getDeviceId();

         ViewConfiguration vc = ViewConfiguration.get(context);
         buffer[0] = vc.getScaledMinimumFlingVelocity(deviceId, axis, source);
         buffer[1] = vc.getScaledMaximumFlingVelocity(deviceId, axis, source);
     }

     private float getCurrentVelocity(MotionEvent event, int axis) {
         if (mVelocityTracker == null) {
             mVelocityTracker = VelocityTracker.obtain();
         }

         return mVelocityProvider.getCurrentVelocity(mVelocityTracker, event, axis);
     }

     private void recycleVelocityTracker() {
         if (mVelocityTracker != null) {
             mVelocityTracker.recycle();
             mVelocityTracker = null;
         }
     }

     private static float getCurrentVelocity(VelocityTracker vt, MotionEvent event, int axis) {
         vt.addMovement(event);
         vt.computeCurrentVelocity(1000);
         return vt.getAxisVelocity(axis);
     }
 }
	/*
	* Copyright 2023 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.widget;

	import android.annotation.Nullable;
	import android.content.Context;
	import android.view.MotionEvent;
	import android.view.VelocityTracker;
	import android.view.ViewConfiguration;
	import android.widget.flags.FeatureFlags;
	import android.widget.flags.FeatureFlagsImpl;

	import com.android.internal.annotations.VisibleForTesting;

	/**
	* Helper for controlling differential motion flings.
	*
	* <p><b>Differential motion</b> here refers to motions that report change in position instead of
	* absolution position. For instance, differential data points of 2, -1, 5 represent: there was
	* a movement by "2" units, then by "-1" units, then by "5" units. Examples of motions reported
	* differentially include motions from {@link MotionEvent#AXIS_SCROLL}.
	*
	* <p>The client should call {@link #onMotionEvent} when a differential motion event happens on
	* the target View (that is, the View on which we want to fling), and this class processes the event
	* to orchestrate fling.
	*
	* <p>Note that this helper class currently works to control fling only in one direction at a time.
	* As such, it works independently of horizontal/vertical orientations. It requests its client to
	* start/stop fling, and it's up to the client to choose the fling direction based on its specific
	* internal configurations and/or preferences.
	*
	* @hide
	*/
	public class DifferentialMotionFlingHelper {
	private final Context mContext;
	private final DifferentialMotionFlingTarget mTarget;

	private final FlingVelocityThresholdCalculator mVelocityThresholdCalculator;
	private final DifferentialVelocityProvider mVelocityProvider;

	private final FeatureFlags mWidgetFeatureFlags;

	@Nullable private VelocityTracker mVelocityTracker;

	private float mLastFlingVelocity;

	private int mLastProcessedAxis = -1;
	private int mLastProcessedSource = -1;
	private int mLastProcessedDeviceId = -1;

	// Initialize min and max to +infinity and 0, to effectively disable fling at start.
	private final int[] mFlingVelocityThresholds = new int[] {Integer.MAX_VALUE, 0};

	/** Interface to calculate the fling velocity thresholds. Helps fake during testing. */
	@VisibleForTesting
	public interface FlingVelocityThresholdCalculator {
	/**
	* Calculates the fling velocity thresholds (in pixels/second) and puts them in a provided
	* store.
	*
	* @param context the context associated with the View that may be flung.
	* @param store an at-least size-2 int array. The method will overwrite positions 0 and 1
	* with the min and max fling velocities, respectively.
	* @param event the event that may trigger fling.
	* @param axis the axis being processed for the event.
	*/
	void calculateFlingVelocityThresholds(
	Context context, int[] store, MotionEvent event, int axis);
	}

	/**
	* Interface to provide velocity. Helps fake during testing.
	*
	* <p>The client should call {@link #getCurrentVelocity(VelocityTracker, MotionEvent, int)} each
	* time it wants to consider a {@link MotionEvent} towards the latest velocity, and the
	* interface handles providing velocity that accounts for the latest and all past events.
	*/
	@VisibleForTesting
	public interface DifferentialVelocityProvider {
	/**
	* Returns the latest velocity.
	*
	* @param vt the {@link VelocityTracker} to be used to compute velocity.
	* @param event the latest event to be considered in the velocity computations.
	* @param axis the axis being processed for the event.
	* @return the calculated, latest velocity.
	*/
	float getCurrentVelocity(VelocityTracker vt, MotionEvent event, int axis);
	}

	/**
	* Represents an entity that may be flung by a differential motion or an entity that initiates
	* fling on a target View.
	*/
	public interface DifferentialMotionFlingTarget {
	/**
	* Start flinging on the target View by a given velocity.
	*
	* @param velocity the fling velocity, in pixels/second.
	* @return {@code true} if fling was successfully initiated, {@code false} otherwise.
	*/
	boolean startDifferentialMotionFling(float velocity);

	/** Stop any ongoing fling on the target View that is caused by a differential motion. */
	void stopDifferentialMotionFling();

	/**
	* Returns the scaled scroll factor to be used for differential motions. This is the
	* value that the raw {@link MotionEvent} values should be multiplied with to get pixels.
	*
	* <p>This usually is one of the values provided by {@link ViewConfiguration}. It is
	* up to the client to choose and provide any value as per its internal configuration.
	*
	* @see ViewConfiguration#getScaledHorizontalScrollFactor()
	* @see ViewConfiguration#getScaledVerticalScrollFactor()
	*/
	float getScaledScrollFactor();
	}

	/** Constructs an instance for a given {@link DifferentialMotionFlingTarget}. */
	public DifferentialMotionFlingHelper(
	Context context,
	DifferentialMotionFlingTarget target) {
	this(context,
	target,
	DifferentialMotionFlingHelper::calculateFlingVelocityThresholds,
	DifferentialMotionFlingHelper::getCurrentVelocity,
	/* widgetFeatureFlags= */ new FeatureFlagsImpl());
	}

	@VisibleForTesting
	public DifferentialMotionFlingHelper(
	Context context,
	DifferentialMotionFlingTarget target,
	FlingVelocityThresholdCalculator velocityThresholdCalculator,
	DifferentialVelocityProvider velocityProvider,
	FeatureFlags widgetFeatureFlags) {
	mContext = context;
	mTarget = target;
	mVelocityThresholdCalculator = velocityThresholdCalculator;
	mVelocityProvider = velocityProvider;
	mWidgetFeatureFlags = widgetFeatureFlags;
	}

	/**
	* Called to report when a differential motion happens on the View that's the target for fling.
	*
	* @param event the {@link MotionEvent} being reported.
	* @param axis the axis being processed by the target View.
	*/
	public void onMotionEvent(MotionEvent event, int axis) {
	if (!mWidgetFeatureFlags.enablePlatformWidgetDifferentialMotionFling()) {
	return;
	}
	boolean flingParamsChanged = calculateFlingVelocityThresholds(event, axis);
	if (mFlingVelocityThresholds[0] == Integer.MAX_VALUE) {
	// Integer.MAX_VALUE means that the device does not support fling for the current
	// configuration. Do not proceed any further.
	recycleVelocityTracker();
	return;
	}

	float scaledVelocity =
	getCurrentVelocity(event, axis) * mTarget.getScaledScrollFactor();

	float velocityDirection = Math.signum(scaledVelocity);
	// Stop ongoing fling if there has been state changes affecting fling, or if the current
	// velocity (if non-zero) is opposite of the velocity that last caused fling.
	if (flingParamsChanged
	\|\| (velocityDirection != Math.signum(mLastFlingVelocity)
	&& velocityDirection != 0)) {
	mTarget.stopDifferentialMotionFling();
	}

	if (Math.abs(scaledVelocity) < mFlingVelocityThresholds[0]) {
	return;
	}

	// Clamp the scaled velocity between [-max, max].
	// e.g. if max=100, and vel=200
	// vel = max(-100, min(200, 100)) = max(-100, 100) = 100
	// e.g. if max=100, and vel=-200
	// vel = max(-100, min(-200, 100)) = max(-100, -200) = -100
	scaledVelocity =
	Math.max(
	-mFlingVelocityThresholds[1],
	Math.min(scaledVelocity, mFlingVelocityThresholds[1]));

	boolean flung = mTarget.startDifferentialMotionFling(scaledVelocity);
	mLastFlingVelocity = flung ? scaledVelocity : 0;
	}

	/**
	* Calculates fling velocity thresholds based on the provided event and axis, and returns {@code
	* true} if there has been a change of any params that may affect fling velocity thresholds.
	*/
	private boolean calculateFlingVelocityThresholds(MotionEvent event, int axis) {
	int source = event.getSource();
	int deviceId = event.getDeviceId();
	if (mLastProcessedSource != source
	\|\| mLastProcessedDeviceId != deviceId
	\|\| mLastProcessedAxis != axis) {
	mVelocityThresholdCalculator.calculateFlingVelocityThresholds(
	mContext, mFlingVelocityThresholds, event, axis);
	// Save data about this processing so that we don't have to re-process fling thresholds
	// for similar parameters.
	mLastProcessedSource = source;
	mLastProcessedDeviceId = deviceId;
	mLastProcessedAxis = axis;
	return true;
	}
	return false;
	}

	private static void calculateFlingVelocityThresholds(
	Context context, int[] buffer, MotionEvent event, int axis) {
	int source = event.getSource();
	int deviceId = event.getDeviceId();

	ViewConfiguration vc = ViewConfiguration.get(context);
	buffer[0] = vc.getScaledMinimumFlingVelocity(deviceId, axis, source);
	buffer[1] = vc.getScaledMaximumFlingVelocity(deviceId, axis, source);
	}

	private float getCurrentVelocity(MotionEvent event, int axis) {
	if (mVelocityTracker == null) {
	mVelocityTracker = VelocityTracker.obtain();
	}

	return mVelocityProvider.getCurrentVelocity(mVelocityTracker, event, axis);
	}

	private void recycleVelocityTracker() {
	if (mVelocityTracker != null) {
	mVelocityTracker.recycle();
	mVelocityTracker = null;
	}
	}

	private static float getCurrentVelocity(VelocityTracker vt, MotionEvent event, int axis) {
	vt.addMovement(event);
	vt.computeCurrentVelocity(1000);
	return vt.getAxisVelocity(axis);
	}
	}