Merge "docs: Migrating PIP preview docs into regular DAC docs" into nyc-dev

  to: /training/articles/security-key-attestation.html

- from: /preview/features/security-config.html

  to: /training/articles/security-config.html

- from: /preview/features/picture-in-picture.html

  to: /training/tv/playback/picture-in-picture.html

      path: /training/tv/playback/guided-step.html

    - title: Enabling Background Playback

      path: /training/tv/playback/options.html

    - title: Adding Picture-in-picture

      path: /training/tv/playback/picture-in-picture.html

  - title: Helping Users Find Content on TV

    path: /training/tv/discovery/index.html

    path_attributes:

page.title=Picture-in-picture

page.title=Adding Picture-in-picture

page.keywords=preview,sdk,PIP,Picture-in-picture

page.tags=androidn

helpoutsWidget=true

trainingnavtop=true

@jd:body

<div id="qv-wrapper">

<div id="qv">

<div id="tb-wrapper">

<div id="tb">

<h2>In this document</h2>

<ol>

</div>

</div>

<p>In Android N, Android TV users can now watch a video

in a pinned window in a corner of the screen when navigating within

apps. Picture-in-picture (PIP) mode lets apps run a video

<p>In Android 7.0, Android TV users can now watch a video

in a pinned window in a corner of the screen when navigating within or

between apps. 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 multitask while using your app, which

helps users be more productive.</p>

background. The PIP window lets users multitask while using Android TV,

which helps users be more productive.</p>

<p>Your app can decide when to trigger PIP mode. Here are some examples of

when to enter PIP mode:</p>

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, the PIP window is automatically

closed. Users can also close the PIP window through Recents.</p>

closed.</p>

<img src="{@docRoot}preview/images/pip-active.png" />

<img src="{@docRoot}images/android-7.0/pip-active.png" />

<p class="img-caption"><strong>Figure 1.</strong> A Picture-in-picture

video visible in a corner of the screen while the user browses content

on the main screen.</p>

<p>PIP leverages the multi-window APIs available in Android N to

<p>PIP leverages the multi-window APIs available in Android 7.0 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

<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.enterPictureInPictureMode()</code>. The following example

{@link android.app.Activity#enterPictureInPictureMode

enterPictureInPictureMode()}. The following example

switches to PIP mode when the user selects a dedicated PIP button on a media

control bar:</p>

<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" />

<img src="{@docRoot}images/android-7.0/pip-button.png" />

<p class="img-caption"><strong>Figure 1.</strong> A Picture-in-picture

button on a media control bar.</p>

<p>Android N includes a new

<code>PlaybackControlsRow.PictureInPictureAction</code> class which defines

<p>Android 7.0 includes a

{@link android.support.v17.leanback.widget.PlaybackControlsRow.PictureInPictureAction

PlaybackControlsRow.PictureInPictureAction} class which defines

control bar PIP actions and uses the PIP icon.</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. Remove UI elements before your activity enters PIP,

and restore these elements when your activity becomes full-screen again.

Override <code>Activity.onPictureInPictureModeChanged()</code> or

<code>Fragment.onPictureInPictureModeChanged()</code> and enable or

Override {@link android.app.Activity#onPictureInPictureModeChanged

Activity.onPictureInPictureModeChanged()} or

{@link android.app.Fragment#onPictureInPictureModeChanged

Fragment.onPictureInPictureModeChanged()} and enable or

disable your UI elements as needed, for example:</p>

<pre>

onPause()} method. Video playback should not be paused and should continue

playing if the activity is paused due to PIP mode.</p>

<p>In Android N, you should pause and resume video playback when the system

<p>In Android 7.0, you should pause and resume video playback when the system

calls your activity's {@link android.app.Activity#onStop onStop()} and

{@link android.app.Activity#onStart onStart()}. By doing this, you can avoid

having to check if your app is in PIP mode in

</pre>

<p>In your activity, override {@link android.app.Activity#onNewIntent

Activity.onNewIntent()} and handle the new video, stopping any existing video

onNewIntent()} and handle the new video, stopping any existing video

playback if needed.</p>

<h2 id="best">Best Practices</h2>