diff options
| -rw-r--r-- | core/java/android/view/MotionEvent.java | 156 |
1 files changed, 114 insertions, 42 deletions
diff --git a/core/java/android/view/MotionEvent.java b/core/java/android/view/MotionEvent.java index cc93adc32541..0bed342a8b27 100644 --- a/core/java/android/view/MotionEvent.java +++ b/core/java/android/view/MotionEvent.java @@ -2280,8 +2280,11 @@ public final class MotionEvent extends InputEvent implements Parcelable { } /** - * {@link #getX(int)} for the first pointer index (may be an - * arbitrary pointer identifier). + * Equivalent to {@link #getX(int)} for pointer index 0 (regardless of the + * pointer identifier). + * + * @return The X coordinate of the first pointer index in the coordinate + * space of the view that received this motion event. * * @see #AXIS_X */ @@ -2290,8 +2293,11 @@ public final class MotionEvent extends InputEvent implements Parcelable { } /** - * {@link #getY(int)} for the first pointer index (may be an - * arbitrary pointer identifier). + * Equivalent to {@link #getY(int)} for pointer index 0 (regardless of the + * pointer identifier). + * + * @return The Y coordinate of the first pointer index in the coordinate + * space of the view that received this motion event. * * @see #AXIS_Y */ @@ -2433,13 +2439,20 @@ public final class MotionEvent extends InputEvent implements Parcelable { } /** - * Returns the X coordinate of this event for the given pointer - * <em>index</em> (use {@link #getPointerId(int)} to find the pointer - * identifier for this index). - * Whole numbers are pixels; the - * value may have a fraction for input devices that are sub-pixel precise. - * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 - * (the first pointer that is down) to {@link #getPointerCount()}-1. + * Returns the X coordinate of the pointer referenced by + * {@code pointerIndex} for this motion event. The coordinate is in the + * coordinate space of the view that received this motion event. + * + * <p>Use {@link #getPointerId(int)} to get the pointer identifier for the + * pointer referenced by {@code pointerIndex}. + * + * @param pointerIndex Index of the pointer for which the X coordinate is + * returned. May be a value in the range of 0 (the first pointer that + * is down) to {@link #getPointerCount()} - 1. + * @return The X coordinate of the pointer referenced by + * {@code pointerIndex} for this motion event. The unit is pixels. The + * value may contain a fractional portion for devices that are subpixel + * precise. * * @see #AXIS_X */ @@ -2448,13 +2461,20 @@ public final class MotionEvent extends InputEvent implements Parcelable { } /** - * Returns the Y coordinate of this event for the given pointer - * <em>index</em> (use {@link #getPointerId(int)} to find the pointer - * identifier for this index). - * Whole numbers are pixels; the - * value may have a fraction for input devices that are sub-pixel precise. - * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 - * (the first pointer that is down) to {@link #getPointerCount()}-1. + * Returns the Y coordinate of the pointer referenced by + * {@code pointerIndex} for this motion event. The coordinate is in the + * coordinate space of the view that received this motion event. + * + * <p>Use {@link #getPointerId(int)} to get the pointer identifier for the + * pointer referenced by {@code pointerIndex}. + * + * @param pointerIndex Index of the pointer for which the Y coordinate is + * returned. May be a value in the range of 0 (the first pointer that + * is down) to {@link #getPointerCount()} - 1. + * @return The Y coordinate of the pointer referenced by + * {@code pointerIndex} for this motion event. The unit is pixels. The + * value may contain a fractional portion for devices that are subpixel + * precise. * * @see #AXIS_Y */ @@ -2700,12 +2720,13 @@ public final class MotionEvent extends InputEvent implements Parcelable { } /** - * Returns the original raw X coordinate of this event. For touch - * events on the screen, this is the original location of the event - * on the screen, before it had been adjusted for the containing window - * and views. + * Equivalent to {@link #getRawX(int)} for pointer index 0 (regardless of + * the pointer identifier). * - * @see #getX(int) + * @return The X coordinate of the first pointer index in the coordinate + * space of the device display. + * + * @see #getX() * @see #AXIS_X */ public final float getRawX() { @@ -2713,12 +2734,13 @@ public final class MotionEvent extends InputEvent implements Parcelable { } /** - * Returns the original raw Y coordinate of this event. For touch - * events on the screen, this is the original location of the event - * on the screen, before it had been adjusted for the containing window - * and views. + * Equivalent to {@link #getRawY(int)} for pointer index 0 (regardless of + * the pointer identifier). * - * @see #getY(int) + * @return The Y coordinate of the first pointer index in the coordinate + * space of the device display. + * + * @see #getY() * @see #AXIS_Y */ public final float getRawY() { @@ -2726,13 +2748,38 @@ public final class MotionEvent extends InputEvent implements Parcelable { } /** - * Returns the original raw X coordinate of this event. For touch - * events on the screen, this is the original location of the event - * on the screen, before it had been adjusted for the containing window - * and views. - * - * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 - * (the first pointer that is down) to {@link #getPointerCount()}-1. + * Returns the X coordinate of the pointer referenced by + * {@code pointerIndex} for this motion event. The coordinate is in the + * coordinate space of the device display, irrespective of system + * decorations and whether or not the system is in multi-window mode. If the + * app spans multiple screens in a multiple-screen environment, the + * coordinate space includes all of the spanned screens. + * + * <p>In multi-window mode, the coordinate space extends beyond the bounds + * of the app window to encompass the entire display area. For example, if + * the motion event occurs in the right-hand window of split-screen mode in + * landscape orientation, the left edge of the screen—not the left + * edge of the window—is the origin from which the X coordinate is + * calculated. + * + * <p>In multiple-screen scenarios, the coordinate space can span screens. + * For example, if the app is spanning both screens of a dual-screen device, + * and the motion event occurs on the right-hand screen, the X coordinate is + * calculated from the left edge of the left-hand screen to the point of the + * motion event on the right-hand screen. When the app is restricted to a + * single screen in a multiple-screen environment, the coordinate space + * includes only the screen on which the app is running. + * + * <p>Use {@link #getPointerId(int)} to get the pointer identifier for the + * pointer referenced by {@code pointerIndex}. + * + * @param pointerIndex Index of the pointer for which the X coordinate is + * returned. May be a value in the range of 0 (the first pointer that + * is down) to {@link #getPointerCount()} - 1. + * @return The X coordinate of the pointer referenced by + * {@code pointerIndex} for this motion event. The unit is pixels. The + * value may contain a fractional portion for devices that are subpixel + * precise. * * @see #getX(int) * @see #AXIS_X @@ -2742,13 +2789,38 @@ public final class MotionEvent extends InputEvent implements Parcelable { } /** - * Returns the original raw Y coordinate of this event. For touch - * events on the screen, this is the original location of the event - * on the screen, before it had been adjusted for the containing window - * and views. - * - * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 - * (the first pointer that is down) to {@link #getPointerCount()}-1. + * Returns the Y coordinate of the pointer referenced by + * {@code pointerIndex} for this motion event. The coordinate is in the + * coordinate space of the device display, irrespective of system + * decorations and whether or not the system is in multi-window mode. If the + * app spans multiple screens in a multiple-screen environment, the + * coordinate space includes all of the spanned screens. + * + * <p>In multi-window mode, the coordinate space extends beyond the bounds + * of the app window to encompass the entire device screen. For example, if + * the motion event occurs in the lower window of split-screen mode in + * portrait orientation, the top edge of the screen—not the top edge + * of the window—is the origin from which the Y coordinate is + * determined. + * + * <p>In multiple-screen scenarios, the coordinate space can span screens. + * For example, if the app is spanning both screens of a dual-screen device + * that's rotated 90 degrees, and the motion event occurs on the lower + * screen, the Y coordinate is calculated from the top edge of the upper + * screen to the point of the motion event on the lower screen. When the app + * is restricted to a single screen in a multiple-screen environment, the + * coordinate space includes only the screen on which the app is running. + * + * <p>Use {@link #getPointerId(int)} to get the pointer identifier for the + * pointer referenced by {@code pointerIndex}. + * + * @param pointerIndex Index of the pointer for which the Y coordinate is + * returned. May be a value in the range of 0 (the first pointer that + * is down) to {@link #getPointerCount()} - 1. + * @return The Y coordinate of the pointer referenced by + * {@code pointerIndex} for this motion event. The unit is pixels. The + * value may contain a fractional portion for devices that are subpixel + * precise. * * @see #getY(int) * @see #AXIS_Y |