diff options
| -rw-r--r-- | core/java/android/view/Display.java | 121 |
1 files changed, 68 insertions, 53 deletions
diff --git a/core/java/android/view/Display.java b/core/java/android/view/Display.java index 9cb0d1ff2c3f..a06b0e0355d8 100644 --- a/core/java/android/view/Display.java +++ b/core/java/android/view/Display.java @@ -741,35 +741,42 @@ public final class Display { } /** - * Gets the size of the display, in pixels. - * Value returned by this method does not necessarily represent the actual raw size - * (native resolution) of the display. - * <p> - * 1. The returned size may be adjusted to exclude certain system decor elements - * that are always visible. - * </p><p> - * 2. It may be scaled to provide compatibility with older applications that - * were originally designed for smaller displays. - * </p><p> - * 3. It can be different depending on the WindowManager to which the display belongs. - * </p><p> - * - If requested from non-Activity context (e.g. Application context via - * {@code (WindowManager) getApplicationContext().getSystemService(Context.WINDOW_SERVICE)}) - * it will report the size of the entire display based on current rotation and with subtracted - * system decoration areas. - * </p><p> - * - If requested from activity (either using {@code getWindowManager()} or - * {@code (WindowManager) getSystemService(Context.WINDOW_SERVICE)}) resulting size will - * correspond to current app window size. In this case it can be smaller than physical size in - * multi-window mode. - * </p><p> - * Typically for the purposes of layout apps should make a request from activity context - * to obtain size available for the app content. - * </p> + * Gets the size of the display in pixels. + * + * <p>The return value does not necessarily represent the actual size (native resolution) of the + * display. The returned size might be adjusted to exclude certain system decor elements that + * are always visible, or the size might be scaled to provide compatibility with older + * applications that were originally designed for smaller displays. + * + * <p>The returned size can also be different depending on the WindowManager bound to the + * display: + * <ul> + * <li>If size is requested from an activity (either using a WindowManager accessed by + * {@code getWindowManager()} or {@code getSystemService(Context.WINDOW_SERVICE)}), the + * size of the current app window is returned. As a result, in multi-window mode, the + * returned size can be smaller than the size of the device screen. + * <li>If size is requested from a non-activity context (for example, the application + * context, where the WindowManager is accessed by + * {@code getApplicationContext().getSystemService(Context.WINDOW_SERVICE)}), the + * returned size can vary depending on API level: + * <ul> + * <li>API level 29 and below — The size of the entire display (based on + * current rotation) minus system decoration areas is returned. + * <li>API level 30 and above — The size of the top running activity in the + * current process is returned. If the current process has no running + * activities, the size of the device default display, including system + * decoration areas, is returned. + * </ul> + * </ul> + * + * <p>For layout purposes, apps should make a request from an activity context to obtain the + * size of the display area available for app content. + * + * @param outSize A {@link Point} object which receives the display size information. * - * @param outSize A {@link Point} object to receive the size information. - * @deprecated Use {@link WindowManager#getCurrentWindowMetrics()} to obtain an instance of - * {@link WindowMetrics} and use {@link WindowMetrics#getBounds()} instead. + * @deprecated Use {@link WindowMetrics} instead. Obtain a {@code WindowMetrics} instance by + * calling {@link WindowManager#getCurrentWindowMetrics()}, then call + * {@link WindowMetrics#getBounds()} to get the dimensions of the application window. */ @Deprecated public void getSize(Point outSize) { @@ -785,8 +792,9 @@ public final class Display { * Gets the size of the display as a rectangle, in pixels. * * @param outSize A {@link Rect} object to receive the size information. + * * @deprecated Use {@link WindowMetrics#getBounds()} to get the dimensions of the application - * window area. + * window. */ @Deprecated public void getRectSize(Rect outSize) { @@ -1275,32 +1283,39 @@ public final class Display { } /** - * Gets display metrics that describe the size and density of this display. - * The size returned by this method does not necessarily represent the - * actual raw size (native resolution) of the display. - * <p> - * 1. The returned size may be adjusted to exclude certain system decor elements - * that are always visible. - * </p><p> - * 2. It may be scaled to provide compatibility with older applications that - * were originally designed for smaller displays. - * </p><p> - * 3. It can be different depending on the WindowManager to which the display belongs. - * </p><p> - * - If requested from non-Activity context (e.g. Application context via - * {@code (WindowManager) getApplicationContext().getSystemService(Context.WINDOW_SERVICE)}) - * metrics will report the size of the entire display based on current rotation and with - * subtracted system decoration areas. - * </p><p> - * - If requested from activity (either using {@code getWindowManager()} or - * {@code (WindowManager) getSystemService(Context.WINDOW_SERVICE)}) resulting metrics will - * correspond to current app window metrics. In this case the size can be smaller than physical - * size in multi-window mode. - * </p> + * Gets the size and density of this display. + * + * <p>The size returned does not necessarily represent the actual size (native resolution) of + * the display. The returned size might be adjusted to exclude certain system decor elements + * that are always visible, or the size might be scaled to provide compatibility with older + * applications that were originally designed for smaller displays. + * + * <p>The returned size can also be different depending on the WindowManager associated with the + * display: + * <ul> + * <li>If metrics are requested from an activity (either using a WindowManager accessed by + * {@code getWindowManager()} or {@code getSystemService(Context.WINDOW_SERVICE)}), the + * returned metrics provide the size of the current app window. As a result, in + * multi-window mode, the returned size can be smaller than the size of the device + * screen. + * <li>If metrics are requested from a non-activity context (for example, the application + * context, where the WindowManager is accessed by + * {@code getApplicationContext().getSystemService(Context.WINDOW_SERVICE)}), the + * returned size can vary depending on API level: + * <ul> + * <li>API level 29 and below — The returned metrics provide the size of the + * entire display (based on current rotation) minus system decoration areas. + * <li>API level 30 and above — The returned metrics provide the size of the + * top running activity in the current process. If the current process has no + * running activities, the metrics provide the size of the default display of + * the device, including system decoration areas. + * </ul> + * </ul> + * + * @param outMetrics A {@link DisplayMetrics} object which receives the display metrics. * - * @param outMetrics A {@link DisplayMetrics} object to receive the metrics. * @deprecated Use {@link WindowMetrics#getBounds()} to get the dimensions of the application - * window area, and {@link Configuration#densityDpi} to get the current density. + * window. Use {@link Configuration#densityDpi} to get the display density. */ @Deprecated public void getMetrics(DisplayMetrics outMetrics) { |