From e978d75237bd0c3189c17ffd9686ce421ca488d2 Mon Sep 17 00:00:00 2001
From: Adrian Roos <roosa@google.com>
Date: Tue, 14 Apr 2020 08:58:17 +0000
Subject: WindowInsets: clarify displayCutout javadoc

Fixes: 152729752
Change-Id: I4d24aaede44d80dae8d6e6d95a7d15d5f33a04c9
---
 core/java/android/view/WindowInsets.java | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

(limited to 'core/java/android')

diff --git a/core/java/android/view/WindowInsets.java b/core/java/android/view/WindowInsets.java
index ca3dd04fd756..aad1c60d7b7e 100644
--- a/core/java/android/view/WindowInsets.java
+++ b/core/java/android/view/WindowInsets.java
@@ -473,6 +473,12 @@ public final class WindowInsets {
     /**
      * Returns the display cutout if there is one.
      *
+     * <p>Note: the display cutout will already be {@link #consumeDisplayCutout consumed} during
+     * dispatch to {@link View#onApplyWindowInsets}, unless the window has requested a
+     * {@link WindowManager.LayoutParams#layoutInDisplayCutoutMode} other than
+     * {@link WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER never} or
+     * {@link WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT default}.
+     *
      * @return the display cutout or null if there is none
      * @see DisplayCutout
      */
@@ -1424,7 +1430,13 @@ public final class WindowInsets {
         /**
          * Returns an insets type representing the area that used by {@link DisplayCutout}.
          *
-         * <p>This is equivalent to the safe insets on {@link #getDisplayCutout()}.</p>
+         * <p>This is equivalent to the safe insets on {@link #getDisplayCutout()}.
+         *
+         * <p>Note: During dispatch to {@link View#onApplyWindowInsets}, if the window is using
+         * the {@link WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT default}
+         * {@link WindowManager.LayoutParams#layoutInDisplayCutoutMode}, {@link #getDisplayCutout()}
+         * will return {@code null} even if the window overlaps a display cutout area, in which case
+         * the {@link #displayCutout() displayCutout() inset} will still report the accurate value.
          *
          * @see DisplayCutout#getSafeInsetLeft()
          * @see DisplayCutout#getSafeInsetTop()
-- 
cgit v1.2.3