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 <joneckenrode@google.com>
Change-Id: I72f1e6a9b724ce2559aacc0162f2107799c0252f
diff --git a/core/java/android/content/res/Configuration.java b/core/java/android/content/res/Configuration.java
index 29f21f1..3dedc41 100644
--- a/core/java/android/content/res/Configuration.java
+++ b/core/java/android/content/res/Configuration.java
@@ -751,9 +751,15 @@
public static final int SCREEN_WIDTH_DP_UNDEFINED = 0;
/**
- * The current width of the available screen space in dp units, excluding
- * the area occupied by screen decorations at the edges of the display.
- * Corresponds to the
+ * The width of the available screen space in dp units excluding the area
+ * occupied by {@link android.view.WindowInsets window insets}.
+ *
+ * <aside class="note"><b>Note:</b> 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)}.</aside>
+ *
+ * <p>Corresponds to the
* <a href="{@docRoot}guide/topics/resources/providing-resources.html#AvailableWidthHeightQualifier">
* available width</a> resource qualifier. Defaults to
* {@link #SCREEN_WIDTH_DP_UNDEFINED} if no width is specified.
@@ -763,21 +769,25 @@
* (for example, when apps are displayed side by side in split-screen mode
* in landscape orientation).
*
+ * <p>For embedded activities, equals the width of the individual
+ * activities, not the width of the app window or the device screen.
+ *
* <p>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.
*
* <p>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 static final int SCREEN_HEIGHT_DP_UNDEFINED = 0;
/**
- * The current height of the available screen space in dp units, excluding
- * the area occupied by screen decorations at the edges of the display (such
- * as the status bar, navigation bar, and cutouts). Corresponds to the
+ * The height of the available screen space in dp units excluding the area
+ * occupied by {@link android.view.WindowInsets window insets}, such as the
+ * status bar, navigation bar, and cutouts.
+ *
+ * <aside class="note"><b>Note:</b> 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)}.</aside>
+ *
+ * <p>Corresponds to the
* <a href="{@docRoot}guide/topics/resources/providing-resources.html#AvailableWidthHeightQualifier">
* available height</a> resource qualifier. Defaults to
* {@link #SCREEN_HEIGHT_DP_UNDEFINED} if no height is specified.
@@ -800,22 +817,25 @@
* (for example, when apps are displayed one above another in split-screen
* mode in portrait orientation).
*
+ * <p>For embedded activities, equals the height of the individual
+ * activities, not the height of the app window or the device screen.
+ *
* <p>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.
*
* <p>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 static final int SMALLEST_SCREEN_WIDTH_DP_UNDEFINED = 0;
/**
- * The smallest screen size an application will see in normal operation,
- * corresponding to
- * <a href="{@docRoot}guide/topics/resources/providing-resources.html#SmallestScreenWidthQualifier">smallest
- * screen width</a> 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
+ * <a href="{@docRoot}guide/topics/resources/providing-resources.html#SmallestScreenWidthQualifier">
+ * smallest width</a> 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;