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>
</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 -->

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
<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>
<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
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>
<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">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
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 ) {

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