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
diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs
index 9e156d0..b5ecf5c 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 e39e34a..43c6d41 100644
--- a/docs/html/training/tv/playback/index.jd
+++ b/docs/html/training/tv/playback/index.jd
@@ -64,4 +64,7 @@
<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 0000000..c65343d
--- /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>
+@Override
+public void onPause() {
+ super.onPause();
+ if (mVideoView.isPlaying()) {
+ // Argument equals true to notify the system that the activity
+ // wishes to be visible behind other translucent activities
+ if (! requestVisibleBehind(true)) {
+ // App-specific method to stop playback and release resources
+ // because call to requestVisibleBehind(true) failed
+ stopPlayback();
+ }
+ } else {
+ // Argument equals false because the activity is not playing
+ requestVisibleBehind(false);
+ }
+}
+
+@Override
+public void onVisibleBehindCanceled() {
+ // App-specific method to stop playback and release resources
+ stopPlayback();
+ super.onVisibleBehindCanceled();
+}
+</pre>
+