From 192d56d3fa7e7a8423c685cdffe54dfc5267bf44 Mon Sep 17 00:00:00 2001
From: Daniel Yu 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. Your app can decide when to trigger PIP mode. Here are some examples on
+when to enter PIP mode: 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 Home 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. 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. 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
+ 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.
+
+
+Declaring Your Activity Supports Picture-in-picture
+
+android:supportsPictureInPicture and
+android:resizeableActivity to true. Also, specify
+that your activity handles layout configuration changes so that your activity
+won't relaunch when layout changes occur during PIP mode transitions.
+<activity android:name="VideoActivity"
+ android:resizeableActivity="true"
+ android:supportsPictureInPicture="true"
+ android:configChanges=
+ "screenSize|smallestScreenSize|screenLayout|orientation"
+ ...
+
+
+Switching Your Activity to Picture-in-picture
+
+When you need to switch your activity into PIP mode, call
+Activity.enterPictureInPicture(). The following example switches
+to PIP mode when the user selects a dedicated PIP button on a media control
+bar:
+@Override
+public void onActionClicked(Action action) {
+ if (action.getId() == R.id.lb_control_picture_in_picture) {
+ getActivity().enterPictureInPicture();
+ return;
+ }
+ ...
+
+
+Adding a PIP button to your media control bar lets your user easily switch +to PIP mode while controlling video playback.
+ +
+Figure 1. A Picture-in-picture +button on a media control bar.
+ +A new PlaybackControlsRow.PictureInPictureAction class is
+provided to use the PIP icon and handle control bar PIP actions.
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 Activity.onPictureInPictureChanged() or
+Fragment.onPictureInPictureChanged() and enable or
+disable your UI elements as needed, for example:
+@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.
+ ...
+ }
+}
+
+
+When your activity switches to PIP, the system considers the activity in a
+paused state, and calls your activity's onPause() 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
+onPause() method and handle playback appropriately, for
+example:
+@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
+ ...
+}
+
+
+When your activity switches out of PIP mode back to full screen mode, the
+system resumes your activity and calls your onResume() method.
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 Handling UI During Picture-in-picture Mode.
+ +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.
+ +When an activity is in PIP mode, by default it doesn't get input focus. To
+receive input events while in PIP mode, use
+MediaSession.setMediaButtonReceiver().
For more information on multi-window APIs, see +Android N +Developer Preview Multi-Window Support.
diff --git a/docs/html/preview/images/pip-active.png b/docs/html/preview/images/pip-active.png new file mode 100644 index 0000000000000000000000000000000000000000..1e4bb634553ae0add7d026b7e115219ef7625f94 GIT binary patch literal 191954 zcmV)vK$X9VP)WRNpzw3VrfNt-p;+0>x
zUC@9q+m#o-?r-rIPma6C0Dt$|-Yx995BRPCtT|_q0K4SJ-nC%0{H)px_c;Ry25{YF
zj;Oi$oV@}(G8(P2(mi#Z{^M1inay4<7Xq+mY!ceHL3l_l6W;FOTk+$R<0QmYql4sC
zjGg+7dY%G60dk_#S>_NOVort-7R=jq6Gd9V8y;igREx~Je#Fspm@Q|?5CI&bLt@ae
zv+FKPVFUwfGh@7nqKd*^2vNjPr?kXn0C+1P=-w+LSfcbi;r2WX(ryk8Y6XshLp;Pq
z02suK$P$dLI~0 7IF6ULQ@j+-#E2!~=d6~G~$a?TO4iYx~gC1Yd4YIydNNVmd(1J#`r@$@L~uq4hFrYK<_-U
z^paY^OL)-8stvbRB!Yo87xE&7<*BN>iAh;zOlFK(u`UWLGYAIJ04f55dXcC{1`z-d
zAS2ptJl&xXa`o}YMoO}(zsbhP5}hjwQlKS@>RSQOvMLAeVNBMDWsFT{xQty3Lsa)-
zyjs^`B}078q>;-m)^XWr=o8s{Z=o*PyeDN)0Z>HeF>E!>8*7l|hEf*w5=vp4;@uB>
z0w5s_jB$u@1zL@b9a
zoQ?{jlH_^haO2dl$O{1`O9rvwC>&Ixs(KD}XhvF~F?mrGc@DV~QALaz(kJRNI~o?_
zVWu2ZA$KO4z#(!BA=;{5D05vmR1{TRkt$AR3-7JSTAmLx3?Zs@RrJ(Ei$ns3$XQ(M
zHhcS1Wkn)uvZufO(&LZ6V`DUk%yr$I8joV67hk*aU;Ov~^u?>!*EYsK{qgq=&TPDN
z^@eFAhz~V|#s}|X%jKzn{pJMSn0RV70(LR)~D$LK}w&wY(;
z;auiRD2nQ4-ArPTBaH*RqcuX+5?U~<+K2$?B=~uV`j##!+Py6WNzsUKpas=xKU+mZ
zyE|(0trQegbZuiTF9y!$xv`cgvz9;=)S05l1b|hMPzlix2_h0ijxjJtMN~i$MQZ0*
zxlxFjAeqoGM^#WTCWKIyORct4#)
zX*w(eHfM`G8!omNkGT2X^>?T1m6y{-*KL|-@Hv?$%~fahY2&xsd{6l|7c1s9kTY$S
zlhLwj0esx*?
*T1O0$K&
zqhBHd|AdL8RGi$o>2_*^G!D+SUeMbzF=`Q;>5cON00cQ(ldCG((u0hY^W1RuZWoI4
zoHO3YLuk$5?3p*>%lPR>VQd;{O81Jp0T@8fRCL(%p^yf{9kigo-a~OYXasI4j-E~9
z-BbuDzbgxyGEq!dGeVHpSycXsB>w$5?~r8N(w`8>jyB|sYwBsav<1sHc7;PzQS1vV
zPWutKB2&jQE)^xw0sHd(j5@+lT6~_1B92(Es)}!*v