A display cutout is an area on some devices that extends into the display surface. It allows for an edge-to-edge experience while providing space for important sensors on the front of the device.
Android supports display cutouts on devices running Android 9 (API level 28) and higher. However, device manufacturers can also choose to support display cutouts on devices running Android 8.1 or lower.
This topic describes how to implement support for devices with cutouts, including how to work with the cutout area--that is, the edge-to-edge rectangle on the display surface that contains the cutout.
1 Display cutout.
Choose how your app handles cutout areas
If you don't want your content to overlap with a cutout area, it’s generally
sufficient to make sure that your content does not overlap with the status bar
and the navigation bar. If you're rendering into the cutout area, you can use
to retrieve a
that contains the safe insets and bounding box for each cutout. These APIs let
you check whether your content overlaps with the cutout so that you can
reposition, if needed.
You can also determine whether content is laid out behind the cutout area. The
window layout attribute controls how your content is drawn in the cutout area.
You can set
layoutInDisplayCutoutMode to one of the following values:
LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT- With this default setting, content renders into the cutout area when displayed in portrait mode, but content is letterboxed when displayed in landscape mode.
LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES- Content renders into the cutout area in both portrait and landscape modes.
LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER- Content never renders into the cutout area.
You can set the cutout mode either programmatically or by setting a style in
your activity. The following example defines a
style that you can use to apply the
LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES attribute to the activity.
<style name="ActivityTheme"> <item name="android:windowLayoutInDisplayCutoutMode"> shortEdges <!-- default, shortEdges, or never --> </item> </style>
The following sections describe the different cutout modes in more detail.
By default, in portrait mode with no special flags set, the status bar on a device with a cutout is resized to be at least as tall as the cutout, and your content displays in the area below. In landscape or fullscreen mode, your app window is letterboxed so that none of your content displays in the cutout area.
Render content in short edge cutout areas
For some content, such as video, photos, maps, and games, rendering in the
cutout area can be a great way to provide a more immersive, edge-to-edge
experience for users. With
the content extends into the cutout area on the short edge of the display in
both portrait and landscape, regardless of whether the system bars are hidden or
visible. When using this mode, be sure that no important content overlaps with
the cutout area.
Here are some examples of
Never render content in the display cutout area
the window is never allowed to overlap with the cutout area.
See the following examples of
Best practices for display cutout support
When working with display cutouts, be sure to consider the following:
- Be mindful of the placement of critical elements of the UI. Do not let the cutout area obscure any important text, controls, or other information.
- Touch sensitivity may be lower in the cutout area. Do not place or extend any interactive elements that require fine touch recognition into the cutout area.
Where possible, use WindowInsetsCompat to retrieve the status bar height and determine the appropriate padding to apply to your content. Avoid hard-coding the status bar height, as this can lead to overlapping or cut-off content.
nevercutout modes if your app needs to transition into and out of immersive mode. Default cutout behavior can cause content in your app to move up and down during transitions, as demonstrated in the following image.
In immersive mode, be careful using window versus screen coordinates, since your app doesn't take up the whole screen when letterboxed. Because of the letterbox, coordinates from the screen origin are no longer the same as coordinates from the window origin. You can transform screen coordinates to the view’s coordinates as needed by using getLocationOnScreen(). The following image shows how coordinates differ when content is letterboxed:
Test how your content renders
Be sure to test all of your app's screens and experiences. Test on devices with different types of cutouts, if possible. If you don't have a device with a cutout, you can simulate some common cutout configurations on any device or emulator running Android 9 or higher by doing the following:
- Enable developer options.
- In the Developer options screen, scroll down to the Drawing section, and select Simulate a display with a cutout.
- Select the cutout type.