Merge "docs: Adding documentation for "gregarious mode" (background playback) for Android TV." into mnc-docs

3 files changed, 73 insertions, 0 deletions

diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs
index 9f046b3b341a..3d1cf39299d6 100644
--- a/docs/html/training/training_toc.cs
+++ b/docs/html/training/training_toc.cs
@@ -1098,6 +1098,10 @@
                ja-lang="再生中カードを表示する">
               Displaying a Now Playing Card</a>
           </li>
+          <li>
+            <a href="<?cs var:toroot ?>training/tv/playback/options.html">
+              Enabling Background Playback</a>
+          </li>
         </ul>
       </li>
 
diff --git a/docs/html/training/tv/playback/index.jd b/docs/html/training/tv/playback/index.jd
index e39e34a0e971..43c6d41e09c1 100644
--- a/docs/html/training/tv/playback/index.jd
+++ b/docs/html/training/tv/playback/index.jd
@@ -64,4 +64,7 @@ startpage=true
 
   <dt><b><a href="now-playing.html">Displaying a Now Playing Card</a></b></dt>
     <dd>Learn how to use a MediaSession to display a Now Playing card on the home screen.</dd>
+
+  <dt><b><a href="options.html">Enabling Background Playback</a></b></dt>
+    <dd>Learn how to continue playback when the user clicks on <strong>Home</strong>.</dd>
 </dl>
diff --git a/docs/html/training/tv/playback/options.jd b/docs/html/training/tv/playback/options.jd
new file mode 100644
index 000000000000..c65343df6805
--- /dev/null
+++ b/docs/html/training/tv/playback/options.jd
@@ -0,0 +1,66 @@
+page.title=Enabling Background Playback
+page.tags=tv, play, playback, background
+helpoutsWidget=true
+
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+  <h2>This lesson teaches you to</h2>
+  <ol>
+    <li><a href="#background">Request Background Playback</a></li>
+  </ol>
+</div>
+</div>
+
+<p>
+A user watching content on a TV device may decide to switch to the TV launcher at any time.
+If a user switches to the launcher while using a TV playback app, by default the app is paused.
+Since the user did not explicitly request to pause playback, the default behavior might seem
+abrupt and unexpected. This lesson describes how to enable background playback in your app,
+which provides a better user experience.
+</p>
+
+<h2 id="background">Request Background Playback</h2>
+
+<p>Normally, when the user clicks on <strong>Home</strong> to display the TV
+launcher, the activity pauses. However, your app can request background playback, in
+which the activity continues playing behind the TV launcher.</p>
+
+<p>To request background playback, call
+{@link android.app.Activity#requestVisibleBehind requestVisibleBehind()}.
+Be sure to clean up media resources if the activity stops being
+visible. For example, you should free media resources if
+{@link android.app.Activity#requestVisibleBehind requestVisibleBehind()}
+returns <code>false</code> to indicate that the request failed, or if the system calls
+your override of {@link android.app.Activity#onVisibleBehindCanceled onVisibleBehindCanceled()}.
+</p>
+
+<pre>
+&commat;Override
+public void onPause() &lbrace;
+  super.onPause();
+  if (mVideoView.isPlaying()) &lbrace;
+    // Argument equals true to notify the system that the activity
+    // wishes to be visible behind other translucent activities
+    if (! requestVisibleBehind(true)) &lbrace;
+      // App-specific method to stop playback and release resources
+      // because call to requestVisibleBehind(true) failed
+      stopPlayback();
+    &rbrace;
+  &rbrace; else &lbrace;
+    // Argument equals false because the activity is not playing
+    requestVisibleBehind(false);
+  &rbrace;
+&rbrace;
+
+&commat;Override
+public void onVisibleBehindCanceled() &lbrace;
+  // App-specific method to stop playback and release resources
+  stopPlayback();
+  super.onVisibleBehindCanceled();
+&rbrace;
+</pre>
+