DisplayCutout: Add clarifying images to LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES
Fixes: 76462084
Test: make doc-comment-check-docs, open $ANDROID_BUILD_TOP/out/target/common/docs/doc-comment-check/reference/android/view/WindowManager.LayoutParams.html, navigate to LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES
Change-Id: I8a9df979cbb062896fa874a163414a4f8a095b21
diff --git a/core/java/android/view/WindowManager.java b/core/java/android/view/WindowManager.java
index abc19d0..a6b7e0b 100644
--- a/core/java/android/view/WindowManager.java
+++ b/core/java/android/view/WindowManager.java
@@ -2279,6 +2279,35 @@
* The window must make sure that no important content overlaps with the
* {@link DisplayCutout}.
*
+ * <p>
+ * In this mode, the window extends under cutouts on the short edge of the display in both
+ * portrait and landscape, regardless of whether the window is hiding the system bars:<br/>
+ * <img src="{@docRoot}reference/android/images/display_cutout/short_edge/fullscreen_top_no_letterbox.png"
+ * height="720"
+ * alt="Screenshot of a fullscreen activity on a display with a cutout at the top edge in
+ * portrait, no letterbox is applied."/>
+ *
+ * <img src="{@docRoot}reference/android/images/display_cutout/short_edge/landscape_top_no_letterbox.png"
+ * width="720"
+ * alt="Screenshot of an activity on a display with a cutout at the top edge in landscape,
+ * no letterbox is applied."/>
+ *
+ * <p>
+ * A cutout in the corner is considered to be on the short edge: <br/>
+ * <img src="{@docRoot}reference/android/images/display_cutout/short_edge/fullscreen_corner_no_letterbox.png"
+ * height="720"
+ * alt="Screenshot of a fullscreen activity on a display with a cutout in the corner in
+ * portrait, no letterbox is applied."/>
+ *
+ * <p>
+ * On the other hand, should the cutout be on the long edge of the display, a letterbox will
+ * be applied such that the window does not extend into the cutout on either long edge:
+ * <br/>
+ * <img src="{@docRoot}reference/android/images/display_cutout/short_edge/portrait_side_letterbox.png"
+ * height="720"
+ * alt="Screenshot of an activity on a display with a cutout on the long edge in portrait,
+ * letterbox is applied."/>
+ *
* @see DisplayCutout
* @see WindowInsets#getDisplayCutout()
*/
diff --git a/docs/html/reference/images/display_cutout/default_mode/fullscreen_letterbox.png b/docs/html/reference/images/display_cutout/default_mode/fullscreen_letterbox.png
new file mode 100644
index 0000000..8602290
--- /dev/null
+++ b/docs/html/reference/images/display_cutout/default_mode/fullscreen_letterbox.png
Binary files differ
diff --git a/docs/html/reference/images/display_cutout/default_mode/landscape.png b/docs/html/reference/images/display_cutout/default_mode/landscape.png
new file mode 100644
index 0000000..be112f4
--- /dev/null
+++ b/docs/html/reference/images/display_cutout/default_mode/landscape.png
Binary files differ
diff --git a/docs/html/reference/images/display_cutout/default_mode/landscape_corner.png b/docs/html/reference/images/display_cutout/default_mode/landscape_corner.png
new file mode 100644
index 0000000..7aa92b4
--- /dev/null
+++ b/docs/html/reference/images/display_cutout/default_mode/landscape_corner.png
Binary files differ
diff --git a/docs/html/reference/images/display_cutout/default_mode/portrait.png b/docs/html/reference/images/display_cutout/default_mode/portrait.png
new file mode 100644
index 0000000..6392ad5
--- /dev/null
+++ b/docs/html/reference/images/display_cutout/default_mode/portrait.png
Binary files differ
diff --git a/docs/html/reference/images/display_cutout/default_mode/portrait_corner.png b/docs/html/reference/images/display_cutout/default_mode/portrait_corner.png
new file mode 100644
index 0000000..dc8e6d0
--- /dev/null
+++ b/docs/html/reference/images/display_cutout/default_mode/portrait_corner.png
Binary files differ
diff --git a/docs/html/reference/images/display_cutout/never_mode/landscape.png b/docs/html/reference/images/display_cutout/never_mode/landscape.png
new file mode 100644
index 0000000..be112f4
--- /dev/null
+++ b/docs/html/reference/images/display_cutout/never_mode/landscape.png
Binary files differ
diff --git a/docs/html/reference/images/display_cutout/never_mode/portrait_top_letterbox.png b/docs/html/reference/images/display_cutout/never_mode/portrait_top_letterbox.png
new file mode 100644
index 0000000..fc7dfcf
--- /dev/null
+++ b/docs/html/reference/images/display_cutout/never_mode/portrait_top_letterbox.png
Binary files differ
diff --git a/docs/html/reference/images/display_cutout/short_edge/fullscreen_corner_no_letterbox.png b/docs/html/reference/images/display_cutout/short_edge/fullscreen_corner_no_letterbox.png
new file mode 100644
index 0000000..09f942d
--- /dev/null
+++ b/docs/html/reference/images/display_cutout/short_edge/fullscreen_corner_no_letterbox.png
Binary files differ
diff --git a/docs/html/reference/images/display_cutout/short_edge/fullscreen_side_letterbox.png b/docs/html/reference/images/display_cutout/short_edge/fullscreen_side_letterbox.png
new file mode 100644
index 0000000..9aafc58
--- /dev/null
+++ b/docs/html/reference/images/display_cutout/short_edge/fullscreen_side_letterbox.png
Binary files differ
diff --git a/docs/html/reference/images/display_cutout/short_edge/fullscreen_top_no_letterbox.png b/docs/html/reference/images/display_cutout/short_edge/fullscreen_top_no_letterbox.png
new file mode 100644
index 0000000..75e913b
--- /dev/null
+++ b/docs/html/reference/images/display_cutout/short_edge/fullscreen_top_no_letterbox.png
Binary files differ
diff --git a/docs/html/reference/images/display_cutout/short_edge/landscape_corner.png b/docs/html/reference/images/display_cutout/short_edge/landscape_corner.png
new file mode 100644
index 0000000..d9e0f99
--- /dev/null
+++ b/docs/html/reference/images/display_cutout/short_edge/landscape_corner.png
Binary files differ
diff --git a/docs/html/reference/images/display_cutout/short_edge/landscape_sideboxed.png b/docs/html/reference/images/display_cutout/short_edge/landscape_sideboxed.png
new file mode 100644
index 0000000..9d44493
--- /dev/null
+++ b/docs/html/reference/images/display_cutout/short_edge/landscape_sideboxed.png
Binary files differ
diff --git a/docs/html/reference/images/display_cutout/short_edge/landscape_top_no_letterbox.png b/docs/html/reference/images/display_cutout/short_edge/landscape_top_no_letterbox.png
new file mode 100644
index 0000000..ac023c5
--- /dev/null
+++ b/docs/html/reference/images/display_cutout/short_edge/landscape_top_no_letterbox.png
Binary files differ
diff --git a/docs/html/reference/images/display_cutout/short_edge/portrait_side_letterbox.png b/docs/html/reference/images/display_cutout/short_edge/portrait_side_letterbox.png
new file mode 100644
index 0000000..50228db
--- /dev/null
+++ b/docs/html/reference/images/display_cutout/short_edge/portrait_side_letterbox.png
Binary files differ
