Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit f860c586 authored by Prabir Pradhan's avatar Prabir Pradhan
Browse files

MotionEvent docs: Clarify relative axis processing for batched events 

Bug: 361614673
Change-Id: I8a770bdd3b4a19ab9b78c9f699f321da0d7e6e59
Test: None
Flag: DOCS_ONLY
parent 448a9ffa

core/java/android/view/MotionEvent.java

+22 −7
Original line number Diff line number Diff line
@@ -127,7 +127,16 @@ import java.util.Objects; 
 *             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>
@@ -1079,6 +1088,9 @@ public final class MotionEvent extends InputEvent implements Parcelable { 
     * 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)
@@ -1092,6 +1104,9 @@ public final class MotionEvent extends InputEvent implements Parcelable { 
     * 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)
@@ -1286,8 +1301,8 @@ public final class MotionEvent extends InputEvent implements Parcelable { 
     * 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.

     */
@@ -1307,8 +1322,8 @@ public final class MotionEvent extends InputEvent implements Parcelable { 
     * <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.

     */
@@ -1329,8 +1344,8 @@ public final class MotionEvent extends InputEvent implements Parcelable { 
     * 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.

     */