From bfc8636dfca82470fb67720a4ac09cd5e58f2422 Mon Sep 17 00:00:00 2001
From: Daniel Yu <dsyu@google.com>
Date: Tue, 12 Jan 2016 10:02:21 -0800
Subject: [PATCH] docs: Adding documentation for "gregarious mode" (background
 playback) for Android TV.

Formerly this was cherry-picked from Andy S's CL: ag/732685
Into a CL of mine: ag/838200
However, I somehow managed to create a CL that could not be merged
(it complains about "this change depends on changes that are not ready").
It's likely because I tried to revert an erroneous change Andy
made via git commands, and probably did something wrong there.

Anyway, I've copied my former CL exactly, but without cherry-picking,
so it's now a new independent CL that should be mergeable without
problem.

Bug: 21209207
Change-Id: Ib5c6e031f9a3e43ab80b05bfe1edbfd81d83e54d
---
 docs/html/training/training_toc.cs        |  4 ++
 docs/html/training/tv/playback/index.jd   |  3 ++
 docs/html/training/tv/playback/options.jd | 66 +++++++++++++++++++++++
 3 files changed, 73 insertions(+)
 create mode 100644 docs/html/training/tv/playback/options.jd

diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs
index 9e156d0821d3b..b5ecf5cf6a471 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 e39e34a0e971e..43c6d41e09c19 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 0000000000000..c65343df68056
--- /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>
+