WindowInsets: clarify displayCutout javadoc

Fixes: 152729752
Change-Id: I4d24aaede44d80dae8d6e6d95a7d15d5f33a04c9

1 files changed, 13 insertions, 1 deletions

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()