android_frameworks_base/docs/html/preview/features/multi-window.jd

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>
&lt;activity android:name=".MyActivity"&gt;
    &lt;layout android:defaultHeight="500dp"
          android:defaultWidth="600dp"
          android:gravity="top|end"
          android:minimalSize="450dp" /&gt;
&lt;/activity&gt;
</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>