docs: New doc for N Preview Multi-Window feature.

page.title=N Developer Preview Multi-Window Support

page.metaDescription=New support in the N Developer Preview for showing more than one app at a time.

page.keywords="multi-window", "android N", "split screen", "free-form"

@jd:body

<div id="qv-wrapper">

  <div id="qv">

    <h2>In this document</h2>

      <ol>

        <li><a href="#overview">Overview</a></li>

        <li><a href="#lifecycle">Multi-Window Lifecycle</a></li>

        <li><a href="#configuring">Configuring Your App for Multi-Window

              Mode</a></li>

        <li><a href="#running">Running Your App in Multi-Window Mode</a></li>

        <li><a href="#testing">Testing Your App's Multi-Window Support</a></li>

      </ol>

  </div>

</div>

<p>

  The N Developer Preview 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 <em>split-screen</em> mode. On TV devices, apps can

  use <em>picture-in-picture</em> mode to continue video playback while users

  are interacting with another app.

</p>

<p>

  If you build your app with the N Preview SDK, you can configure how your app

  handles multi-window display. For example, you can specify your activity's

  minimum allowable dimensions, preventing users from making the activity

  window smaller than that size. You can also disable multi-window display for

  your app, ensuring that the system only shows your app in full-screen

  mode.

</p>

<h2 id="overview">Overview</h2>

<p>

  The N Developer Preview 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 device:

</p>

<ul>

  <li>Handheld devices running the N Developer Preview 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.

  </li>

  <li>On Nexus Player running the N Developer Preview, apps can put themselves

  in picture-in-picture mode, allowing them to continue showing content

  while the user browses or interacts with other apps. For more information,

  see <a href="picture-in-picture.html">Picture-in-picture</a>.

  </li>

  <li>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.

  </li>

</ul>

<img src="{@docRoot}preview/images/mw-splitscreen.png" alt="" width="641"

    id="img-split-screen" />

<p class="img-caption">

  <strong>Figure 1.</strong> Two apps running side-by-side in split-screen mode.

</p>

<p>

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

</p>

<ul>

  <li>If the user opens the <a href="{@docRoot}guide/components/recents.html">Overview

  screen</a> 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.

  </li>

  <li>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.

  <!-- ***TODO: screenshot*** -->

  </li>

</ul>

<h2 id="lifecycle">Multi-Window Lifecycle</h2>

<p>

  Multi-window mode does not change the <a href=

  "{@docRoot}training/basics/activity-lifecycle/index.html">activity

  lifecycle</a>.

</p>

<p>

  In multi-window mode, only the activity the user has most recently interacted

  with is active at a given time. This activity is considered <em>topmost</em>.

  All other activities are in the paused state, even if they are visible.

  However, the system gives these paused-but-visible activities higher priority

  than activities that are not visible. If the user interacts with one of the

  paused activities, that activity is resumed, and the previously topmost

  activity is paused.

</p>

<p class="note">

  <strong>Note:</strong> In multi-window mode, an app can be in the paused

  state and still be visible to the user. An app might need to continue its

  activities even while paused. For example, a video-playing app that is in

  paused mode but is visible should continue showing its video.

</p>

<p>

  When the user puts an app into multi-window mode, the system notifies the

  activity of a configuration change, as specified in <a href=

  "{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime

  Changes</a>. 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 <a href=

  "{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime

  Changes</a>, 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.

</p>

<p>

  If the user is resizes a window and makes it larger in either dimension,

  the system fills in the expanded

  area with the color specified by the {@link android.R.attr#windowBackground

  windowBackground} attribute, or by the default

  <code>windowBackgroundFallback</code> style attribute. When the user finishes

  resizing the window, the activity is redrawn with its new dimensions, as

  described in <a href=

  "{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime

  Changes</a>.

</p>

<h2 id="configuring">Configuring Your App for Multi-Window Mode</h2>

<p>

  If your app targets the N Developer Preview, 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.

</p>

<p class="note">

  <strong>Note:</strong> If you build a multi-orientation app with a version of the

  SDK earlier than the N Developer Preview, 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 <em>not</em> 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.

</p>

<h4 id="resizeableActivity">android:resizeableActivity</h4>

<p>

  Set this attribute in your manifest's <code>&lt;activity&gt;</code> or

  <code>&lt;application&gt;</code> node to enable or disable multi-window

  display:

</p>

<pre>

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

</pre>

<p>

  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.

</p>

<p>

  If your app targets the N Developer Preview, but you do not specify a value

  for this attribute, the attribute's value defaults to true.

</p>

<h4 id="supportsPictureInPicture">android:supportsPictureInPicture</h4>

<p>

  Set this attribute in your manifest's <code>&lt;activity&gt;</code> node to

  indicate whether the activity supports picture-in-picture display.

</p>

<pre>

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

</pre>

<h3 id="layout">Layout attributes</h3>

<p>

  With the N Developer Preview, the <code>&lt;layout&gt;</code> manifest element

  supports several attributes that affect how an activity behaves in

  multi-window mode:

</p>

<dl>

  <dt>

    <code>android:defaultWidth</code>

  </dt>

  <dd>

    Default width of the activity when launched in freeform mode.

  </dd>

  <dt>

    <code>android:defaultHeight</code>

  </dt>

  <dd>

    Default height of the activity when launched in freeform mode.

  </dd>

  <dt>

    <code>android:gravity</code>

  </dt>

  <dd>

    Initial placement of the activity when launched in freeform mode. See the

    {@link android.view.Gravity} reference for suitable values.

  </dd>

  <dt>

    <code>android:minimalSize</code>

  </dt>

  <dd>

    Minimum height and minimum width for the activity in both split-screen

    and freeform modes. The system does not permit the user to resize the

    activity below the specified size in either dimension.

  </dd>

</dl>

<p>

  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:

</p>

<pre>

<activity android:name=".MyActivity">

    <layout android:defaultHeight="500dp"

          android:defaultWidth="600dp"

          android:gravity="top|end"

          android:minimalSize="450dp" />

</activity>

</pre>

<h2 id="running">Running Your App in Multi-Window Mode</h2>

<p>

  The N Developer Preview offers new functionality to support apps that can run

  in multi-window mode.

</p>

<h3 id="disabled-features">Disabled features in multi-window mode</h3>

<p>

  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:

<ul>

  <li>Some <a href="{@docRoot}training/system-ui/index.html">System UI</a>

  customization options are disabled; for example, apps cannot hide the status

  bar if they are not running in full-screen mode.

  </li>

  <li>The system ignores changes to the <code><a href=

  "{@docRoot}guide/topics/manifest/activity-element.html#screen"

  >android:screenOrientation</a></code> attribute.

  </li>

</ul>

<h3 id="change-notification">Multi-window change notification and querying</h3>

<p>

  The following new methods have been added to the {@link android.app.Activity}

  class to support multi-window display. For details on each method, see the

  <!--TODO: Add link to preview download page-->

   N Preview SDK Reference.

</p>

<dl>

  <dt>

    <code>Activity.inMultiWindow()</code>

  </dt>

  <dd>

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

  </dd>

  <dt>

    <code>Activity.inPictureInPicture()</code>

  </dt>

  <dd>

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

    <p class="note">

      <strong>Note:</strong> Picture-in-Picture mode is a special case of

      multi-window mode. If <code>myActivity.inPictureInPicture()</code>

      returns true, then <code>myActivity.inMultiWindow()</code> also returns

      true.

    </p>

  </dd>

  <dt>

    <code>Activity.onMultiWindowChanged()</code>

  </dt>

  <dd>

    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.

  </dd>

  <dt>

    <code>Activity.onPictureInPictureChanged()</code>

  </dt>

  <dd>

    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.

  </dd>

</dl>

<p>

  There are also {@link android.app.Fragment} versions of each of these

  methods, for example <code>Fragment.inMultiWindow()</code>.

</p>

<h3 id="entering-pip">Entering Picture-in-Picture Mode</h3>

<p>

  To put an activity in picture-in-picture mode, call the new method

  <code>Activity.enterPictureInPicture()</code>. This method has no effect if

  the device does not support picture-in-picture mode. For more information,

  see <!-- TODO: Link to new N-Preview PIP doc-->

  Picture-in-Picture Mode.

</p>

<h3 id="launch">Launch New Activities in Multi-Window Mode</h3>

<p>

  When you launch a new activity, you can hint to the system that the new

  activity should be displayed adjacent to the current one, if possible. To do

  this, use the flag

  <code>Intent.FLAG_ACTIVITY_LAUNCH_TO_ADJACENT</code>. Passing

  this flag requests the following behavior:

</p>

<ul>

  <li>If the device is in split-screen mode, the system attempts to create the

  new activity next to the activity that launched it, so the two activities

  share the screen. The system is not guaranteed to be able to do this, but it

  makes the activities adjacent if possible.

  </li>

  <li>If the device is not in split-screen mode, this flag has no effect.

  </li>

</ul>

<p>

  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

  <code>ActivityOptions.setLaunchBounds()</code>. This method has no effect if

  the device is not in multi-window mode.

</p>

<p class="note">

  <strong>Note:</strong> 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.

</p>

<h2 id="testing">Testing Your App's Multi-Window Support</h2>

<p>

  Whether or not you update your app for the N Developer Preview, you should

  verify how it behaves in multi-window mode in case a user tries to launch it

  in multiwindow mode on a device running the N Developer Preview.

</p>

<h3 id="configuring">Configuring a Test Device</h3>

<p>

  If you install the N Developer Preview on a device, split-screen mode is

  automatically supported.

</p>

<h3 id="test-non-n">If your app was not built with the N Preview SDK</h3>

<p>

  If you did not build your app with the N Preview SDK 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.

</p>

<p>

  If your app does not declare a fixed orientation, you should launch your app

  on a device running the N Developer Preview and attempt to put the app in

  split-screen mode. Verify that the user experience is

  acceptable when the app is forcibly resized.

</p>

<p>

  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.

</p>

<h3 id="test-mw">If you support multi-window mode</h3>

<p>

  If you built your app with the N Preview SDK and have not disabled

  multi-window support, verify the following behavior under both split-screen

  and freeform modes.

</p>

<ul>

  <li>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.

  </li>

  <li>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.

  </li>

  <li>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.

  </li>

  <li>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.

  </li>

  <li>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.

  </li>

</ul>

<h4 id="test-checklist">Testing checklist</h4>

<p>

  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.

</p>

<ul>

  <li>Enter and leave multi-window mode.

  </li>

  <li>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.

  </li>

  <li>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.

  </li>

  <li>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, see <a href="{@docRoot}tools/debugging/debugging-memory.html">

  Investigating Your RAM Usage</a>.

  </li>

  <li>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.

  </li>

</ul>

<h3 id="test-disabled-mw">If you have disabled multi-window support</h3>

<p>

  If you disabled multi-window support by setting

  <code>android:resizableActivity="false"</code>, you should launch your app on

  a device running the N Developer Preview 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.

</p>