From 82ebfa96e5d47960af1b6cfd483077ce1e933d11 Mon Sep 17 00:00:00 2001
From: Yunfan Chen <yunfanc@google.com>
Date: Wed, 17 Jan 2024 18:57:14 +0900
Subject: Update configuration API docs to reflect behavior change

Update the API doc of screenWidthDp and screenHeightDp to reflect the
behavior change happening.

Bug: 151861875
Bug: 321168774
Test: N/A
Change-Id: I3e40b80f66d1c8d465cd1f4cc8bc0bc40d9a35ab
---
 core/java/android/content/res/Configuration.java | 55 +++++++++++++++---------
 1 file changed, 34 insertions(+), 21 deletions(-)

diff --git a/core/java/android/content/res/Configuration.java b/core/java/android/content/res/Configuration.java
index d27479299efa..885f4c5e8ec4 100644
--- a/core/java/android/content/res/Configuration.java
+++ b/core/java/android/content/res/Configuration.java
@@ -802,14 +802,20 @@ public final class Configuration implements Parcelable, Comparable<Configuration
     public static final int SCREEN_WIDTH_DP_UNDEFINED = 0;
 
     /**
-     * The width of the available screen space in dp units excluding the area
-     * occupied by {@link android.view.WindowInsets window insets}.
+     * The width of the available screen space in dp units.
      *
-     * <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)
+     * <aside class="note"><b>Note:</b> If the app targets
+     * {@link android.os.Build.VERSION_CODES#VANILLA_ICE_CREAM}
+     * or after, The width measurement reflects the window size without excluding insets.
+     * Otherwise, the measurement excludes window insets even when the app is displayed edge to edge
+     * using {@link android.view.Window#setDecorFitsSystemWindows(boolean)
      * Window#setDecorFitsSystemWindows(boolean)}.</aside>
      *
+     * Use {@link android.view.WindowMetrics#getBounds()} to always obtain the horizontal
+     * display area available to an app or embedded activity including the area
+     * occupied by window insets. A version of the API is also available for use on older platforms
+     * through {@link androidx.window.layout.WindowMetrics}.
+     *
      * <p>Corresponds to the
      * <a href="{@docRoot}guide/topics/resources/providing-resources.html#AvailableWidthHeightQualifier">
      * available width</a> resource qualifier. Defaults to
@@ -831,14 +837,15 @@ public final class Configuration implements Parcelable, Comparable<Configuration
      * environment, {@code screenWidthDp} is the width of the screen on which
      * the app is displayed excluding window insets.
      *
-     * <p>Differs from {@link android.view.WindowMetrics} by not including
+     * <p>If the app targets {@link android.os.Build.VERSION_CODES#VANILLA_ICE_CREAM} or after,
+     * it is the same as {@link android.view.WindowMetrics}, but is expressed rounded to the nearest
+     * dp rather than px.
+     *
+     * <p>Otherwise, differs from {@link android.view.WindowMetrics} by not including
      * 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.
+     * area occupied by window insets.
      */
     public int screenWidthDp;
 
@@ -849,15 +856,20 @@ public final class Configuration implements Parcelable, Comparable<Configuration
     public static final int SCREEN_HEIGHT_DP_UNDEFINED = 0;
 
     /**
-     * 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.
+     * The height of the available screen space in dp units.
      *
-     * <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)
+     * <aside class="note"><b>Note:</b> If the app targets
+     * {@link android.os.Build.VERSION_CODES#VANILLA_ICE_CREAM}
+     * or after, the height measurement reflects the window size without excluding insets.
+     * Otherwise, the measurement excludes window insets even when the app is displayed edge to edge
+     * using {@link android.view.Window#setDecorFitsSystemWindows(boolean)
      * Window#setDecorFitsSystemWindows(boolean)}.</aside>
      *
+     * Use {@link android.view.WindowMetrics#getBounds()} to always obtain the vertical
+     * display area available to an app or embedded activity including the area
+     * occupied by window insets. A version of the API is also available for use on older platforms
+     * through {@link androidx.window.layout.WindowMetrics}.
+     *
      * <p>Corresponds to the
      * <a href="{@docRoot}guide/topics/resources/providing-resources.html#AvailableWidthHeightQualifier">
      * available height</a> resource qualifier. Defaults to
@@ -879,14 +891,15 @@ public final class Configuration implements Parcelable, Comparable<Configuration
      * multiple-screen environment, {@code screenHeightDp} is the height of the
      * screen on which the app is displayed excluding window insets.
      *
-     * <p>Differs from {@link android.view.WindowMetrics} by not including
+     * <p>If the app targets {@link android.os.Build.VERSION_CODES#VANILLA_ICE_CREAM} or after,
+     * it is the same as {@link android.view.WindowMetrics}, but is expressed rounded to the nearest
+     * dp rather than px.
+     *
+     * <p>Otherwise, differs from {@link android.view.WindowMetrics} by not including
      * 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.
+     * area occupied by window insets.
      */
     public int screenHeightDp;
 
-- 
cgit v1.2.3-59-g8ed1b