The Leanback support library - 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.
++ 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. +
+ ++ This lesson discusses how to use the classes provided by the v17 leanback support library to + implement a user interface for browsing music or videos from your app's media catalog. +
-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}:
++ 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}: +
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" @@ -42,10 +55,13 @@ page.title=BrowseFragment </LinearLayout>-
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:
++ 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: +
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 {
Displaying Media Lists
-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.
+
+ 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.
+
-The following example code shows an implementation of a presenter for displaying string
- data:
+
+ The following example code shows an implementation of a {@link
+ android.support.v17.leanback.widget.Presenter} for displaying string data:
+
public class StringPresenter extends Presenter {
@@ -107,10 +129,13 @@ public class StringPresenter extends Presenter {
}
-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:
+
+ 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:
+
private ArrayObjectAdapter mRowsAdapter;
@@ -140,21 +165,26 @@ private void buildRowsAdapter() {
}
-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
- Android TV sample app.
+
+ 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
+ Android TV sample app.
+
+Update the Background
-Updating the Background
+
+ 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.
+
-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.
-
-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:
+
+ 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:
+
protected void updateBackground(Drawable drawable) {
@@ -162,19 +192,21 @@ protected void updateBackground(Drawable drawable) {
}
-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:
+
+ 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:
+
protected void clearBackground() {
BackgroundManager.getInstance(this).setDrawable(mDefaultBackground);
}
-protected OnItemSelectedListener getDefaultItemSelectedListener() {
- return new OnItemSelectedListener() {
+protected OnItemViewSelectedListener getDefaultItemViewSelectedListener() {
+ return new OnItemViewSelectedListener() {
@Override
public void onItemSelected(Object item, Row row) {
if (item instanceof Movie ) {
diff --git a/docs/html/preview/tv/ui/details.jd b/docs/html/training/tv/playback/details.jd
similarity index 54%
rename from docs/html/preview/tv/ui/details.jd
rename to docs/html/training/tv/playback/details.jd
index 8b8fa8b5b4bd2..6391a495d2f37 100644
--- a/docs/html/preview/tv/ui/details.jd
+++ b/docs/html/training/tv/playback/details.jd
@@ -1,47 +1,59 @@
-page.title=DetailFragment
+page.title=Building a Details View
+page.tags="detailsfragment"
+
+trainingnavtop=true
@jd:body
-
-
- In this document
+
+
+ This lesson teaches you to
-The media browsing interface classes provided by the
- Leanback support library
+
+ The media browsing interface classes provided by the v17 leanback support library
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.
+
+
+
+ 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.
Note: 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 same
- activity using fragment transactions. For more information on using fragment transactions, see the
- Building a Dynamic
- UI with Fragments 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 same activity using
+ fragment transactions. For more information on using fragment transactions, see the Building a Dynamic UI with
+ Fragments training.
Build a Details Presenter
-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:
+
+ 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:
+
public class DetailsDescriptionPresenter
@@ -69,13 +81,18 @@ public class DetailsDescriptionPresenter
Extend the Details Fragment
-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.
+
+ 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.
+
-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.
+
+ 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.
+
public class MediaItemDetailsFragment extends DetailsFragment {
@@ -126,15 +143,21 @@ public class MediaItemDetailsFragment extends DetailsFragment {
-Creating a Details Activity
+Create a Details Activity
-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.
+
+ 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.
+
-Start creating the details activity by building a layout that references your implementation
- of the {@code DetailsFragment}:
+
+ Start creating the details activity by building a layout that references your implementation of
+ the {@link android.support.v17.leanback.app.DetailsFragment}:
+
<!-- file: res/layout/details.xml -->
@@ -147,7 +170,9 @@ public class MediaItemDetailsFragment extends DetailsFragment {
/>
-Next, create an activity class that uses the layout shown in the previous code example:
+
+ Next, create an activity class that uses the layout shown in the previous code example:
+
public class DetailsActivity extends Activity
@@ -160,8 +185,10 @@ public class DetailsActivity extends Activity
}
-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:
+
+ 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:
+
<application>
@@ -175,15 +202,21 @@ public class DetailsActivity extends Activity
-Listener for Clicked Items
+Define a Listener for Clicked Items
-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.
+
+ 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.
+
-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:
+
+ 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:
+
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() {
@Override
public void onItemClicked(Object item, Row row) {
System.out.println("Media Item clicked: " + item.toString());
diff --git a/docs/html/training/tv/playback/index.jd b/docs/html/training/tv/playback/index.jd
new file mode 100644
index 0000000000000..d7167e7e8aab0
--- /dev/null
+++ b/docs/html/training/tv/playback/index.jd
@@ -0,0 +1,49 @@
+page.title=Building TV Playback Apps
+page.tags="leanback"
+
+startpage=true
+
+@jd:body
+
+
+
+ Dependencies and Prerequisites
+
+ - Android 5.0 (API level 21) or higher
+
+ You should also read
+
+ -
+ Design for TV
+
+
+
+
+
+ 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.
+
+
+
+ The Android framework provides classes for building user interfaces for these types of apps with
+ the v17 leanback support
+ library. 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.
+
+
+This class shows you how to build a TV app for browsing and playing media content using the Leanback
+ support libraries for TV.
+
+Topics
+
+
+ - Creating a Catalog Browser
+ - Learn how to use the Leanback support library to build a browsing interface for media
+ catalogs.
+
+ - Building a Details View
+ - Learn how to use the Leanback support library to build a details page for media items.
+