Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: migrate TV Playback app content

Browse Source 
Change-Id: I851dac6423cba3b76c85e1ac5b6c03a98272d868
This commit is contained in:
Joe Fernandez
2014-10-02 10:13:16 -07:00
parent d86a2f5b34
commit f666355b2d
4 changed files with 230 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/html/training/training_toc.cs
View File

@@ -876,6 +876,24 @@ include the action bar on devices running Android 2.1 or higher."
</ul> </ul>
</li> </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> </ul>
</li> </li>
<!-- End: Building for TV --> <!-- End: Building for TV -->

130
docs/html/preview/tv/ui/browse.jd → docs/html/training/tv/playback/browse.jd
View File

@@ -1,30 +1,43 @@
page.title=BrowseFragment page.title=Creating a Catalog Browser
page.tags="browsefragment","presenter","backgroundmanager"
trainingnavtop=true
@jd:body @jd:body
<div id="qv-wrapper"> <div id="tb-wrapper">
<div id="qv"> <div id="tb">
<h2>In this document</h2> <h2>This lesson teaches you to</h2>
<ol> <ol>
<li><a href="#layout">Media Browse Layout</a></li> <li><a href="#layout">Create a Media Browse Layout</a></li>
<li><a href="#lists">Displaying Media Lists</a></li> <li><a href="#lists">Display Media Lists</a></li>
<li><a href="#background">Updating the Background</a></li> <li><a href="#background">Update the Background</a></li>
</ol> </ol>
</div> </div>
</div> </div>
<p>The <a href="{@docRoot}preview/tv/start/index.html#tv-libraries">Leanback support library</a> <p>
provides several APIs for displaying and browsing media catalogs Media apps that run on TV need to allow users to browse its content offerings, make a
on the TV devices. This guide discusses how to use the classes provided by this library to selection, and start playing content. The content browsing experience for apps of this type
implement a user interface for browsing music or videos from your app's media catalog.</p> 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> <h2 id="layout">Create a Media Browse Layout</h2>
<p>The {@code BrowseFragment} class in the Leanback support library allows you to create a primary <p>
layout for browsing categories and rows of media items with a minimum of code. The following The {@link android.support.v17.leanback.app.BrowseFragment} class in the leanback library
example shows how to create a layout that contains a {@code BrowseFragment}:</p> 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> <pre>
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" &lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
@@ -42,10 +55,13 @@ page.title=BrowseFragment
&lt;/LinearLayout&gt; &lt;/LinearLayout&gt;
</pre> </pre>
<p>In order to work with this layout in an activity, retrieve the {@code BrowseFragment} element <p>
from the layout. Use the methods in {@code BrowseFragment} to set display parameters such as the In order to work with this layout in an activity, retrieve the {@link
icon, title and whether category headers are enabled. The following code sample demonstrates how android.support.v17.leanback.app.BrowseFragment} element from the layout. Use the methods in this
to set the layout parameters for a {@code BrowseFragment} in a layout:</p> 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> <pre>
public class BrowseMediaActivity extends Activity { public class BrowseMediaActivity extends Activity {
@@ -66,7 +82,8 @@ public class BrowseMediaActivity extends Activity {
// Set display parameters for the BrowseFragment // Set display parameters for the BrowseFragment
mBrowseFragment.setHeadersState(BrowseFragment.HEADERS_ENABLED); mBrowseFragment.setHeadersState(BrowseFragment.HEADERS_ENABLED);
mBrowseFragment.setTitle(getString(R.string.app_name)); 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); mBrowseFragment.setBrowseParams(params);
} }
@@ -76,13 +93,18 @@ public class BrowseMediaActivity extends Activity {
<h2 id="lists">Displaying Media Lists</h2> <h2 id="lists">Displaying Media Lists</h2>
<p>The {@code BrowseFragment} allows you to define and display browsable media content categories and <p>
media items from a media catalog using adapters and presenters. Adapters enable you to connect to The {@link android.support.v17.leanback.app.BrowseFragment} allows you to define and display
local or online data sources that contain your media catalog information. Presenter classes hold browsable media content categories and media items from a media catalog using adapters and
data about media items and provide layout information for displaying an item on screen.</p> 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 <p>
data:</p> The following example code shows an implementation of a {@link
android.support.v17.leanback.widget.Presenter} for displaying string data:
</p>
<pre> <pre>
public class StringPresenter extends Presenter { public class StringPresenter extends Presenter {
@@ -107,10 +129,13 @@ public class StringPresenter extends Presenter {
} }
</pre> </pre>
<p>Once you have constructed a presenter class for your media items, you can build and attach an <p>
adapter to the {@code BrowseFragment} to display those items on screen for browsing by the user. The Once you have constructed a presenter class for your media items, you can build and attach an
following example code demonstrates how to construct an adapter to display categories and items adapter to the {@link android.support.v17.leanback.app.BrowseFragment} to display those items on
in those categories using the StringPresenter class shown in the previous code example:</p> 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> <pre>
private ArrayObjectAdapter mRowsAdapter; private ArrayObjectAdapter mRowsAdapter;
@@ -140,21 +165,26 @@ private void buildRowsAdapter() {
} }
</pre> </pre>
<p>This example shows a static implementation of the adapters. A typical media browsing <p>
application uses data from an online database or web service. For an example of a browsing This example shows a static implementation of the adapters. A typical media browsing application
application that uses data retrieved from the web, see the uses data from an online database or web service. For an example of a browsing application that
<a href="http://github.com/googlesamples/androidtv-leanback">Android TV</a> sample app.</p> 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">Update the Background</h2>
<h2 id="background">Updating 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 <p>
image as users browse through content. This technique can make interaction with your app feel more The Leanback support library provides a {@link android.support.v17.leanback.app.BackgroundManager}
cinematic and enjoyable for users.</p> 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>The Leanback support library provides a {@code BackgroundManager} class for changing the </p>
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> <pre>
protected void updateBackground(Drawable drawable) { protected void updateBackground(Drawable drawable) {
@@ -162,19 +192,21 @@ protected void updateBackground(Drawable drawable) {
} }
</pre> </pre>
<p>Many of the existing media-browse apps automatically update the background as the user <p>
navigates through media listings. In order to do this, you can set up a selection listener to Many of the existing media-browse apps automatically update the background as the user navigates
automatically update the background based on the user's current selection. The following example through media listings. In order to do this, you can set up a selection listener to automatically
shows you how to set up an {@code OnItemSelectedListener} update the background based on the user's current selection. The following example shows you how
class to catch selection events and update the background:</p> to set up an {@link android.support.v17.leanback.widget.OnItemViewSelectedListener} class to
catch selection events and update the background:
</p>
<pre> <pre>
protected void clearBackground() { protected void clearBackground() {
BackgroundManager.getInstance(this).setDrawable(mDefaultBackground); BackgroundManager.getInstance(this).setDrawable(mDefaultBackground);
} }
protected OnItemSelectedListener getDefaultItemSelectedListener() { protected OnItemViewSelectedListener getDefaultItemViewSelectedListener() {
return new OnItemSelectedListener() { return new OnItemViewSelectedListener() {
&#64;Override &#64;Override
public void onItemSelected(Object item, Row row) { public void onItemSelected(Object item, Row row) {
if (item instanceof Movie ) { if (item instanceof Movie ) {

131
docs/html/preview/tv/ui/details.jd → docs/html/training/tv/playback/details.jd
View File

@@ -1,47 +1,59 @@
page.title=DetailFragment page.title=Building a Details View
page.tags="detailsfragment"
trainingnavtop=true
@jd:body @jd:body
<div id="qv-wrapper"> <div id="tb-wrapper">
<div id="qv"> <div id="tb">
<h2>In this document</h2> <h2>This lesson teaches you to</h2>
<ol> <ol>
<li><a href="#details-presenter">Build a Details Presenter</a></li> <li><a href="#details-presenter">Build a Details Presenter</a></li>
<li><a href="#details-fragment">Extend the Details Fragment</a> <li><a href="#details-fragment">Extend the Details Fragment</a>
<li><a href="#activity">Creating a Details Activity</a></li> <li><a href="#activity">Create a Details Activity</a></li>
<li><a href="#item-listener">Listener for Clicked Items</a></li> <li><a href="#item-listener">Define a Listener for Clicked Items</a></li>
</li>
</ol> </ol>
</div> </div>
</div> </div>
<p>The media browsing interface classes provided by the <p>
<a href="{@docRoot}preview/tv/start/index.html#tv-libraries">Leanback support library</a> 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 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 or reviews, and for taking action on that item, such as purchasing it or playing its content.
section discusses how to create a presenter class for media item details and extend the </p>
{@code DetailsFragment} class to implement a details view for a media item when it
is selected by a user. <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>
<p class="note"> <p class="note">
<strong>Note:</strong> The implementation example shown here uses an additional activity to <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 contain the {@link android.support.v17.leanback.app.DetailsFragment}. However, it is possible to
by replacing the current {@code BrowseFragment} with a {@code DetailsFragment} within the <em>same</em> avoid creating a second activity by replacing the current {@link
activity using fragment transactions. For more information on using fragment transactions, see the android.support.v17.leanback.app.BrowseFragment} with a {@link
<a href="{@docRoot}training/basics/fragments/fragment-ui.html#Replace">Building a Dynamic android.support.v17.leanback.app.DetailsFragment} within the <em>same</em> activity using
UI with Fragments</a> training. 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> </p>
<h2 id="details-presenter">Build a Details Presenter</h2> <h2 id="details-presenter">Build a Details Presenter</h2>
<p>In the media browsing framework provided for by the leanback support library, you use <p>
presenter objects to control the display of data on screen, including media item details. The In the media browsing framework provided by the leanback library, you use presenter
framework provides the {@code AbstractDetailsDescriptionPresenter} class for this purpose, which objects to control the display of data on screen, including media item details. The framework
is a nearly complete implementation of the presenter for media item details. All you have to do is provides the {@link android.support.v17.leanback.widget.AbstractDetailsDescriptionPresenter}
implement the {@code onBindDescription()} method to bind the view fields to your data objects, as shown in class for this purpose, which is a nearly complete implementation of the presenter for media item
the following code sample:</p> 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> <pre>
public class DetailsDescriptionPresenter public class DetailsDescriptionPresenter
@@ -69,13 +81,18 @@ public class DetailsDescriptionPresenter
<h2 id="details-fragment">Extend the Details Fragment</h2> <h2 id="details-fragment">Extend the Details Fragment</h2>
<p>When you use the {@code DetailsFragment} class for displaying your media item details, you <p>
extend that class to provide additional content such as a preview image and actions for the media When using the {@link android.support.v17.leanback.app.DetailsFragment} class for displaying
item. You can also provide additional content, such as a list of related media items.</p> 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 <p>
previous section, add a preview image and actions for the media item being viewed. This example The following example code demonstrates how to use the presenter class shown in the
also shows the addition of a related media items row, which appears below the details listing.</p> 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> <pre>
public class MediaItemDetailsFragment extends DetailsFragment { public class MediaItemDetailsFragment extends DetailsFragment {
@@ -126,15 +143,21 @@ public class MediaItemDetailsFragment extends DetailsFragment {
</pre> </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 <p>
to be used for display. Creating an activity for your details view, separate from the browse Fragments such as the {@link android.support.v17.leanback.app.DetailsFragment} must be contained
activity, enables you to invoke your details view using an Intent. This section explains how to within an activity in order to be used for display. Creating an activity for your details view,
build an activity to contain your implementation of the detail view for your media items.</p> 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 <p>
of the {@code DetailsFragment}:</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> <pre>
&lt;!-- file: res/layout/details.xml --&gt; &lt;!-- file: res/layout/details.xml --&gt;
@@ -147,7 +170,9 @@ public class MediaItemDetailsFragment extends DetailsFragment {
/&gt; /&gt;
</pre> </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> <pre>
public class DetailsActivity extends Activity public class DetailsActivity extends Activity
@@ -160,8 +185,10 @@ public class DetailsActivity extends Activity
} }
</pre> </pre>
<p>Finally, add this new activity to the manifest. Remember to apply the Leanback theme to <p>
ensure that the user interface is consistent with the media browse activity:</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> <pre>
&lt;application&gt; &lt;application&gt;
@@ -175,15 +202,21 @@ public class DetailsActivity extends Activity
</pre> </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 <p>
browsing view to move to your details view when a user clicks on a media item. In order to enable After you have implemented the {@link android.support.v17.leanback.app.DetailsFragment},
this behavior, add an {@code OnItemClickedListener} object to the BrowseFragment that fires an modify your main media browsing view to move to your details view when a user clicks on a media
intent to start the item details activity.</p> 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 <p>
clicks a media item in the main media browsing activity:</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> <pre>
public class BrowseMediaActivity extends Activity { public class BrowseMediaActivity extends Activity {
@@ -197,8 +230,8 @@ public class BrowseMediaActivity extends Activity {
buildRowsAdapter(); buildRowsAdapter();
// add a listener for selected items // add a listener for selected items
mBrowseFragment.setOnItemClickedListener( mBrowseFragment.OnItemViewClickedListener(
new OnItemClickedListener() { new OnItemViewClickedListener() {
&#64;Override &#64;Override
public void onItemClicked(Object item, Row row) { public void onItemClicked(Object item, Row row) {
System.out.println("Media Item clicked: " + item.toString()); System.out.println("Media Item clicked: " + item.toString());

49
docs/html/training/tv/playback/index.jd Normal file
View File

@@ -0,0 +1,49 @@
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>