docs: Moving multi-window docs out of N Preview area for N release

am: dda5e4b1ab

Change-Id: I22779b166a1ad81237564c10be253629110d2e6d

docs/html/_redirects.yaml

@@ -1,11 +1,6 @@
 # For information about this file's format, see
 # https://developers.google.com/internal/publishing/redirects
 redirects:
-
-# Redirects from (removed) N Preview documentation
-- from: /preview/features/afw.html
-  to: https://developers.google.com/android/work/overview
-
 - from: /about/versions/index.html
   to: /about/index.html
 - from: /about/versions/api-levels.html
@@ -1207,6 +1202,11 @@ redirects:
 - from: /r/studio-ui/menu-start.html
   to: /training/index.html?utm_medium=android-studio
 
+# Redirects from (removed) N Preview documentation
+- from: /preview/features/afw.html
+  to: https://developers.google.com/android/work/overview
+- from: /preview/features/multi-window.html
+  to: /guide/topics/ui/multi-window.html
 - from: /preview/features/icu4j-framework.html
   to: /guide/topics/resources/icu4j-framework.html
 - from: /preview/features/key-attestation.html
@@ -1226,4 +1226,4 @@ redirects:
 - from: /preview/features/multilingual-support.html
   to: /guide/topics/resources/multilingual-support.html
 - from: /preview/j8-jack.html
-  to: /guide/platform/j8-jack.html
+  to: /guide/platform/j8-jack.html

docs/html/guide/_book.yaml

@@ -235,6 +235,8 @@ toc:
       path: /guide/topics/search/adding-custom-suggestions.html
     - title: Searchable Configuration
       path: /guide/topics/search/searchable-config.html
+  - title: Multi-Window Support
+    path: /guide/topics/ui/multi-window.html
   - title: Drag and Drop
     path: /guide/topics/ui/drag-drop.html
   - title: Accessibility

docs/html/guide/topics/manifest/activity-element.jd

@@ -35,6 +35,7 @@ parent.link=manifest-intro.html
           android:<a href="#prmsn">permission</a>="<i>string</i>"
           android:<a href="#proc">process</a>="<i>string</i>"
           android:<a href="#relinquish">relinquishTaskIdentity</a>=["true" | "false"]
+          android:<a href="#resizeableActivity">resizeableActivity</a>=["true" | "false"]
           android:<a href="#screen">screenOrientation</a>=["unspecified" | "behind" |
                                      "landscape" | "portrait" |
                                      "reverseLandscape" | "reversePortrait" |
@@ -43,6 +44,7 @@ parent.link=manifest-intro.html
                                      "sensor" | "fullSensor" | "nosensor" |
                                      "user" | "fullUser" | "locked"]
           android:<a href="#state">stateNotNeeded</a>=["true" | "false"]
+          android:<a href="#supportsPIP">supportsPictureInPicture</a>=["true" | "false"]
           android:<a href="#aff">taskAffinity</a>="<i>string</i>"
           android:<a href="#theme">theme</a>="<i>resource or theme</i>"
           android:<a href="#uioptions">uiOptions</a>=["none" | "splitActionBarWhenNarrow"]
@@ -794,9 +796,39 @@ to "{@code false}". The default value is "{@code false}".
 and icons in the <a href="{@docRoot}guide/components/recents.html">overview screen</a>.</p>
 </dd>
 
+<dt id="resizeableActivity"><code>resizeableActivity</code></dt>
+
+<dd>
+<p>
+  Specifies whether the app supports <a href=
+  "{@docRoot}guide/topics/ui/multi-window.html">multi-window display</a>. You
+  can set this attribute in either the <code>&lt;activity&gt;</code> or
+  <a href="application-element.html"><code>&lt;application&gt;</code></a>
+  element.
+</p>
+
+<p>
+  If you set this attribute to true, the user can launch the activity in
+  split-screen and freeform modes. If you set the attribute 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 API level 24 or higher, but you do not specify a value
+  for this attribute, the attribute's value defaults to true.
+</p>
+
+<p>
+  This attribute was added in API level 24.
+</p>
+</dd>
 
 <dt><a name="screen"></a>{@code android:screenOrientation}</dt>
-<dd>The orientation of the activity's display on the device.
+<dd>The orientation of the activity's display on the device. The system ignores
+  this attribute if the activity is running in <a
+  href="{@docRoot}guide/topics/ui/multi-window.html">multi-window mode</a>.
 
 <p>The value can be any one of the following strings:</p>
 
@@ -921,6 +953,19 @@ home screen uses this setting to make sure that it does not get removed if it
 crashes for some reason.
 </p></dd>
 
+<dt id="supportsPIP"><code>supportsPictureInPicture</code></dt>
+
+<dd>
+<p>
+  Specifies whether the activity supports <a href=
+  "{@docRoot}training/tv/playback/picture-in-picture.jd">Picture-in-Picture</a>
+  display. The system ignores this attribute if <a href=
+  "#resizeableActivity"><code>android:resizeableActivity</code></a> is false.
+</p>
+
+<p>This attribute was added in API level 24.</p>
+</dd>
+
 <dt><a name="aff"></a>{@code android:taskAffinity}</dt>
 <dd>The task that the activity has an affinity for.  Activities with
 the same affinity conceptually belong to the same task (to the same

docs/html/guide/topics/manifest/application-element.jd

@@ -26,6 +26,7 @@ page.title=<application>
              android:<a href="#proc">process</a>="<i>string</i>"
              android:<a href="#restoreany">restoreAnyVersion</a>=["true" | "false"]
              android:<a href="#requiredAccountType">requiredAccountType</a>="<i>string</i>"
+             android:<a href="#resizeableActivity">resizeableActivity</a>=["true" | "false"]
              android:<a href="#restrictedAccountType">restrictedAccountType</a>="<i>string</i>"
              android:<a href="#supportsrtl">supportsRtl</a>=["true" | "false"]
              android:<a href="#aff">taskAffinity</a>="<i>string</i>"
@@ -358,6 +359,34 @@ your app to access personal information that belongs to the owner user.</p>
 </dd>
 
 
+<dt id="resizeableActivity"><code>resizeableActivity</code></dt>
+
+<dd>
+<p>
+  Specifies whether the app supports <a href=
+  "{@docRoot}guide/topics/ui/multi-window.html">multi-window display</a>. You
+  can set this attribute in either the <a href="activity-element">
+  <code>&lt;activity&gt;</code></a> or <code>&lt;application&gt;</code> element.
+</p>
+
+<p>
+  If you set this attribute to true, the user can launch the activity in
+  split-screen and freeform modes. If you set the attribute 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 API level 24 or higher, but you do not specify a value
+  for this attribute, the attribute's value defaults to true.
+</p>
+
+<p>
+  This attribute was added in API level 24.
+</p>
+</dd>
+
 <dt><a name="restrictedAccountType"></a>{@code android:restrictedAccountType}</dt>
 <dd>Specifies the account type required by this application and indicates that restricted profiles
 are allowed to access such accounts that belong to the owner user. If your app requires an

docs/html/guide/topics/resources/runtime-changes.jd

@@ -17,6 +17,8 @@ page.tags=activity,lifecycle
     <li><a href="accessing-resources.html">Accessing Resources</a></li>
     <li><a href="http://android-developers.blogspot.com/2009/02/faster-screen-orientation-change.html">Faster
         Screen Orientation Change</a></li>
+    <li><a href="{@docRoot}guide/topics/ui/multi-window.html#lifecycle">
+      Multi-Window Lifecycle</a></li>
   </ol>
 </div>
 </div>

docs/html/guide/topics/ui/multi-window.jd

@@ -17,6 +17,8 @@ page.keywords="multi-window", "android N", "split screen", "free-form"
       </ol>
     <h2>See Also</h2>
       <ol>
+        <li><a href="{@docRoot}training/tv/playback/picture-in-picture.html">Adding
+          Picture-in-Picture</a></li>
         <li><a class="external-link"
           href="https://github.com/googlesamples/android-MultiWindowPlayground">Multi-Window
           Playground sample app</a></li>
@@ -28,7 +30,7 @@ page.keywords="multi-window", "android N", "split screen", "free-form"
 </div>
 
 <p>
-  Android N adds support for displaying more than one app at the
+  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 <em>split-screen</em> mode. On TV devices, apps can
   use <em>picture-in-picture</em> mode to continue video playback while users
@@ -36,7 +38,7 @@ page.keywords="multi-window", "android N", "split screen", "free-form"
 </p>
 
 <p>
-  If you build your app with the N Preview SDK, you can configure how your 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
@@ -46,20 +48,20 @@ page.keywords="multi-window", "android N", "split screen", "free-form"
 <h2 id="overview">Overview</h2>
 
 <p>
-  Android N allows several apps to share the screen at once. For
+  Android 7.0 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 Android N offer split-screen
+  <li>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.
   </li>
 
-  <li>On Nexus Player running Android N, apps can put themselves
+  <li>On TV devices, apps can put themselves
   in <a href="picture-in-picture.html">picture-in-picture mode</a>, allowing
   them to continue showing content while the user browses or interacts with
   other apps.
@@ -72,9 +74,9 @@ page.keywords="multi-window", "android N", "split screen", "free-form"
   </li>
 </ul>
 
-<img src="{@docRoot}preview/images/mw-splitscreen.png" alt="" width="650"
+<img src="{@docRoot}images/android-7.0/mw-splitscreen.png" alt="" width="650"
-    srcset="{@docRoot}preview/images/mw-splitscreen.png 1x,
+    srcset="{@docRoot}images/android-7.0/mw-splitscreen.png 1x,
-    {@docRoot}preview/images/mw-splitscreen_2x.png 2x,"
+    {@docRoot}images/android-7.0/mw-splitscreen_2x.png 2x,"
     id="img-split-screen" />
 <p class="img-caption">
   <strong>Figure 1.</strong> Two apps running side-by-side in split-screen mode.
@@ -100,9 +102,7 @@ page.keywords="multi-window", "android N", "split screen", "free-form"
 <p>
   Users can <a href="{@docRoot}guide/topics/ui/drag-drop.html">drag and
   drop</a> data from one activity to another while the activities are sharing
-  the screen. (Previously, users could only drag and drop data within a single
+  the screen.
-  activity.)
-</p>
 
 <h2 id="lifecycle">Multi-Window Lifecycle</h2>
 
@@ -163,7 +163,7 @@ page.keywords="multi-window", "android N", "split screen", "free-form"
 <h2 id="configuring">Configuring Your App for Multi-Window Mode</h2>
 
 <p>
-  If your app targets Android N, you can configure how and
+  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
@@ -173,8 +173,8 @@ page.keywords="multi-window", "android N", "split screen", "free-form"
 </p>
 
 <p class="note">
-  <strong>Note:</strong> If you build a multi-orientation app with a version of the
+  <strong>Note:</strong> If you build a multi-orientation app that targets API
-  SDK lower than Android N, and the user uses the app in
+  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 <em>not</em> resize fixed-orientation apps; if
@@ -183,10 +183,13 @@ page.keywords="multi-window", "android N", "split screen", "free-form"
 </p>
 
 <h4 id="resizeableActivity">android:resizeableActivity</h4>
+
 <p>
-  Set this attribute in your manifest's <code>&lt;activity&gt;</code> or
+  Set this attribute in your manifest's <a href=
-  <code>&lt;application&gt;</code> node to enable or disable multi-window
+  "{@docRoot}guide/topics/manifest/activity-element"><code>&lt;activity&gt;</code></a>
-  display:
+  or <a href=
+  "{@docRoot}guide/topics/manifest/application-element"><code>&lt;application&gt;</code></a>
+  element to enable or disable multi-window display:
 </p>
 
 <pre>
@@ -202,16 +205,19 @@ android:resizeableActivity=["true" | "false"]
 </p>
 
 <p>
-  If your app targets Android N, but you do not specify a value
+  If your app targets API level 24, 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
+  Set this attribute in your manifest's <a href=
-  indicate whether the activity supports picture-in-picture display. This
+  "{@docRoot}guide/topics/manifest/activity-element"><code>&lt;activity&gt;</code></a>
-  attribute is ignored if <code>android:resizeableActivity</code> is false.
+  node to indicate whether the activity supports <a href=
+  "{@docRoot}training/tv/playback/picture-in-picture.jd">Picture-in-Picture</a>
+  display. This attribute is ignored if <code>android:resizeableActivity</code>
+  is false.
 </p>
 
 <pre>
@@ -221,7 +227,7 @@ android:supportsPictureInPicture=["true" | "false"]
 <h3 id="layout">Layout attributes</h3>
 
 <p>
-  With Android N, the <code>&lt;layout&gt;</code> manifest element
+  With Android 7.0, the <code>&lt;layout&gt;</code> manifest element
   supports several attributes that affect how an activity behaves in
   multi-window mode:
 </p>
@@ -283,8 +289,8 @@ android:supportsPictureInPicture=["true" | "false"]
 <h2 id="running">Running Your App in Multi-Window Mode</h2>
 
 <p>
-  Android N offers new functionality to support apps that can run
+  Beginning with Android 7.0, the system offers functionality to support apps
-  in multi-window mode.
+  that can run in multi-window mode.
 </p>
 
 <h3 id="disabled-features">Disabled features in multi-window mode</h3>
@@ -309,15 +315,13 @@ android:supportsPictureInPicture=["true" | "false"]
 <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}
+  {@link android.app.Activity} offers the following methods to support
-  class to support multi-window display. For details on each method, see the
+  multi-window display.
-  <a href="{@docRoot}preview/setup-sdk.html#docs-dl">N Preview SDK
-  Reference</a>.
 </p>
 
 <dl>
   <dt>
-    <code>Activity.isInMultiWindowMode()</code>
+    {@link android.app.Activity#isInMultiWindowMode isInMultiWindowMode()}
   </dt>
 
   <dd>
@@ -325,12 +329,14 @@ android:supportsPictureInPicture=["true" | "false"]
   </dd>
 
   <dt>
-    <code>Activity.isInPictureInPictureMode()</code>
+    {@link android.app.Activity#isInPictureInPictureMode
+    isInPictureInPictureMode()}
   </dt>
 
   <dd>
-    Call to find out if the activity is in picture-in-picture mode.
+    Call to find out if the activity is in <a href=
-
+    "{@docRoot}training/tv/playback/picture-in-picture.jd">picture-in-picture</a>
+    mode.
     <p class="note">
       <strong>Note:</strong> Picture-in-picture mode is a special case of
       multi-window mode. If <code>myActivity.isInPictureInPictureMode()</code>
@@ -340,7 +346,8 @@ android:supportsPictureInPicture=["true" | "false"]
   </dd>
 
   <dt>
-    <code>Activity.onMultiWindowModeChanged()</code>
+    {@link android.app.Activity#onMultiWindowModeChanged
+    onMultiWindowModeChanged()}
   </dt>
 
   <dd>
@@ -351,7 +358,8 @@ android:supportsPictureInPicture=["true" | "false"]
   </dd>
 
   <dt>
-    <code>Activity.onPictureInPictureModeChanged()</code>
+    {@link android.app.Activity#onPictureInPictureModeChanged
+    onPictureInPictureModeChanged()}
   </dt>
 
   <dd>
@@ -363,17 +371,21 @@ android:supportsPictureInPicture=["true" | "false"]
 </dl>
 
 <p>
-  There are also {@link android.app.Fragment} versions of each of these
+  The {@link android.app.Fragment} class exposes versions of many of these
-  methods, for example <code>Fragment.isInMultiWindowMode()</code>.
+  methods, for example {@link android.app.Fragment#onMultiWindowModeChanged
+  Fragment.onMultiWindowModeChanged()}.
 </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
+  To put an activity in picture-in-picture mode, call {@link
-  <code>Activity.enterPictureInPictureMode()</code>. This method has no effect if
+  android.app.Activity#enterPictureInPictureMode
-  the device does not support picture-in-picture mode. For more information,
+  Activity.enterPictureInPictureMode()}. This method has no effect if the
-  see the <a href="picture-in-picture.html">Picture-in-Picture</a> documentation.
+  device does not support picture-in-picture mode. For more information, see
+  the <a href=
+  "{@docRoot}training/tv/playback/picture-in-picture.jd">Picture-in-Picture</a>
+  documentation.
 </p>
 
 <h3 id="launch">Launch New Activities in Multi-Window Mode</h3>
@@ -381,8 +393,8 @@ android:supportsPictureInPicture=["true" | "false"]
 <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
+  this, use the intent flag
-  <code>Intent.FLAG_ACTIVITY_LAUNCH_TO_ADJACENT</code>. Passing
+  {@link android.content.Intent#FLAG_ACTIVITY_LAUNCH_ADJACENT}. Passing
   this flag requests the following behavior:
 </p>
 
@@ -400,7 +412,8 @@ android:supportsPictureInPicture=["true" | "false"]
 <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
+  {@link android.app.ActivityOptions#setLaunchBounds
+  ActivityOptions.setLaunchBounds()}. This method has no effect if
   the device is not in multi-window mode.
 </p>
 
@@ -416,22 +429,15 @@ android:supportsPictureInPicture=["true" | "false"]
 <p>
   Users can <a href="{@docRoot}guide/topics/ui/drag-drop.html">drag and
   drop</a> data from one activity to another while the two activities are
-  sharing the screen. (Previously, users could only drag and drop data within a
+  sharing the screen. (Prior to Android 7.0, users could only drag and drop data
-  single activity.) For this reason, you may want to add drag and drop
+  within a single activity.) For this reason, you may want to add drag and drop
   functionality to your app if your app does not currently support it.
 </p>
 
-<p>
-  The N Preview SDK extends the <a href=
-  "{@docRoot}reference/android/view/package-summary.html"><code>android.view</code></a>
-  package to support cross-app drag and drop. For details on the following
-  classes and methods, see the <a href="{@docRoot}preview/setup-sdk.html#docs-dl">N
-  Preview SDK Reference</a>.
-</p>
 
 <dl>
   <dt>
-    <code>android.view.DropPermissions</code>
+    {@link android.view.DragAndDropPermissions}
   </dt>
 
   <dd>
@@ -440,20 +446,20 @@ android:supportsPictureInPicture=["true" | "false"]
   </dd>
 
   <dt>
-    <code>View.startDragAndDrop()</code>
+    {@link android.view.View#startDragAndDrop View.startDragAndDrop()}
   </dt>
 
   <dd>
-    New alias for {@link android.view.View#startDrag View.startDrag()}. To
+    Alias for {@link android.view.View#startDrag View.startDrag()}. To enable
-    enable cross-activity drag and drop, pass the new flag
+    cross-activity drag and drop, pass the flag {@link
-    <code>View.DRAG_FLAG_GLOBAL</code>. If you need to give URI permissions to
+    android.view.View#DRAG_FLAG_GLOBAL}. If you need to give URI permissions to
-    the recipient activity, pass the new flags
+    the recipient activity, pass the flags {@link
-    <code>View.DRAG_FLAG_GLOBAL_URI_READ</code> or
+    android.view.View#DRAG_FLAG_GLOBAL_URI_READ} or {@link
-    <code>View.DRAG_FLAG_GLOBAL_URI_WRITE</code>, as appropriate.
+    android.view.View#DRAG_FLAG_GLOBAL_URI_WRITE}, as appropriate.
   </dd>
 
   <dt>
-    <code>View.cancelDragAndDrop()</code>
+    {@link android.view.View#cancelDragAndDrop View.cancelDragAndDrop()}
   </dt>
 
   <dd>
@@ -462,7 +468,7 @@ android:supportsPictureInPicture=["true" | "false"]
   </dd>
 
   <dt>
-    <code>View.updateDragShadow()</code>
+    {@link android.view.View#updateDragShadow View.updateDragShadow()}
   </dt>
 
   <dd>
@@ -471,7 +477,8 @@ android:supportsPictureInPicture=["true" | "false"]
   </dd>
 
   <dt>
-    <code>Activity.requestDragAndDropPermissions()</code>
+    {@link android.app.Activity#requestDragAndDropPermissions
+    Activity.requestDragAndDropPermissions()}
   </dt>
 
   <dd>
@@ -483,29 +490,29 @@ android:supportsPictureInPicture=["true" | "false"]
 <h2 id="testing">Testing Your App's Multi-Window Support</h2>
 
 <p>
-  Whether or not you update your app for Android N, you should
+  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 multiwindow mode on a device running Android N.
+  in multi-window mode on a device running Android 7.0 or higher.
 </p>
 
 <h3 id="configuring">Configuring a Test Device</h3>
 
 <p>
-  If you install Android N on a device, split-screen mode is
+  If a device runs Android 7.0 or higher, it automatically supports split-screen
-  automatically supported.
+  mode.
 </p>
 
-<h3 id="test-non-n">If your app was not built with the N Preview SDK</h3>
+<h3 id="test-non-n">If your app targets API level 23 or lower</h3>
 
 <p>
-  If you did not build your app with the N Preview SDK and the user attempts to use
+  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
+  the app in multi-window mode, the system forcibly resizes the app unless the
-  declares a fixed orientation.
+  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 Android N and attempt to put the app in
+  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.
 </p>
@@ -519,7 +526,7 @@ android:supportsPictureInPicture=["true" | "false"]
 <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
+  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.
 </p>
@@ -593,7 +600,7 @@ android:supportsPictureInPicture=["true" | "false"]
 <p>
   If you disabled multi-window support by setting
   <code>android:resizableActivity="false"</code>, you should launch your app on
-  a device running Android N and attempt to put the app in
+  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.
 </p>

docs/html/training/basics/activity-lifecycle/pausing.jd

@@ -32,25 +32,34 @@ class="button">Download the demo</a>
   </div>
 </div>
 
-<p>During normal app use, the foreground activity is sometimes obstructed by other
+<p>
-visual components that cause the activity to <em>pause</em>.  For example, when a semi-transparent
+  During normal app use, the app sometimes loses focus, causing the activity to
-activity opens (such as one in the style of a dialog), the previous activity pauses. As long as the
+  <em>pause</em>. For example, when apps run in <a href=
-activity is still partially visible but currently not the activity in focus, it remains paused.</p>
+  "{@docRoot}guide/topics/ui/multi-window.html">multi-window mode</a>, only one
+  of the apps has the focus at any time; the system pauses all other apps. Similarly,
+  when a semi-transparent activity opens (such as one in the style of a
+  dialog), the previous activity pauses. As long as the activity is still
+  partially visible but currently not the activity in focus, it remains paused.
+</p>
 
 <p>However, once the activity is fully-obstructed and not visible, it <em>stops</em> (which is
 discussed in the next lesson).</p>
 
 <p>As your activity enters the paused state, the system calls the {@link
 android.app.Activity#onPause onPause()} method on your {@link android.app.Activity}, which allows
-you to stop ongoing actions that should not continue while paused (such as a video) or persist
+you to stop ongoing actions that should not continue while paused or persist
 any information that should be permanently saved in case the user continues to leave your app. If
 the user returns to your activity from the paused state, the system resumes it and calls the
 {@link android.app.Activity#onResume onResume()} method.</p>
 
-<p class="note"><strong>Note:</strong> When your activity receives a call to {@link
+<p class="note">
-android.app.Activity#onPause()}, it may be an indication that the activity will be paused for a
+  <strong>Note:</strong> When the system calls your activity's {@link
-moment and the user may return focus to your activity. However, it's usually the first indication
+  android.app.Activity#onPause()} method, the system may be signaling that the
-that the user is leaving your activity.</p>
+  activity will be paused for a moment and the user may return focus to your
+  activity, or that the app is running in multi-window mode. However, this
+  method call may also be the first indication that the user is leaving your
+  activity.
+</p>
 
 <img src="{@docRoot}images/training/basics/basic-lifecycle-paused.png" />
 <p class="img-caption"><strong>Figure 1.</strong> When a semi-transparent activity obscures
@@ -67,7 +76,11 @@ the user is leaving the activity and it will soon enter the Stopped state.  You
 the {@link android.app.Activity#onPause()} callback to:</p>
 
 <ul>
-  <li>Stop animations or other ongoing actions that could consume CPU.</li>
+  <li>Check if the activity is visible; if it is not, stop animations or other
+    ongoing actions that could consume CPU. Remember, beginning with Android
+    7.0, a paused app might be running in <a
+    href="{@docRoot}guide/topics/ui/multi-window.html">multi-window mode</a>.
+    In this case, you would not want to stop animations or video playback.</li>
   <li>Commit unsaved changes, but only if users expect such changes to be permanently saved when
 they leave (such as a draft email).</li>
   <li>Release system resources, such as broadcast receivers, handles to sensors (like