From 136e08f6197cafb65af3f91d32b53fc4c796d480 Mon Sep 17 00:00:00 2001 From: joneckenrode Date: Mon, 23 May 2022 20:08:13 +0000 Subject: [PATCH] Revised the API documentation for screenWidthDp and screenHeightDp to include information about window insets and embedded activities. Bug: 170805355 Bug: 232947647 Test: Built API documentation Signed-off-by: joneckenrode Change-Id: I72f1e6a9b724ce2559aacc0162f2107799c0252f --- .../android/content/res/Configuration.java | 82 ++++++++++++------- 1 file changed, 51 insertions(+), 31 deletions(-) diff --git a/core/java/android/content/res/Configuration.java b/core/java/android/content/res/Configuration.java index 29f21f14088e6..3dedc41312515 100644 --- a/core/java/android/content/res/Configuration.java +++ b/core/java/android/content/res/Configuration.java @@ -751,9 +751,15 @@ public final class Configuration implements Parcelable, ComparableNote: The width measurement excludes window + * insets even when the app is displayed edge to edge using + * {@link android.view.Window#setDecorFitsSystemWindows(boolean) + * Window#setDecorFitsSystemWindows(boolean)}. + * + *

Corresponds to the * * available width resource qualifier. Defaults to * {@link #SCREEN_WIDTH_DP_UNDEFINED} if no width is specified. @@ -763,21 +769,25 @@ public final class Configuration implements Parcelable, ComparableFor embedded activities, equals the width of the individual + * activities, not the width of the app window or the device screen. + * *

In multiple-screen scenarios, the width measurement can span screens. * For example, if the app is spanning both screens of a dual-screen device * (with the screens side by side), {@code screenWidthDp} represents the - * width of both screens, excluding the area occupied by screen decorations. - * When the app is restricted to a single screen in a multiple-screen + * width of both screens excluding the area occupied by window insets. When + * the app is restricted to a single screen in a multiple-screen * environment, {@code screenWidthDp} is the width of the screen on which - * the app is running. + * the app is displayed excluding window insets. * *

Differs from {@link android.view.WindowMetrics} by not including - * screen decorations in the width measurement and by expressing the - * measurement in dp rather than px. Use {@code screenWidthDp} to obtain the - * horizontal display area available to the app, excluding the area occupied - * by screen decorations. Use {@link android.view.WindowMetrics#getBounds()} - * to obtain the width of the display area available to the app, including - * the area occupied by screen decorations. + * window insets in the width measurement and by expressing the measurement + * in dp rather than px. Use {@code screenWidthDp} to obtain the width of + * the display area available to an app or embedded activity excluding the + * area occupied by window insets. Use + * {@link android.view.WindowMetrics#getBounds()} to obtain the horizontal + * display area available to an app or embedded activity including the area + * occupied by window insets. */ public int screenWidthDp; @@ -788,9 +798,16 @@ public final class Configuration implements Parcelable, ComparableNote: The height measurement excludes window + * insets even when the app is displayed edge to edge using + * {@link android.view.Window#setDecorFitsSystemWindows(boolean) + * Window#setDecorFitsSystemWindows(boolean)}. + * + *

Corresponds to the * * available height resource qualifier. Defaults to * {@link #SCREEN_HEIGHT_DP_UNDEFINED} if no height is specified. @@ -800,22 +817,25 @@ public final class Configuration implements Parcelable, ComparableFor embedded activities, equals the height of the individual + * activities, not the height of the app window or the device screen. + * *

In multiple-screen scenarios, the height measurement can span screens. * For example, if the app is spanning both screens of a dual-screen device * rotated 90 degrees (one screen above the other), {@code screenHeightDp} - * represents the height of both screens, excluding the area occupied by - * screen decorations. When the app is restricted to a single screen in a + * represents the height of both screens excluding the area occupied by + * window insets. When the app is restricted to a single screen in a * multiple-screen environment, {@code screenHeightDp} is the height of the - * screen on which the app is running. + * screen on which the app is displayed excluding window insets. * *

Differs from {@link android.view.WindowMetrics} by not including - * screen decorations in the height measurement and by expressing the - * measurement in dp rather than px. Use {@code screenHeightDp} to obtain - * the vertical display area available to the app, excluding the area - * occupied by screen decorations. Use - * {@link android.view.WindowMetrics#getBounds()} to obtain the height of - * the display area available to the app, including the area occupied by - * screen decorations. + * window insets in the height measurement and by expressing the measurement + * in dp rather than px. Use {@code screenHeightDp} to obtain the height of + * the display area available to an app or embedded activity excluding the + * area occupied by window insets. Use + * {@link android.view.WindowMetrics#getBounds()} to obtain the vertical + * display area available to an app or embedded activity including the area + * occupied by window insets. */ public int screenHeightDp; @@ -826,12 +846,12 @@ public final class Configuration implements Parcelable, Comparablesmallest - * screen width resource qualifier. - * This is the smallest value of both screenWidthDp and screenHeightDp - * in both portrait and landscape. Set to + * The smallest screen size an application will see in normal operation. + * Corresponds to the + * + * smallest width resource qualifier. This is the smallest value of + * {@link #screenWidthDp} and {@link #screenHeightDp} in both portrait and + * landscape orientations. Defaults to * {@link #SMALLEST_SCREEN_WIDTH_DP_UNDEFINED} if no width is specified. */ public int smallestScreenWidthDp;