Multi-window support

Android 7.0 adds support for displaying more than one app at the same time. On handheld devices, two apps can run side-by-side or one-above-the-other in split-screen mode. On TV devices, apps can use picture-in-picture mode to continue video playback while users are interacting with another app.

If your app targets Android 7.0 (API level 24) or higher, you can configure how your app handles multi-window display. For example, you can specify your activity's minimum allowable dimensions. You can also disable multi-window display for your app, ensuring that the system only shows your app in full-screen mode.


Android allows several apps to share the screen at once. For example, a user could split the screen, viewing a web page on the left side while composing an email on the right side. The user experience depends on the version of the Android OS and the kind of device:

  • Handheld devices running Android 7.0 offer split-screen mode. In this mode, the system fills the screen with two apps, showing them either side-by-side or one-above-the-other. The user can drag the dividing line separating the two to make one app larger and the other smaller.
  • Starting with Android 8.0, apps can put themselves in picture-in-picture mode, allowing them to continue showing content while the user browses or interacts with other apps.
  • Manufacturers of larger devices can choose to enable freeform mode, in which the user can freely resize each activity. If the manufacturer enables this feature, the device offers freeform mode in addition to split-screen mode.

Figure 1. Two apps running side-by-side in split-screen mode.

The user can switch into multi-window mode in the following ways:

  • If the user opens the Overview screen and performs a long press on an activity title, they can drag that activity to a highlighted portion of the screen to put the activity in multi-window mode.
  • If the user performs a long press on the Overview button, the device puts the current activity in multi-window mode, and opens the Overview screen to let the user choose another activity to share the screen.

Users can drag and drop data from one activity to another while the activities are sharing the screen.

Multi-window lifecycle

Multi-window mode does not change the activity lifecycle.

In multi-window mode, only the activity the user has most recently interacted with is active at a given time. This activity is considered topmost, and is the only activity in the RESUMED state. All other visible activities are STARTED but are not RESUMED. However, the system gives these visible-but-not-resumed activities higher priority than activities that are not visible. If the user interacts with one of the visible activities, that activity is resumed, and the previously topmost activity enters the STARTED state.

Note: In multi-window mode, an app might not be in the RESUMED state even though it is visible to the user. An app might need to continue its operation while it is not topmost. For example, a video-playing app in this state should continue showing its video. For this reason, we recommend that activities that play video not pause video playback in response to the ON_PAUSE lifecycle event. Instead, the activity should begin playback in response to ON_START, and pause playback in response to ON_STOP. If you handle the lifecycle events directly instead of using the Lifecycle package, pause video playback in your onStop() handler, and resume playback in onStart().

When the user puts an app into multi-window mode, the system notifies the activity of a configuration change, as specified in Handling Configuration Changes. This also happens when the user resizes the app, or puts the app back into full-screen mode. Essentially, this change has the same activity-lifecycle implications as when the system notifies the app that the device has switched from portrait to landscape mode, except that the device dimensions are changed instead of just being swapped. As discussed in Handling Configuration Changes, your activity can handle the configuration change itself, or it can allow the system to destroy the activity and recreate it with the new dimensions.

If the user is resizing a window and makes it larger in either dimension, the system resizes the activity to match the user action and issues configuration changes as needed. If the app lags behind in drawing in newly-exposed areas, the system temporarily fills those areas with the color specified by the windowBackground attribute or by the default windowBackgroundFallback style attribute.

When the app is in multi-window mode the resumed state will depend on the Android version of the device.

  • In Android 9 (API level 28) and lower, only the activity with focus is in the RESUMED state; all others are PAUSED. When there are multiple activities within a single app process, the activity with the highest Z-order is RESUMED and the others are PAUSED.
  • In Android 10 (API level 29) and higher, all visible, top-focusable Activities are RESUMED.

multi-resume documentation for more information.


Being able to run multiple windows is one of the benefits of large screens. In the past, having two apps side by side was common in some devices. The technology has improved to the point where three or more apps can run on the screen at the same time, and also share content between themselves:

If an app doesn't properly support multi-window, it can set resizeableActivity=false. For more information, read the Multi-Window guide.

With multi-window becoming more common, consider supporting drag and drop in your app.


When running on Android 9.0 and earlier, only the app in focus is in the resumed state. Any other visible Activities are paused. This can create problems if apps close resources or stop playing content when they pause.

In Android 10, this behavior changed so that all Activities remain in the resumed state when the device is in multi-window mode. This is called multi-resume. Note that an activity can be paused if there’s a transparent activity on top, or the Activity is not focusable (e.g. picture-in-picture mode). It’s also possible that no activities have focus at a given time, for example, if the Notification drawer is opened. OnStop keeps working as usual. It will be called any time the activity is taken off the screen.

Multi-resume is also available on select devices running Android 9.0. To opt-in to multi-resume on those devices, you can add the following manifest meta-data:

    android:name="android.allow_multiple_resumed_activities" android:value="true" />

To verify that a given device supports this manifest meta-data, refer to the device specifications.

Exclusive resources access

To help support the multi-resume feature, there’s a new lifecycle callback, Activity#onTopResumedActivityChanged().

This method is invoked when an activity gains or loses the top resumed Activity position. This is important to know when an activity uses a shared single-user resource, such as the microphone or camera.

override fun onTopResumedActivityChanged(topResumed: Boolean) {
    if (topResumed) {
        // Top resumed activity
        // Can be a signal to re-acquire exclusive resources
    } else {
        // No longer the top resumed activity

Note that an app can lose resources for several other reasons, such as removing a shared piece of hardware.

In any case, an app should gracefully handle resource loss events and state changes that affect available resources.

For apps that use a camera it’s recommended to use the method CameraManager.AvailabilityCallback#onCameraAccessPrioritiesChanged() as a hint that it might be a good time to try to get access to the camera. This method is available in Android 10 (API level 29) and higher.

Remember that resizeableActivity=false is not a guarantee of exclusive camera access, since other camera-using apps can be opened on other displays.

Camera in multi-window mode.

Your app does not necessary have to release the camera when it loses focus. For example, you might want to continue camera preview while the user interacts with the newly focused topmost resumed app. It's fine for your app to keep running the camera when it’s not the topmost resumed app but it has to handle the disconnect case properly. When the topmost resumed app wants to use the camera it can open it, and your app will lose access. Your app can re-open the camera when it gets the focus back.

After an app receives a CameraDevice.StateCallback#onDisconnected() callback, subsequent calls on the camera device will throw a CameraAccessException.


In the future, you might see foldable phones that support more than one screen or display at a time. Handling this configuration is similar to how developers work with projected screens today on Chrome OS.

Android 10 (API level 29) and higher supports activities on secondary displays. If an activity is running on a device with multiple displays, users can move the activity from one display to another. Multi-resume applies to multi-screen scenarios as well. Several activities can receive user input at the same time.

An app can specify which display it should run on when it launches, or when it creates another activity. This behavior depends on the activity launch mode defined in the manifest file, and in the intent flags and options set by the entity launching the activity. See ActivityOptions for more details.

As with folding transitions, when an activity moves to a secondary display, it can go through a context update, window resize, and configuration and resource changes. If the activity handles the configuration change, it will be notified in onConfigurationChanged(). If not, it will be relaunched.

An activity should check the current display in onCreate and onConfigurationChanged if handled. Make sure to update the resources and layouts when the display changes.

If the selected launch mode for an activity allows multiple instances, remember that launching on a secondary screen can create a new instance of the activity. Both activities will be resumed at the same time.

Multiple instances of an Activity in multiple displays.

You may also want to read about the existing multi-display APIs that were introduced in Android 8.0.

Display cutouts

Foldable devices might have different cutout geometry when folded and unfolded. To avoid cutout issues read Best practices for display cutout.

Activity vs application context

Using the right context is crucial in multi-display. When accessing resources, the activity context (which is displayed) is different from the application context (which is not).

The activity context contains information about the display and is always adjusted for the display area on which it appears. This allows you to get the correct information about the density or window metrics your app currently has. You should always be using the activity context (or another UI-based context) to get information about the current window or display. This also affects some system APIs that use information from the context (like Toast).

The activity window configuration and parent display define resources and context. To get the current display use:

val activityDisplay = activity.display

To get the current activity window metrics use:

val windowMetrics = activity.windowManager.getCurrentWindowMetrics()

To get the maximum window metrics for the current system configuration use:

val maximumWindowMetrics = activity.windowManager.getMaximumWindowMetrics()

The maximum window metrics is great information for making calculations, layout choices, or determining the size of resources to fetch ahead of time. Having this available in onCreate() allows you to make these decisions before the first layout pass. These should not be used for laying out specific layout elements and instead should use information from the Configuration object.

Using secondary screens

You can get the available displays from the DisplayManager system service:

val dm = getSystemService(Context.DISPLAY_SERVICE) as DisplayManager
val displays = dm.displays

Use the Display class to get information about a particular display, such as checking the flags to see if a display is secure.

However, do not assume that the display size is going to be the constant size your application will be placed in. Remember that in multi-window mode, your application will be on a subset of the display.

To determine if an activity can launch on a display:

activityManager.isActivityStartAllowedOnDisplay(context, displayId, intent)

And to launch an activity on a display:

val options = ActivityOptions.makeBasic()
options.launchDisplayId = targetDisplay.displayId
startActivity(intent, options.toBundle())

Multi-display support

Android already supports Software keyboards, Wallpapers, and Launchers.

Software keyboard

A keyboard can be shown on a secondary screen if the display is configured to support system decorations. The input method editor will automatically show up if a text field requests input on that display.

Keyboard on a secondary display.


In Android 10 (API level 29) and higher, secondary screens can have wallpaper. The framework creates a separate instance of WallpaperService.Engine for each display. Make sure the surface of each engine is drawn independently. Developers can load assets using the display context in WallpaperService.Engine#getDisplayContext(). Also, make sure your WallpaperInfo.xml file sets android:supportsMultipleDisplays="true".

Wallpapers on phone and secondary display.


There is a new intent filter category SECONDARY_HOME to provide a dedicated activity for secondary screens. Instances of this activity are used on all displays that support system decorations, one per each display.

        <category android:name="android.intent.category.SECONDARY_HOME" />

The activity must have a launch mode that does not prevent multiple instances and can adapt to different screen sizes. The launch mode cannot be singleInstance or singleTask.

As example, the AOSP implementation of Launcher3 supports a SECONDARY_HOME activity.

Material Design Launcher on phone.

Material Design Launcher on a secondary display.

Configuring your app for multi-window Mode

If your app targets API level 24 or higher, you can configure how and whether your app's activities support multi-window display. You can set attributes in your manifest to control both size and layout. A root activity's attribute settings apply to all activities within its task stack. For example, if the root activity has android:resizeableActivity set to true, then all activities in the task stack are resizable.

Note: If you build a multi-orientation app that targets API level 23 or lower, and the user uses the app in multi-window mode, the system forcibly resizes the app. The system presents a dialog box warning the user that the app may behave unexpectedly. The system does not resize fixed-orientation apps; if the user attempts to open a fixed-orientation app under multi-window mode, the app takes over the whole screen.

On some larger devices, such as Chromebooks, your app might run in a resizable window even if you specify android:resizeableActivity=”false”. If this will break your app, you can use filters to restrict your app's availability on such devices.


Set this attribute in your manifest's <activity> or <application> element to enable or disable multi-window display:

android:resizeableActivity=["true" | "false"]

If this attribute is set to true, the activity can be launched in split-screen and freeform modes. If the attribute is set to false, the activity does not support multi-window mode. If this value is false, and the user attempts to launch the activity in multi-window mode, the activity takes over the full screen.

If your app targets API level 24, but you do not specify a value for this attribute, the attribute's value defaults to true.


Set this attribute in your manifest's <activity> node to indicate whether the activity supports Picture-in-Picture display. This attribute is ignored if android:resizeableActivity is false.

android:supportsPictureInPicture=["true" | "false"]

Layout attributes

With Android 7.0, the <layout> manifest element supports several attributes that affect how an activity behaves in multi-window mode:

Default width of the activity when launched in freeform mode.
Default height of the activity when launched in freeform mode.
Initial placement of the activity when launched in freeform mode. See the Gravity reference for suitable values.
android:minHeight, android:minWidth
Minimum height and minimum width for the activity in both split-screen and freeform modes. If the user moves the divider in split-screen mode to make an activity smaller than the specified minimum, the system crops the activity to the size the user requests.

For example, the following code shows how to specify an activity's default size and location, and its minimum size, when the activity is displayed in freeform mode:

<activity android:name=".MyActivity">
    <layout android:defaultHeight="500dp"
          android:minWidth="300dp" />

Handle configuration changes correctly

If you're handling multi-window configuration changes yourself, such as what happens when a user resizes a window, add the android:configChanges attribute to your manifest with at least the following values:


After adding android:configChanges, your Activity and Fragments receive a callback to onConfigurationChanged() instead of being destroyed and recreated. You can then manually update your views, reload resources, and perform other operations as needed.

Running your app in multi-window mode

Beginning with Android 7.0, the system offers functionality to support apps that can run in multi-window mode.

Disabled features in multi-window mode

Certain features are disabled or ignored when a device is in multi-window mode, because they don’t make sense for an activity which may be sharing the device screen with other activities or apps. Such features include:

  • Some System UI customization options are disabled; for example, apps cannot hide the status bar if they are not running in full-screen mode.
  • The system ignores changes to the android:screenOrientation attribute.

Multi-window change notification and querying

Activity offers the following methods to support multi-window display.

Call to find out if the activity is in multi-window mode.
Call to find out if the activity is in picture-in-picture mode.

Note: Picture-in-picture mode is a special case of multi-window mode. If myActivity.isInPictureInPictureMode() returns true, then myActivity.isInMultiWindowMode() also returns true.

The system calls this method whenever the activity goes into or out of multi-window mode. The system passes the method a value of true if the activity is entering multi-window mode, and false if the activity is leaving multi-window mode.
The system calls this method whenever the activity goes into or out of picture-in-picture mode. The system passes the method a value of true if the activity is entering picture-in-picture mode, and false if the activity is leaving picture-in-picture mode.

The Fragment class exposes versions of many of these methods, for example Fragment.onMultiWindowModeChanged().

Entering picture-in-picture mode

To put an activity in picture-in-picture mode, call Activity.enterPictureInPictureMode(). This method has no effect if the device does not support picture-in-picture mode. For more information, see the Picture-in-Picture documentation.

Launch new activities in multi-window mode

When you launch a new activity, you can indicate that the new activity should be displayed adjacent to the current one if possible. To do this use the intent flag FLAG_ACTIVITY_LAUNCH_ADJACENT. This flag tells the system to try to create the new activity next to the activity that launched it, so the two activities share the screen. The system makes a best effort to do this, but it is not guaranteed to happen.

If a device is in freeform mode and you are launching a new activity, you can specify the new activity's dimensions and screen location by calling ActivityOptions.setLaunchBounds(). This method has no effect if the device is not in multi-window mode.

Note: If you launch an activity within a task stack, the activity replaces the activity on the screen, inheriting all of its multi-window properties. If you want to launch the new activity as a separate window in multi-window mode, you must launch it in a new task stack.

Support drag and drop

Users can drag and drop data from one activity to another while the two activities are sharing the screen. (Prior to Android 7.0, users could only drag and drop data within a single activity.) To quickly add support for accepting dropped content in editable TextView widgets, see OnReceiveContentListener in Jetpack. For comprehensive drag-and-drop support, such as enabling the dragging of content from your app, see the drag and drop topic.

Token object responsible for specifying the permissions granted to the app that receives a drop.
Alias for View.startDrag(). To enable cross-activity drag and drop, pass the flag DRAG_FLAG_GLOBAL. If you need to give URI permissions to the recipient activity, pass the flags DRAG_FLAG_GLOBAL_URI_READ or DRAG_FLAG_GLOBAL_URI_WRITE, as appropriate.
Cancels a drag operation currently in progress. Can only be called by the app that originated the drag operation.
Replaces the drag shadow for a drag operation currently in progress. Can only be called by the app that originated the drag operation.
Requests the permissions for the content URIs passed with the ClipData contained in a DragEvent.
Releases the permissions needed to access the data at the content URI given in the ClipData. If you don't call this method, the permissions are released automatically when the containing activity is destroyed.


Each root activity has its own task, which runs on a separate process and is displayed in its own window. To launch a new instance of your app in a separate window, you can start new activities with the FLAG_ACTIVITY_NEW_TASK flag. You can combine this with some of the multi-window attributes to request a specific location for the new window. For example, a shopping app can display multiple windows to compare products.

Don't confuse multi-instance with a multi-panel layout, such as a list/detail layout that uses SlidingPaneLayout. This runs inside a single window.

Note that when multiple instances are running in separate windows on a foldable device, one or more instances might be sent to the background if the pose changes. For example, assume a device is unfolded and has two app instances running in two windows on either side of the fold. If the device is folded, one of the instances might be terminated instead of trying to fit the windows for both instances on a smaller screen.

Testing Your app's multi-window support

Whether or not your app targets API level 24 or higher, you should verify how it behaves in multi-window mode in case a user tries to launch it in multi-window mode on a device running Android 7.0 or higher.

Configuring a test device

If a device runs Android 7.0 or higher, it automatically supports split-screen mode.

If your app targets API level 23 or lower

If your app targets API level 23 or lower and the user attempts to use the app in multi-window mode, the system forcibly resizes the app unless the app declares a fixed orientation.

If your app does not declare a fixed orientation, you should launch your app on a device running Android 7.0 or higher and attempt to put the app in split-screen mode. Verify that the user experience is acceptable when the app is forcibly resized.

If the app declares a fixed orientation, you should attempt to put the app in multi-window mode. Verify that when you do so, the app remains in full-screen mode.

If you support multi-window mode

If your app targets API level 24 or higher and does not disable multi-window support, verify the following behavior under both split-screen and freeform modes.

  • Launch the app in full-screen mode, then switch to multi-window mode by long-pressing the Overview button. Verify that the app switches properly.
  • Launch the app directly in multi-window mode, and verify that the app launches properly. You can launch an app in multi-window mode by pressing the Overview button, then long-pressing the title bar of your app and dragging it to one of the highlighted areas on the screen.
  • Resize your app in split-screen mode by dragging the divider line. Verify that the app resizes without crashing, and that necessary UI elements are visible.
  • If you have specified minimum dimensions for your app, attempt to resize the app below those dimensions. Verify that you cannot resize the app to be smaller than the specified minimum.
  • Through all tests, verify that your app's performance is acceptable. For example, verify that there is not too long a lag to update the UI after the app is resized.

Testing checklist

To verify your app's performance in multi-window mode, try the following operations. You should try these operations in both split-screen and multi-window mode, except where otherwise noted.

  • Enter and leave multi-window mode.
  • Switch from your app to another app, and verify that the app behaves properly while it is visible but not active. For example, if your app is playing video, verify that the video continues to play while the user is interacting with another app.
  • In split-screen mode, try moving the dividing bar to make your app both larger and smaller. Try these operations in both side-by-side and one-above-the-other configurations. Verify that the app does not crash, essential functionality is visible, and the resize operation doesn't take too long.
  • Perform several resize operations in rapid succession. Verify that your app doesn't crash or leak memory. For information about checking your app's memory usage, use Android Studio's Memory Profiler.
  • Use your app normally in a number of different window configurations, and verify that the app behaves properly. Verify that text is readable, and that UI elements aren't too small to interact with.

If you have disabled multi-window support

If you disabled multi-window support by setting android:resizeableActivity="false", you should launch your app on a device running Android 7.0 or higher and attempt to put the app in freeform and split-screen modes. Verify that when you do so, the app remains in full-screen mode.

For further information about multi-window support in Android, see Five Tips for Preparing for Multi-Window in Android N and the Multi-Window Playground sample app.