Update WindowManager's WindowMetrics documentation

Describe when current and max should be used explicitly, to prevent app developers from mis-using getMaximumWindowMetrics in multiwindow modes.

Bug: 175209525
Change-Id: I953917f088325a6a029691cdaafddb94809dde05
Test: manual

1 files changed, 16 insertions, 11 deletions

diff --git a/core/java/android/view/WindowManager.java b/core/java/android/view/WindowManager.java
index 1819da4a86a0..7e9a850178fc 100644
--- a/core/java/android/view/WindowManager.java
+++ b/core/java/android/view/WindowManager.java
@@ -613,6 +613,10 @@ public interface WindowManager extends ViewManager {
      * For example, for activities in multi-window mode, the metrics returned are based on the
      * current bounds that the user has selected for the {@link android.app.Activity Activity}'s
      * task.
+     * <p>
+     * In most scenarios, {@link #getCurrentWindowMetrics()} rather than
+     * {@link #getMaximumWindowMetrics()} is the correct API to use, since it ensures values reflect
+     * window size when the app is not fullscreen.
      *
      * @see #getMaximumWindowMetrics()
      * @see WindowMetrics
@@ -624,26 +628,27 @@ public interface WindowManager extends ViewManager {
     /**
      * Returns the largest {@link WindowMetrics} an app may expect in the current system state.
      * <p>
-     * The metrics describe the size of the largest potential area the window might occupy with
-     * {@link LayoutParams#MATCH_PARENT MATCH_PARENT} width and height, and the {@link WindowInsets}
-     * such a window would have.
-     * <p>
      * The value of this is based on the largest <b>potential</b> windowing state of the system.
      *
      * For example, for activities in multi-window mode, the metrics returned are based on the
      * what the bounds would be if the user expanded the {@link android.app.Activity Activity}'s
      * task to cover the entire screen.
-     *
+     * <p>
+     * The metrics describe the size of the largest potential area the window might occupy with
+     * {@link LayoutParams#MATCH_PARENT MATCH_PARENT} width and height, and the {@link WindowInsets}
+     * such a window would have.
+     * <p>
      * Note that this might still be smaller than the size of the physical display if certain areas
      * of the display are not available to windows created in this {@link Context}.
-     * <p>
+     *
      * For example, given that there's a device which have a multi-task mode to limit activities
      * to a half screen. In this case, {@link #getMaximumWindowMetrics()} reports the bounds of
-     * the half screen which the activity is located, while {@link Display#getRealSize(Point)} still
-     * reports the bounds of the whole physical display.
-     *
-     * Despite this, {@link #getMaximumWindowMetrics()} and {@link Display#getRealSize(Point)}
-     * reports the same bounds in general.
+     * the half screen which the activity is located.
+     * <p>
+     * <b>Generally {@link #getCurrentWindowMetrics()} is the correct API to use</b> for choosing
+     * UI layouts. {@link #getMaximumWindowMetrics()} are only appropriate when the application
+     * needs to know the largest possible size it can occupy if the user expands/maximizes it on the
+     * screen.
      *
      * @see #getCurrentWindowMetrics()
      * @see WindowMetrics