Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit bfc8636d authored by Daniel Yu's avatar Daniel Yu
Browse files

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
parent ad12e4d1

docs/html/training/training_toc.cs

+4 −0
Original line number Diff line number Diff line
@@ -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>

docs/html/training/tv/playback/index.jd

+3 −0
Original line number Diff line number Diff line
@@ -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>

docs/html/training/tv/playback/options.jd

0 → 100644
+66 −0
Original line number Diff line number Diff line 
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>