From 65da12a421398fff576f70ee826e10145a5ccc2a Mon Sep 17 00:00:00 2001
From: Charles Chen <charlesccchen@google.com>
Date: Wed, 19 Feb 2020 10:33:48 +0800
Subject: [PATCH] Update document of WindowMetrics#getSize

Update document to notify that reported size is different between
WindowMetrics#getSize and Display#getSize and provide a sample
code to transform between usages.

Test: build & run
Bug: 128338354
Change-Id: I06aee9aaf903c3864fbb0fe89ea1d3e15506fe1c
(cherry picked from commit 2de0f42d50682ba45f615dadbae3ebba56dd2868)
---
 core/java/android/view/WindowMetrics.java | 25 +++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/core/java/android/view/WindowMetrics.java b/core/java/android/view/WindowMetrics.java
index 8caf5b7fc725c..ab5a06eb99de8 100644
--- a/core/java/android/view/WindowMetrics.java
+++ b/core/java/android/view/WindowMetrics.java
@@ -17,6 +17,7 @@
 package android.view;
 
 import android.annotation.NonNull;
+import android.graphics.Point;
 import android.util.Size;
 
 /**
@@ -40,6 +41,30 @@ public final class WindowMetrics {
 
     /**
      * Returns the size of the window.
+     * <p>
+     * <b>Note that this reports a different size than {@link Display#getSize(Point)}.</b>
+     * This method reports the window size including all system bars area, while
+     * {@link Display#getSize(Point)} reports the area excluding navigation bars and display cutout
+     * areas. The value reported by {@link Display#getSize(Point)} can be obtained by using:
+     * <pre class="prettyprint">
+     * final WindowMetrics metrics = windowManager.getCurrentMetrics();
+     * // Gets all excluding insets
+     * final WindowInsets windowInsets = metrics.getWindowInsets();
+     * Insets insets = windowInsets.getInsets(WindowInsets.Type.navigationBars());
+     * final DisplayCutout cutout = windowInsets.getCutout();
+     * if (cutout != null) {
+     *     final Insets cutoutSafeInsets = Insets.of(cutout.getSafeInsetsLeft(), ...);
+     *     insets = insets.max(insets, cutoutSafeInsets);
+     * }
+     *
+     * int insetsWidth = insets.right + insets.left;
+     * int insetsHeight = insets.top + insets.bottom;
+     *
+     * // Legacy size that Display#getSize reports
+     * final Size legacySize = new Size(metrics.getWidth() - insetsWidth,
+     *         metrics.getHeight() - insetsHeight);
+     * </pre>
+     * </p>
      *
      * @return window size in pixel.
      */