* A logical display does not necessarily represent a particular physical display device @@ -1230,27 +1230,51 @@ public final class Display { } /** - * Gets the real size of the display without subtracting any window decor or - * applying any compatibility scale factors. + * Gets the size of the largest region of the display accessible to an app in the current system + * state, without subtracting any window decor or applying scaling factors. *
* The size is adjusted based on the current rotation of the display. + *
+ * The returned size will fall into one of these scenarios: + *- * The real size may be smaller than the physical size of the screen when the - * window manager is emulating a smaller display (using adb shell wm size). - *
- * In general, {@link #getRealSize(Point)} and {@link WindowManager#getMaximumWindowMetrics()} - * report the same bounds except that certain areas of the display may not be available to - * windows created in the {@link WindowManager}'s {@link Context}. - * - * For example, imagine a device which has a multi-task mode that limits windows to half of the - * screen. In this case, {@link WindowManager#getMaximumWindowMetrics()} reports the - * bounds of the screen half where the window is located, while {@link #getRealSize(Point)} - * still reports the bounds of the whole display. + * The returned value is unsuitable to use when sizing and placing UI elements, since it + * does not reflect the application window size in any of these scenarios. + * {@link WindowManager#getCurrentWindowMetrics()} is an alternative that returns the size + * of the current application window, even if the window is on a device with a partitioned + * display. This helps prevent UI bugs where UI elements are misaligned or placed beyond the + * bounds of the window. + *
+ * Handling multi-window mode correctly is necessary since applications are not always + * fullscreen. A user on a large screen device, such as a tablet or Chrome OS devices, is more + * likely to use multi-window modes. + * + * For example, consider a device with a display partitioned into two halves. The user may have + * a fullscreen application open on the first partition. They may have two applications open in + * split screen (an example of multi-window mode) on the second partition, with each application + * consuming half of the partition. In this case, + * {@link WindowManager#getCurrentWindowMetrics()} reports the fullscreen window is half of the + * screen in size, and each split screen window is a quarter of the screen in size. On the other + * hand, {@link #getRealSize} reports half of the screen size for all windows, since the + * application windows are all restricted to their respective partitions. + * * * @param outSize Set to the real size of the display. - * - * @see WindowManager#getMaximumWindowMetrics() + * @deprecated Use {@link WindowManager#getCurrentWindowMetrics()} to identify the current size + * of the activity window. UI-related work, such as choosing UI layouts, should rely + * upon {@link WindowMetrics#getBounds()}. */ + @Deprecated public void getRealSize(Point outSize) { synchronized (this) { updateDisplayInfoLocked(); @@ -1263,16 +1287,52 @@ public final class Display { } /** - * Gets display metrics based on the real size of this display. + * Gets the size of the largest region of the display accessible to an app in the current system + * state, without subtracting any window decor or applying scaling factors. ** The size is adjusted based on the current rotation of the display. + *
+ * The returned size will fall into one of these scenarios: + *- * The real size may be smaller than the physical size of the screen when the - * window manager is emulating a smaller display (using adb shell wm size). + * The returned value is unsuitable to use when sizing and placing UI elements, since it + * does not reflect the application window size in any of these scenarios. + * {@link WindowManager#getCurrentWindowMetrics()} is an alternative that returns the size + * of the current application window, even if the window is on a device with a partitioned + * display. This helps prevent UI bugs where UI elements are misaligned or placed beyond the + * bounds of the window. + *
+ * Handling multi-window mode correctly is necessary since applications are not always + * fullscreen. A user on a large screen device, such as a tablet or Chrome OS devices, is more + * likely to use multi-window modes. + * + * For example, consider a device with a display partitioned into two halves. The user may have + * a fullscreen application open on the first partition. They may have two applications open in + * split screen (an example of multi-window mode) on the second partition, with each application + * consuming half of the partition. In this case, + * {@link WindowManager#getCurrentWindowMetrics()} reports the fullscreen window is half of the + * screen in size, and each split screen window is a quarter of the screen in size. On the other + * hand, {@link #getRealMetrics} reports half of the screen size for all windows, since the + * application windows are all restricted to their respective partitions. * * * @param outMetrics A {@link DisplayMetrics} object to receive the metrics. + * @deprecated Use {@link WindowManager#getCurrentWindowMetrics()} to identify the current size + * of the activity window. UI-related work, such as choosing UI layouts, should rely + * upon {@link WindowMetrics#getBounds()}. Use {@link Configuration#densityDpi} to + * get the current density. */ + @Deprecated public void getRealMetrics(DisplayMetrics outMetrics) { synchronized (this) { updateDisplayInfoLocked();