Merge "Revised API documentation of getLocationOnScreen, getLocationInWindow, and getLocationInSurface to include multiple-screen behavior and remove mentions of "global" coordinate space." into tm-dev am: d2b8731f93

Original change: https://googleplex-android-review.googlesource.com/c/platform/frameworks/base/+/17826643

Change-Id: I14e1cb718cab9ed515b770ec36f912aa73f92d0b
Ignore-AOSP-First: this is an automerge
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>

1 files changed, 23 insertions, 11 deletions

diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index f8c7cd049365..cf5727ea1342 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -12063,6 +12063,9 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
      * Gets the coordinates of this view in the coordinate space of the
      * {@link Surface} that contains the view.
      *
+     * <p>In multiple-screen scenarios, if the surface spans multiple screens,
+     * the coordinate space of the surface also spans multiple screens.
+     *
      * <p>After the method returns, the argument array contains the x- and
      * y-coordinates of the view relative to the view's left and top edges,
      * respectively.
@@ -25585,19 +25588,23 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
     }
 
     /**
-     * Gets the global coordinates of this view. The coordinates are in the
-     * coordinate space of the device screen, irrespective of system decorations
-     * and whether the system is in multi-window mode.
+     * Gets the coordinates of this view in the coordinate space of the device
+     * screen, irrespective of system decorations and whether the system is in
+     * multi-window mode.
      *
-     * <p>In multi-window mode, the global coordinate space encompasses the
-     * entire device screen, ignoring the bounds of the app window. For
-     * example, if the view is in the bottom portion of a horizontal split
-     * screen, the top edge of the screen&mdash;not the top edge of the
-     * window&mdash;is the origin from which the y-coordinate is calculated.
+     * <p>In multi-window mode, the coordinate space encompasses the entire
+     * device screen, ignoring the bounds of the app window. For example, if the
+     * view is in the bottom portion of a horizontal split screen, the top edge
+     * of the screen&mdash;not the top edge of the window&mdash;is the origin
+     * from which the y-coordinate is calculated.
      *
-     * <p><b>Note:</b> In multiple-screen scenarios, the global coordinate space
-     * is restricted to the screen on which the view is displayed. The
-     * coordinate space does not span multiple screens.
+     * <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 view is located on the right-hand screen, the x-coordinate is
+     * calculated from the left edge of the left-hand screen to the left edge of
+     * the view. 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>After the method returns, the argument array contains the x- and
      * y-coordinates of the view relative to the view's left and top edges,
@@ -25625,6 +25632,11 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
      * top left corner of the window that contains the view. In full screen
      * mode, the origin is the top left corner of the device screen.
      *
+     * <p>In multiple-screen scenarios, if the app spans multiple screens, the
+     * coordinate space also spans multiple screens. But if the app is
+     * restricted to a single screen, the coordinate space includes only the
+     * screen on which the app is running.
+     *
      * <p>After the method returns, the argument array contains the x- and
      * y-coordinates of the view relative to the view's left and top edges,
      * respectively.