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
diff --git a/core/java/android/view/WindowMetrics.java b/core/java/android/view/WindowMetrics.java
index 8caf5b7..ab5a06e 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 @@
/**
* 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.
*/
