Merge "MotionEvent docs: Clarify relative axis processing for batched events" into main am: d073eb8384
Original change: https://android-review.googlesource.com/c/platform/frameworks/base/+/3237700
Change-Id: Iafa2e28a81986cec26009376af2f6edd807c17a1
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
diff --git a/core/java/android/view/MotionEvent.java b/core/java/android/view/MotionEvent.java
index 79a9f2d..8e3311e 100644
--- a/core/java/android/view/MotionEvent.java
+++ b/core/java/android/view/MotionEvent.java
@@ -136,7 +136,16 @@
* ev.getPointerId(p), ev.getX(p), ev.getY(p));
* }
* }
- * </code></pre></p>
+ * </code></pre></p><p>
+ * Developers should keep in mind that it is especially important to consume all samples
+ * in a batched event when processing relative values that report changes since the last
+ * event or sample. Examples of such relative axes include {@link #AXIS_RELATIVE_X},
+ * {@link #AXIS_RELATIVE_Y}, and many of the axes prefixed with {@code AXIS_GESTURE_}.
+ * In these cases, developers should first consume all historical values using
+ * {@link #getHistoricalAxisValue(int, int)} and then consume the current values using
+ * {@link #getAxisValue(int)} like in the example above, as these relative values are
+ * not accumulated in a batched event.
+ * </p>
*
* <h3>Device Types</h3>
* <p>
@@ -1125,6 +1134,9 @@
* the location but this axis reports the difference which allows the app to see
* how the mouse is moved.
* </ul>
+ * </p><p>
+ * These values are relative to the state from the last sample, not accumulated, so developers
+ * should make sure to process this axis value for all batched historical samples.
* </p>
*
* @see #getAxisValue(int, int)
@@ -1138,6 +1150,9 @@
* Axis constant: The movement of y position of a motion event.
* <p>
* This is similar to {@link #AXIS_RELATIVE_X} but for y-axis.
+ * </p><p>
+ * These values are relative to the state from the last sample, not accumulated, so developers
+ * should make sure to process this axis value for all batched historical samples.
* </p>
*
* @see #getAxisValue(int, int)
@@ -1332,8 +1347,8 @@
* swipe gesture starts at X = 500 then moves to X = 400, this axis would have a value of
* -0.1.
* </ul>
- * These values are relative to the state from the last event, not accumulated, so developers
- * should make sure to process this axis value for all batched historical events.
+ * These values are relative to the state from the last sample, not accumulated, so developers
+ * should make sure to process this axis value for all batched historical samples.
* <p>
* This axis is only set on the first pointer in a motion event.
*/
@@ -1353,8 +1368,8 @@
* <li>For a touch pad, reports the distance that should be scrolled in the X axis as a result
* of the user's two-finger scroll gesture, in display pixels.
* </ul>
- * These values are relative to the state from the last event, not accumulated, so developers
- * should make sure to process this axis value for all batched historical events.
+ * These values are relative to the state from the last sample, not accumulated, so developers
+ * should make sure to process this axis value for all batched historical samples.
* <p>
* This axis is only set on the first pointer in a motion event.
*/
@@ -1375,8 +1390,8 @@
* making a pinch gesture, as a proportion of the previous distance. For example, if the fingers
* were 50 units apart and are now 52 units apart, the scale factor would be 1.04.
* </ul>
- * These values are relative to the state from the last event, not accumulated, so developers
- * should make sure to process this axis value for all batched historical events.
+ * These values are relative to the state from the last sample, not accumulated, so developers
+ * should make sure to process this axis value for all batched historical samples.
* <p>
* This axis is only set on the first pointer in a motion event.
*/