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

Commit f666355b authored by Joe Fernandez's avatar Joe Fernandez
Browse files

docs: migrate TV Playback app content

Change-Id: I851dac6423cba3b76c85e1ac5b6c03a98272d868
parent d86a2f5b
Loading
Loading
Loading
Loading
+18 −0
Original line number Diff line number Diff line
@@ -876,6 +876,24 @@ include the action bar on devices running Android 2.1 or higher."
        </ul>
      </li>

      <li class="nav-section">
        <div class="nav-section-header">
          <a href="<?cs var:toroot ?>training/tv/playback/index.html"
             description="How to build apps that provide media catalogs and play content.">
             Building TV Playback Apps</a>
        </div>
        <ul>
          <li>
            <a href="<?cs var:toroot ?>training/tv/playback/browse.html">
              Creating a Catalog Browser</a>
          </li>
          <li>
            <a href="<?cs var:toroot ?>training/tv/playback/details.html">
              Building a Details View</a>
          </li>
        </ul>
      </li>

    </ul>
  </li>
  <!-- End: Building for TV -->
+81 −49
Original line number Diff line number Diff line
page.title=BrowseFragment
page.title=Creating a Catalog Browser
page.tags="browsefragment","presenter","backgroundmanager"

trainingnavtop=true

@jd:body

<div id="qv-wrapper">
<div id="qv">
  <h2>In this document</h2>
<div id="tb-wrapper">
<div id="tb">
  <h2>This lesson teaches you to</h2>
  <ol>
    <li><a href="#layout">Media Browse Layout</a></li>
    <li><a href="#lists">Displaying Media Lists</a></li>
    <li><a href="#background">Updating the Background</a></li>
    <li><a href="#layout">Create a Media Browse Layout</a></li>
    <li><a href="#lists">Display Media Lists</a></li>
    <li><a href="#background">Update the Background</a></li>
  </ol>

</div>
</div>

<p>The <a href="{@docRoot}preview/tv/start/index.html#tv-libraries">Leanback support library</a>
  provides several APIs for displaying and browsing media catalogs
  on the TV devices. This guide discusses how to use the classes provided by this library to
  implement a user interface for browsing music or videos from your app's media catalog.</p>
<p>
  Media apps that run on TV need to allow users to browse its content offerings, make a
  selection, and start playing content. The content browsing experience for apps of this type
  should be simple and intuitive, as well as visually pleasing and engaging.
</p>

<p>
  This lesson discusses how to use the classes provided by the <a href=
  "{@docRoot}tools/support-library/features.html#v17-leanback">v17 leanback support library</a> to
  implement a user interface for browsing music or videos from your app's media catalog.
</p>

<h2 id="layout">Media Browse Layout</h2>

<p>The {@code BrowseFragment} class in the Leanback support library allows you to create a primary
  layout for browsing categories and rows of media items with a minimum of code. The following
  example shows how to create a layout that contains a {@code BrowseFragment}:</p>
<h2 id="layout">Create a Media Browse Layout</h2>

<p>
  The {@link android.support.v17.leanback.app.BrowseFragment} class in the leanback library
  allows you to create a primary layout for browsing categories and rows of media items with a
  minimum of code. The following example shows how to create a layout that contains a {@link
  android.support.v17.leanback.app.BrowseFragment}:
</p>

<pre>
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
@@ -42,10 +55,13 @@ page.title=BrowseFragment
&lt;/LinearLayout&gt;
</pre>

<p>In order to work with this layout in an activity, retrieve the {@code BrowseFragment} element
  from the layout. Use the methods in {@code BrowseFragment} to set display parameters such as the
  icon, title and whether category headers are enabled. The following code sample demonstrates how
  to set the layout parameters for a {@code BrowseFragment} in a layout:</p>
<p>
  In order to work with this layout in an activity, retrieve the {@link
  android.support.v17.leanback.app.BrowseFragment} element from the layout. Use the methods in this
  class to set display parameters such as the icon, title, and whether category headers are enabled.
  The following code sample demonstrates how to set the layout parameters for a {@link
  android.support.v17.leanback.app.BrowseFragment} in a layout:
</p>

<pre>
public class BrowseMediaActivity extends Activity {
@@ -66,7 +82,8 @@ public class BrowseMediaActivity extends Activity {
        // Set display parameters for the BrowseFragment
        mBrowseFragment.setHeadersState(BrowseFragment.HEADERS_ENABLED);
        mBrowseFragment.setTitle(getString(R.string.app_name));
        mBrowseFragment.setBadgeDrawable(getResources().getDrawable(R.drawable.ic_launcher));
        mBrowseFragment.setBadgeDrawable(getResources().getDrawable(
                R.drawable.ic_launcher));
        mBrowseFragment.setBrowseParams(params);

    }
@@ -76,13 +93,18 @@ public class BrowseMediaActivity extends Activity {

<h2 id="lists">Displaying Media Lists</h2>

<p>The {@code BrowseFragment} allows you to define and display browsable media content categories and
  media items from a media catalog using adapters and presenters. Adapters enable you to connect to
  local or online data sources that contain your media catalog information. Presenter classes hold
  data about media items and provide layout information for displaying an item on screen.</p>
<p>
  The {@link android.support.v17.leanback.app.BrowseFragment} allows you to define and display
  browsable media content categories and media items from a media catalog using adapters and
  presenters. Adapters enable you to connect to local or online data sources that contain your
  media catalog information. Presenters hold data about media items and provide layout information
  for displaying an item on screen.
</p>

<p>The following example code shows an implementation of a presenter for displaying string
  data:</p>
<p>
  The following example code shows an implementation of a {@link
  android.support.v17.leanback.widget.Presenter} for displaying string data:
</p>

<pre>
public class StringPresenter extends Presenter {
@@ -107,10 +129,13 @@ public class StringPresenter extends Presenter {
}
</pre>

<p>Once you have constructed a presenter class for your media items, you can build and attach an
  adapter to the {@code BrowseFragment} to display those items on screen for browsing by the user. The
  following example code demonstrates how to construct an adapter to display categories and items
  in those categories using the StringPresenter class shown in the previous code example:</p>
<p>
  Once you have constructed a presenter class for your media items, you can build and attach an
  adapter to the {@link android.support.v17.leanback.app.BrowseFragment} to display those items on
  screen for browsing by the user. The following example code demonstrates how to construct an
  adapter to display categories and items in those categories using the {@code StringPresenter}
  class shown in the previous code example:
</p>

<pre>
private ArrayObjectAdapter mRowsAdapter;
@@ -140,21 +165,26 @@ private void buildRowsAdapter() {
}
</pre>

<p>This example shows a static implementation of the adapters. A typical media browsing
  application uses data from an online database or web service. For an example of a browsing
  application that uses data retrieved from the web, see the
  <a href="http://github.com/googlesamples/androidtv-leanback">Android TV</a> sample app.</p>

<p>
  This example shows a static implementation of the adapters. A typical media browsing application
  uses data from an online database or web service. For an example of a browsing application that
  uses data retrieved from the web, see the
  <a href="http://github.com/googlesamples/androidtv-leanback">Android TV</a> sample app.
</p>

<h2 id="background">Updating the Background</h2>
<h2 id="background">Update the Background</h2>

<p>In order to add visual interest to a media-browsing app on TV, you can update the background
  image as users browse through content. This technique can make interaction with your app feel more
  cinematic and enjoyable for users.</p>
<p>
  In order to add visual interest to a media-browsing app on TV, you can update the background
  image as users browse through content. This technique can make interaction with your app feel
  more cinematic and enjoyable for users.
</p>

<p>The Leanback support library provides a {@code BackgroundManager} class for changing the
  background of your TV app activity. The following example shows how to create a simple method
  for updating the background within your TV app activity:</p>
<p>
  The Leanback support library provides a {@link android.support.v17.leanback.app.BackgroundManager}
  class for changing the background of your TV app activity. The following example shows how to
  create a simple method for updating the background within your TV app activity:
</p>

<pre>
protected void updateBackground(Drawable drawable) {
@@ -162,19 +192,21 @@ protected void updateBackground(Drawable drawable) {
}
</pre>

<p>Many of the existing media-browse apps automatically update the background as the user
  navigates through media listings. In order to do this, you can set up a selection listener to
  automatically update the background based on the user's current selection. The following example
  shows you how to set up an {@code OnItemSelectedListener}
  class to catch selection events and update the background:</p>
<p>
  Many of the existing media-browse apps automatically update the background as the user navigates
  through media listings. In order to do this, you can set up a selection listener to automatically
  update the background based on the user's current selection. The following example shows you how
  to set up an {@link android.support.v17.leanback.widget.OnItemViewSelectedListener} class to
  catch selection events and update the background:
</p>

<pre>
protected void clearBackground() {
    BackgroundManager.getInstance(this).setDrawable(mDefaultBackground);
}

protected OnItemSelectedListener getDefaultItemSelectedListener() {
    return new OnItemSelectedListener() {
protected OnItemViewSelectedListener getDefaultItemViewSelectedListener() {
    return new OnItemViewSelectedListener() {
        &#64;Override
        public void onItemSelected(Object item, Row row) {
            if (item instanceof Movie ) {
+82 −49
Original line number Diff line number Diff line
page.title=DetailFragment
page.title=Building a Details View
page.tags="detailsfragment"

trainingnavtop=true

@jd:body

<div id="qv-wrapper">
<div id="qv">
  <h2>In this document</h2>
<div id="tb-wrapper">
<div id="tb">
  <h2>This lesson teaches you to</h2>
  <ol>
    <li><a href="#details-presenter">Build a Details Presenter</a></li>
    <li><a href="#details-fragment">Extend the Details Fragment</a>
      <li><a href="#activity">Creating a Details Activity</a></li>
      <li><a href="#item-listener">Listener for Clicked Items</a></li>
    </li>
    <li><a href="#activity">Create a Details Activity</a></li>
    <li><a href="#item-listener">Define a Listener for Clicked Items</a></li>
  </ol>
</div>
</div>

<p>The media browsing interface classes provided by the
  <a href="{@docRoot}preview/tv/start/index.html#tv-libraries">Leanback support library</a>
<p>
  The media browsing interface classes provided by the <a href=
  "{@docRoot}tools/support-library/features.html#v17-leanback">v17 leanback support library</a>
  include classes for displaying additional information about a media item, such as a description
  or reviews, and for taking action on that item, such as purchasing it or playing its content. This
  section discusses how to create a presenter class for media item details and extend the
  {@code DetailsFragment} class to implement a details view for a media item when it
  is selected by a user.
  or reviews, and for taking action on that item, such as purchasing it or playing its content.
</p>

<p>
  This lesson discusses how to create a presenter class for media item details, and how to extend
  the {@link android.support.v17.leanback.app.DetailsFragment} class to implement a details view
  for a media item when it is selected by a user.
</p>

<p class="note">
  <strong>Note:</strong> The implementation example shown here uses an additional activity to
  contain the {@code DetailsFragment}. However, it is possible to avoid creating a second activity
  by replacing the current {@code BrowseFragment} with a {@code DetailsFragment} within the <em>same</em>
  activity using fragment transactions. For more information on using fragment transactions, see the
  <a href="{@docRoot}training/basics/fragments/fragment-ui.html#Replace">Building a Dynamic
    UI with Fragments</a> training.
  contain the {@link android.support.v17.leanback.app.DetailsFragment}. However, it is possible to
  avoid creating a second activity by replacing the current {@link
  android.support.v17.leanback.app.BrowseFragment} with a {@link
  android.support.v17.leanback.app.DetailsFragment} within the <em>same</em> activity using
  fragment transactions. For more information on using fragment transactions, see the <a href=
  "{@docRoot}training/basics/fragments/fragment-ui.html#Replace">Building a Dynamic UI with
  Fragments</a> training.
</p>


<h2 id="details-presenter">Build a Details Presenter</h2>

<p>In the media browsing framework provided for by the leanback support library, you use
  presenter objects to control the display of data on screen, including media item details. The
  framework provides the {@code AbstractDetailsDescriptionPresenter} class for this purpose, which
  is a nearly complete implementation of the presenter for media item details. All you have to do is
  implement the {@code onBindDescription()} method to bind the view fields to your data objects, as shown in
  the following code sample:</p>
<p>
  In the media browsing framework provided by the leanback library, you use presenter
  objects to control the display of data on screen, including media item details. The framework
  provides the {@link android.support.v17.leanback.widget.AbstractDetailsDescriptionPresenter}
  class for this purpose, which is a nearly complete implementation of the presenter for media item
  details. All you have to do is implement the {@link
  android.support.v17.leanback.widget.AbstractDetailsDescriptionPresenter#onBindDescription
  onBindDescription()} method to bind the view fields to your data objects, as shown in the
  following code sample:
</p>

<pre>
public class DetailsDescriptionPresenter
@@ -69,13 +81,18 @@ public class DetailsDescriptionPresenter

<h2 id="details-fragment">Extend the Details Fragment</h2>

<p>When you use the {@code DetailsFragment} class for displaying your media item details, you
  extend that class to provide additional content such as a preview image and actions for the media
  item. You can also provide additional content, such as a list of related media items.</p>
<p>
  When using the {@link android.support.v17.leanback.app.DetailsFragment} class for displaying
  your media item details, extend that class to provide additional content such as a preview
  image and actions for the media item. You can also provide additional content, such as a list of
  related media items.
</p>

<p>The following example code demonstrates how to use the presenter class you created in the
  previous section, add a preview image and actions for the media item being viewed. This example
  also shows the addition of a related media items row, which appears below the details listing.</p>
<p>
  The following example code demonstrates how to use the presenter class shown in the
  previous section, to add a preview image and actions for the media item being viewed. This example
  also shows the addition of a related media items row, which appears below the details listing.
</p>

<pre>
public class MediaItemDetailsFragment extends DetailsFragment {
@@ -126,15 +143,21 @@ public class MediaItemDetailsFragment extends DetailsFragment {
</pre>


<h3 id="activity">Creating a Details Activity</h3>
<h3 id="activity">Create a Details Activity</h3>

<p>Fragments such as the {@code DetailsFragment} must be contained within an activity in order
  to be used for display. Creating an activity for your details view, separate from the browse
  activity, enables you to invoke your details view using an Intent. This section explains how to
  build an activity to contain your implementation of the detail view for your media items.</p>
<p>
  Fragments such as the {@link android.support.v17.leanback.app.DetailsFragment} must be contained
  within an activity in order to be used for display. Creating an activity for your details view,
  separate from the browse activity, enables you to invoke your details view using an
  {@link android.content.Intent}. This
  section explains how to build an activity to contain your implementation of the detail view for
  your media items.
</p>

<p>Start creating the details activity by building a layout that references your implementation
  of the {@code DetailsFragment}:</p>
<p>
  Start creating the details activity by building a layout that references your implementation of
  the {@link android.support.v17.leanback.app.DetailsFragment}:
</p>

<pre>
&lt;!-- file: res/layout/details.xml --&gt;
@@ -147,7 +170,9 @@ public class MediaItemDetailsFragment extends DetailsFragment {
/&gt;
</pre>

<p>Next, create an activity class that uses the layout shown in the previous code example:</p>
<p>
  Next, create an activity class that uses the layout shown in the previous code example:
</p>

<pre>
public class DetailsActivity extends Activity
@@ -160,8 +185,10 @@ public class DetailsActivity extends Activity
}
</pre>

<p>Finally, add this new activity to the manifest. Remember to apply the Leanback theme to
  ensure that the user interface is consistent with the media browse activity:</p>
<p>
  Finally, add this new activity to the manifest. Remember to apply the Leanback theme to ensure
  that the user interface is consistent with the media browse activity:
</p>

<pre>
&lt;application&gt;
@@ -175,15 +202,21 @@ public class DetailsActivity extends Activity
</pre>


<h3 id="item-listener">Listener for Clicked Items</h3>
<h3 id="item-listener">Define a Listener for Clicked Items</h3>

<p>After you have implemented the {@code DetailsFragment}, you must modify your main media
  browsing view to move to your details view when a user clicks on a media item. In order to enable
  this behavior, add an {@code OnItemClickedListener} object to the BrowseFragment that fires an
  intent to start the item details activity.</p>
<p>
  After you have implemented the {@link android.support.v17.leanback.app.DetailsFragment},
  modify your main media browsing view to move to your details view when a user clicks on a media
  item. In order to enable this behavior, add an
  {@link android.support.v17.leanback.widget.OnItemViewClickedListener} object to the
  {@link android.support.v17.leanback.app.BrowseFragment} that fires an intent to start the item
  details activity.
</p>

<p>The following example shows how to implement a listener to start the details view when a user
  clicks a media item in the main media browsing activity:</p>
<p>
  The following example shows how to implement a listener to start the details view when a user
  clicks a media item in the main media browsing activity:
</p>

<pre>
public class BrowseMediaActivity extends Activity {
@@ -197,8 +230,8 @@ public class BrowseMediaActivity extends Activity {
        buildRowsAdapter();

        // add a listener for selected items
        mBrowseFragment.setOnItemClickedListener(
            new OnItemClickedListener() {
        mBrowseFragment.OnItemViewClickedListener(
            new OnItemViewClickedListener() {
                &#64;Override
                public void onItemClicked(Object item, Row row) {
                    System.out.println("Media Item clicked: " + item.toString());
+49 −0
Original line number Diff line number Diff line
page.title=Building TV Playback Apps
page.tags="leanback"

startpage=true

@jd:body

<div id="tb-wrapper">
<div id="tb">
  <h2>Dependencies and Prerequisites</h2>
  <ul>
    <li>Android 5.0 (API level 21) or higher</li>
  </ul>
  <h2>You should also read</h2>
  <ul>
    <li><a href="{@docRoot}design/tv/index.html">
      Design for TV</a></li>
  </ul>
</div>
</div>

<p>
  Browsing and playing media files is frequently part of the user experience provided by a TV app.
  Building such an experience from scratch, while making sure that it is fast, fluid, and attractive
  can be quite challenging. Whether your app provides access to a small or large media catalog,
  it is important to allow users to quickly browse options and get to the content they want.
</p>

<p>
  The Android framework provides classes for building user interfaces for these types of apps with
  the <a href="{@docRoot}tools/support-library/features.html#v17-leanback">v17 leanback support
  library</a>. This library provides a framework of classes for creating an efficient and familiar
  interface for browsing and playing media files with minimal coding. The classes are designed
  be extended and customized so you can create an experience that is unique to your app.
</p>

<p>This class shows you how to build a TV app for browsing and playing media content using the Leanback
  support libraries for TV.</p>

<h2>Topics</h2>

<dl>
  <dt><b><a href="browse.html">Creating a Catalog Browser</a></b></dt>
    <dd>Learn how to use the Leanback support library to build a browsing interface for media
      catalogs.</dd>

  <dt><b><a href="details.html">Building a Details View</a></b></dt>
    <dd>Learn how to use the Leanback support library to build a details page for media items.</dd>
</dl>