Merge "DisplayCutout: Fix attrs.xml javadoc" into pi-dev

core/java/android/view/WindowManager.java

@@ -2220,7 +2220,7 @@ public interface WindowManager extends ViewManager {
         @IntDef(
                 flag = true,
                 value = {LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT,
-                        LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS,
+                        LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES,
                         LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER})
         @interface LayoutInDisplayCutoutMode {}
 
@@ -2231,10 +2231,11 @@ public interface WindowManager extends ViewManager {
          * Defaults to {@link #LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT}.
          *
          * @see #LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT
-         * @see #LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS
+         * @see #LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES
          * @see #LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER
          * @see DisplayCutout
-         * @see android.R.attr#layoutInDisplayCutoutMode
+         * @see android.R.attr#windowLayoutInDisplayCutoutMode
+         *         android:windowLayoutInDisplayCutoutMode
          */
         @LayoutInDisplayCutoutMode
         public int layoutInDisplayCutoutMode = LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT;
@@ -2245,10 +2246,10 @@ public interface WindowManager extends ViewManager {
          * laid out such that it does not overlap with the {@link DisplayCutout} area.
          *
          * <p>
-         * In practice, this means that if the window did not set FLAG_FULLSCREEN or
+         * In practice, this means that if the window did not set {@link #FLAG_FULLSCREEN} or
-         * SYSTEM_UI_FLAG_FULLSCREEN, it can extend into the cutout area in portrait if the cutout
+         * {@link View#SYSTEM_UI_FLAG_FULLSCREEN}, it can extend into the cutout area in portrait
-         * is at the top edge. Similarly for SYSTEM_UI_FLAG_HIDE_NAVIGATION and a cutout at the
+         * if the cutout is at the top edge. Similarly for
-         * bottom of the screen.
+         * {@link View#SYSTEM_UI_FLAG_HIDE_NAVIGATION} and a cutout at the bottom of the screen.
          * Otherwise (i.e. fullscreen or landscape) it is laid out such that it does not overlap the
          * cutout area.
          *
@@ -2258,6 +2259,9 @@ public interface WindowManager extends ViewManager {
          *
          * @see DisplayCutout
          * @see WindowInsets
+         * @see #layoutInDisplayCutoutMode
+         * @see android.R.attr#windowLayoutInDisplayCutoutMode
+         *         android:windowLayoutInDisplayCutoutMode
          */
         public static final int LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT = 0;
 
@@ -2281,6 +2285,9 @@ public interface WindowManager extends ViewManager {
          *
          * @see DisplayCutout
          * @see WindowInsets#getDisplayCutout()
+         * @see #layoutInDisplayCutoutMode
+         * @see android.R.attr#windowLayoutInDisplayCutoutMode
+         *         android:windowLayoutInDisplayCutoutMode
          */
         public static final int LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES = 1;
 
@@ -2288,12 +2295,14 @@ public interface WindowManager extends ViewManager {
          * The window is never allowed to overlap with the DisplayCutout area.
          *
          * <p>
-         * This should be used with windows that transiently set SYSTEM_UI_FLAG_FULLSCREEN to
+         * This should be used with windows that transiently set
-         * avoid a relayout of the window when the flag is set or cleared.
+         * {@link View#SYSTEM_UI_FLAG_FULLSCREEN} or {@link View#SYSTEM_UI_FLAG_HIDE_NAVIGATION}
+         * to avoid a relayout of the window when the respective flag is set or cleared.
          *
          * @see DisplayCutout
-         * @see View#SYSTEM_UI_FLAG_FULLSCREEN SYSTEM_UI_FLAG_FULLSCREEN
+         * @see #layoutInDisplayCutoutMode
-         * @see View#SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
+         * @see android.R.attr#windowLayoutInDisplayCutoutMode
+         *         android:windowLayoutInDisplayCutoutMode
          */
         public static final int LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER = 2;
 

core/res/res/values/attrs.xml

@@ -2123,44 +2123,48 @@
         <!-- Controls how the window is laid out if there is a {@code DisplayCutout}.
         <p>
         Defaults to {@code default}.
-
+        <p>
-        @see android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT
+        See also
-        @see android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES
+        {@link android.view.WindowManager.LayoutParams#layoutInDisplayCutoutMode
-        @see android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER
+                WindowManager.LayoutParams.layoutInDisplayCutoutMode},
-        @see android.view.DisplayCutout
+        {@link android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT},
-        @see android.R.attr#layoutInDisplayCutoutMode -->
+        {@link android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES},
+        {@link android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER},
+        and {@link android.view.DisplayCutout DisplayCutout}
+        -->
         <attr name="windowLayoutInDisplayCutoutMode">
-            <!-- The window is allowed to extend into the {@code DisplayCutout} area, only if the
+            <!-- <p>
-            {@code DisplayCutout} is fully contained within a system bar. Otherwise, the window is
+            The window is allowed to extend into the <code>DisplayCutout</code> area, only if
-            laid out such that it does not overlap with the {@code DisplayCutout} area.
+            the <code>DisplayCutout</code> is fully contained within a system bar. Otherwise, the
-
+            window is laid out such that it does not overlap with the <code>DisplayCutout</code>
-            @see android.view.DisplayCutout
+            area.
-            @see android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT
+            <p>
+            Corresponds to <code>LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT</code>.
             -->
             <enum name="default" value="0" />
-            <!--
+            <!-- <p>
-            The window is always allowed to extend into the {@code DisplayCutout} areas on the short
+            The window is always allowed to extend into the <code>DisplayCutout</code> areas on the
-            edges of the screen even if fullscreen or in landscape.
+            short edges of the screen even if fullscreen or in landscape.
-            The window will never extend into a {@link DisplayCutout} area on the long edges of the
+            The window will never extend into a <code>DisplayCutout</code> area on the long edges of
-            screen.
+            the screen.
             <p>
             The window must make sure that no important content overlaps with the
-            {@link DisplayCutout}.
+            <code>DisplayCutout</code>.
-
+            <p>
-            @see android.view.DisplayCutout
+            Corresponds to <code>LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES</code>.
-            @see android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES
             -->
             <enum name="shortEdges" value="1" />
-            <!-- Use {@code shortEdges} instead. This is temporarily here to unblock pushing the SDK
+            <!-- Use <code>shortEdges</code> instead. This is temporarily here to unblock pushing
-                 until all usages have been migrated to {@code shortEdges} -->
+                 the SDK until all usages have been migrated to <code>shortEdges</code> -->
             <enum name="always" value="1" />
-            <!-- The window is never allowed to overlap with the DisplayCutout area.
+            <!-- <p>
+            The window is never allowed to overlap with the <code>DisplayCutout</code> area.
             <p>
-            This should be used with windows that transiently set {@code SYSTEM_UI_FLAG_FULLSCREEN}
+            This should be used with windows that transiently set
-            to avoid a relayout of the window when the flag is set or cleared.
+            <code>SYSTEM_UI_FLAG_FULLSCREEN</code> to avoid a relayout of the window when the
-
+            flag is set or cleared.
-            @see android.view.DisplayCutout
+            <p>
-            @see android.view.WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER
+            Corresponds to <code>LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER</code>.
             -->
             <enum name="never" value="2" />
         </attr>