docs: Adding docs for N preview Picture-in-picture

Adding developer docs for the new PIP mode for Android TV devices.
Updates added based on review suggestions.

Bug: 27228723
Change-Id: I9fec21c349e1bc2b3f04275add8fff070f5c664c

docs/html/preview/features/picture-in-picture.jd

@@ -0,0 +1,175 @@
+page.title=Picture-in-picture
+page.keywords=preview,sdk,PIP,Picture-in-picture
+page.tags=androidn
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+  <h2>In this document</h2>
+  <ol>
+    <li><a href="#declaring">Declaring Your Activity Supports
+    Picture-in-picture</a></li>
+    <li><a href="#pip_button">Switching Your Activity to Picture-in-picture</a>
+    </li>
+    <li><a href="#handling_ui">Handling UI During Picture-in-picture</a>
+    </li>
+    <li><a href="#continuing_playback">Continuing Video Playback While in
+Picture-in-picture</a></li>
+    <li><a href="#best">Best Practices</a></li>
+  </ol>
+</div>
+</div>
+
+<p>In the Android N Developer Preview, Android TV users can now watch a video
+in a pinned window in a corner of the screen when navigating within
+applications. This new Picture-in-picture (PIP) mode lets apps run a video
+activity in the pinned window while another activity continues in the
+background. The PIP window lets users multi-task while using your app, making
+browsing and exploring your app easier and more engaging.</p>
+
+<p>Your app can decide when to trigger PIP mode. Here are some examples on
+when to enter PIP mode:</p>
+
+<ul>
+<li>When the user is navigating back from a video, the video activity can be
+placed in PIP mode instead of being closed.</li>
+<li>When the user is watching the end of an episode of content, the video can
+be placed in PIP mode while the main screen displays promotional or summary
+information about the next episode in the series.</li>
+<li>When the user wants to queue up additional content to watch while watching
+the currently playing content, the video can be placed in PIP mode and a
+content selection activity can be shown in the main screen.</li>
+</ul>
+
+<p>The PIP window is 240 x 135 dp and is shown at the top-most layer in one of
+the four corners of the screen, chosen by the system. The user can bring up a
+PIP menu that lets them toggle the PIP window to full screen, or close the PIP
+window, by holding down the <b>Home</b> button on the remote. If another
+video starts playing on the main screen, or the user leaves the app, the PIP
+window is automatically closed.</p>
+
+<p>PIP leverages the multi-window APIs available in the N Developer Preview to
+provide the pinned video overlay window. To add PIP to your app, you need to
+register your activities that support PIP, switch your activity to PIP mode as
+needed, and make sure UI elements are hidden and video playback continues when
+the activity is in PIP mode.</p>
+
+<h2 id="declaring">Declaring Your Activity Supports Picture-in-picture</h2>
+
+<p>By default, the system will not automatically support PIP for applications.
+If you want support PIP in your application, you need to register your video
+activity in your manifest by setting
+<code>android:supportsPictureInPicture</code> and
+<code>android:resizeableActivity</code> to <code>true</code>. Also, specify
+that your activity handles layout configuration changes so that your activity
+won't relaunch when layout changes occur during PIP mode transitions.</p>
+
+<pre>
+&lt;activity android:name="VideoActivity"
+    android:resizeableActivity="true"
+    android:supportsPictureInPicture="true"
+    android:configChanges=
+        "screenSize|smallestScreenSize|screenLayout|orientation"
+    ...
+</pre>
+
+<p>When registering your activity, keep in mind that in PIP mode, your
+activity is shown in a small overlay window on a TV screen. Video playback
+activities with minimal UI provide the best user experience. Non-video
+activities with detailed UI may not provide a good user experience in PIP
+mode.</p>
+
+<h2 id="pip_button">Switching Your Activity to Picture-in-picture</h2>
+
+When you need to switch your activity into PIP mode, call
+<code>Activity.enterPictureInPicture()</code>. The following example switches
+to PIP mode when the user selects a dedicated PIP button on a media control
+bar:</p>
+
+<pre>
+&#64;Override
+public void onActionClicked(Action action) {
+    if (action.getId() == R.id.lb_control_picture_in_picture) {
+        getActivity().enterPictureInPicture();
+        return;
+    }
+    ...
+</pre>
+
+<p>Adding a PIP button to your media control bar lets your user easily switch
+to PIP mode while controlling video playback.</p>
+
+<img src="{@docRoot}preview/images/pip-button.png" />
+<p class="img-caption"><strong>Figure 1.</strong> A Picture-in-picture
+button on a media control bar.</p>
+
+<p>A new <code>PlaybackControlsRow.PictureInPictureAction</code> class is
+provided to use the PIP icon and handle control bar PIP actions.</p>
+
+<h2 id="handling_ui">Handling UI During Picture-in-picture</h2>
+
+<p>When your activity enters PIP mode, your activity should only show video
+playback. You should remove UI elements before your activity enters PIP,
+and restore these elements when your activity becomes full-screen again.
+Override <code>Activity.onPictureInPictureChanged()</code> or
+<code>Fragment.onPictureInPictureChanged()</code> and enable or
+disable your UI elements as needed, for example:</p>
+
+<pre>
+&#64;Override
+public void onPictureInPictureChanged(boolean inPictureInPicture) {
+    if (inPictureInPicture) {
+        // Hide the controls in picture-in-picture mode.
+        ...
+    } else {
+        // Restore the playback UI based on the playback status.
+        ...
+    }
+}
+</pre>
+
+<h2 id="continuing_playback">Continuing Video Playback While in
+Picture-in-picture</h2>
+
+<p>When your activity switches to PIP, the system considers the activity in a
+paused state, and calls your activity's <code>onPause()</code> method. Video
+playback should not be paused and should continue playing if the activity is
+paused due to PIP mode. Check for PIP in your activity's
+<code>onPause()</code> method and handle playback appropriately, for
+example:</p>
+
+<pre>
+&#64;Override
+public void onPause() {
+    // If called due to PIP, do not pause playback
+    if (inPictureInPicture()) {
+        // Continue playback
+        ...
+    }
+    // If paused but not in PIP, pause playback if necessary
+    ...
+}
+</pre>
+
+<p>When your activity switches out of PIP mode back to full screen mode, the
+system resumes your activity and calls your <code>onResume()</code> method.</p>
+
+<h2 id="best">Best Practices</h2>
+
+<p>PIP is intended for activities that play full-screen video. When switching
+your activity into PIP mode, avoid showing anything except video content.
+Track when your activity enters PIP mode and hide UI elements, as described
+in <a href="#handling_ui">Handling UI During Picture-in-picture Mode</a>.</p>
+
+<p>Since the PIP window is shown as a floating window in the corner of the
+screen, you should avoid showing critical information in the main screen
+in any area that can be obscured by the PIP window.</p>
+
+<p>When an activity is in PIP mode, by default it doesn't get input focus. To
+receive input events while in PIP mode, use
+<code>MediaSession.setMediaButtonReceiver()</code>.</p>
+
+<p>For more information on multi-window APIs, see
+<a href="{@docRoot}preview/features/multi-window.html">Android N 
+Developer Preview Multi-Window Support</a>.</p>