If you’ve been digging through What’s New in Android N, you probably stumbled across multi-window support.

With split-screen multi-window, two apps will be visible side-by-side. Excited to see how this works, I know I immediately scanned through the documentation, looking for what new APIs made this sorcery work.

Turns out, there aren’t many new APIs. A few XML attributes for customizing whether you support multi-window at all and a few Activity methods to check whether you are currently in multi-window mode. So where’s the magic? The magic has been there all along.

And by magic, we mean Android’s resource system. One of the most powerful parts of the resource system is the ability to provide alternate resources — change dimensions, layouts, drawables, menus, etc. based on different qualifiers.

Multi-window takes advantage of the resource system by adjusting the configuration based on the size of your window — screen size is the obvious one, but the smallest width (i.e., the minimum of the width or height) and the orientation are also updated when resizing.

This takes us to the first tip.

Pro-tip 1: Use the right Context

Loading the proper resources requires the proper Context. If you’re using the Activity context for inflating your layouts, retrieving resources, etc, then you’re good to go.

However, if you’re using your Application context for anything UI related, you’ll find that the resources that are loaded are blissfully unaware of multi-window. Besides issues with not using your Activity’s theme, you may be loading the wrong resources entirely! Best to keep your UI stuff with the Activity Context.

Pro-tip 2: Handle configuration changes correctly

With the correct context in hand, you’ll be sure to get the right resources given the size of your window (whether it is full screen as before or split between your app and another). The process for reloading those resources is based on how you handle runtime changes.

The default case is that your whole activity is destroyed and recreated, restoring any state you saved in onSaveInstanceState() and reloading all of the resources/layouts. This has the nice property that you know everything is consistent with the new configuration and that every type of configuration is handled.

It should go without saying that each configuration change should be fast and seamless. Make sure you aren’t doing a lot of work in onResume() and consider using loaders to ensure your data survives configuration changes.

You can still handle the configuration change yourself in which case your Activity (and Fragments) will receive a callback to onConfigurationChanged() instead of being destroyed and recreated and you will need to manually update your views, reload resources, etc.

To catch the multi-window related configuration changes, you’d need to add an android:configChanges attribute to your manifest with at least these values:

<activity

android:name=".MyActivity"

android:configChanges="screenSize|smallestScreenSize

|screenLayout|orientation" />

Make sure you’re handling every resource that might be changing (as is your responsibility when you take on handling configuration changes yourself).

This includes reloading resources that might have been considered a constant before. Consider the case where you had a dimension in values and in values-sw600dp. In the non-multi-window world, you’d never switch between these two at runtime as the smallest width would never change (it would always be the smallest width of your device). However, with multi-window, you can and will have to switch between these resources as your app resizes.

Pro-tip 3: Handle all orientations

Remember way back in the intro where we talked about the orientation changing while the window resizes? That’s right: even if the device is in landscape, your app might be in ‘portrait’ orientation.

Turns out: “portrait” really just means the height is greater than the width and “landscape” means the width is greater than the height. So it certainly makes sense, with that definition in mind, that your app could transition from one to the other while being resized.

That also means that transitions between orientations should be as smooth as possible. Quoting the split screen material design specs:

Changing a device’s orientation should not cause the UI to change unexpectedly. For example, an app displaying a video in one of the split screens (in portrait mode) should not begin playback in full-screen if the device rotates to landscape mode.

Note: if you’d still want this type of functionality when your app is fullscreen, you’ll be able to use the inMultiWindowMode() method to check exactly which case you’re in.

Locking your screen orientation by using android:screenOrientation is also affected by multi-window. For apps not targeting Android N, adding android:screenOrientation means you will not support multi-window at all — you’ll always force the user out of multi-window mode. Things change a little when you target N — instead of not supporting multi-window at all, any orientation you set via android:screenOrientation is ignored when in multi-window mode.

Keep in mind that locking your orientation at runtime using setRequestedOrientation() will have no effect in multi-window mode, whether you target N or not.

Adding the android:immersive attribute to your Activity’s manifest also disables multi-window on apps not targeting N, with the same rules as android:screenOrientation above.

Pro-tip 4: Build a responsive UI for all screen sizes

Orientation isn’t the only thing that goes into designing for split screen. Multi-window is the first time your tablet UI (you have a tablet UI right? After all, 12.5% of 1.4 billion devices is a lot of devices…) is going to be shrunk down to a miniature size.

If you’ve been building a responsive UI that reacts to the available space and has relatively similar phone and tablet layouts, you’ll find you’ll be well prepared for multi-window. As suggested, scaling the UI down to 220dp wide/tall and building up from that size to the fullscreen size is a something you can do now.

Building a single responsive layout makes for smooth transitions as your app resizes

However, if your mobile and tablet UIs are vastly different, don’t overwhelm users by switching between the two — stick with the tablet UI and work on scaling it down. There’s a number of responsive UI patterns you might consider employing to make resizing a seamless experience for your users — again, no N APIs needed.

Pro-tip 5: Activities started by other apps must always support multi-window

In the multi-window world, your whole task is represented by a single window. That’s why if you want to launch an adjacent activity you need to start a new task — new task, new window.

It also means the reverse is true, quoting that same page:

If you launch an activity within a task stack, the activity replaces the activity on the screen, inheriting all of its multi-window properties.

That means if you have an Activity that can be started by other apps, your activity will inherit the same multi-window properties as the calling Activity. This includes attributes such as minimal size. In cases of startActivityForResult(), your Activity must be part of the same task stack and even in the case of an implicit intent, you can’t guarantee that they’ll also include a FLAG_ACTIVITY_NEW_TASK.

Therefore every one of those activities (and any activities started by that Activity) must support multi-window, all the way down the smallest size. Test thoroughly!

Test all the things!

The best way to prepare for multi-window is to test your app. Even without any code changes or going through the process of setting up the Android N SDK, installing your existing app on an Android N device or emulator is a fantastic first step and an easy way to catch low hanging fruit and #BuildBetterApps.

Follow the Android Development Patterns Collection for more!