blob: d6b97c17e2b6a30b503974f6e8a96e82d6381e9a [file] [log] [blame]
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<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>
<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>
<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>
&lt;LinearLayout xmlns:android=""
<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>
public class BrowseMediaActivity extends Activity {
public static final String TAG ="BrowseActivity";
protected BrowseFragment mBrowseFragment;
protected void onCreate(Bundle savedInstanceState) {
final FragmentManager fragmentManager = getFragmentManager();
<strong>mBrowseFragment = (BrowseFragment) fragmentManager.findFragmentById(;</strong>
// Set display parameters for the BrowseFragment
<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 following example code shows an implementation of a presenter for displaying string
public class StringPresenter extends Presenter {
private static final String TAG = "StringPresenter";
public ViewHolder onCreateViewHolder(ViewGroup parent) {
TextView textView = new TextView(parent.getContext());
return new ViewHolder(textView);
public void onBindViewHolder(ViewHolder viewHolder, Object item) {
((TextView) viewHolder.view).setText(item.toString());
public void onUnbindViewHolder(ViewHolder viewHolder) {
// no op
<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>
private ArrayObjectAdapter mRowsAdapter;
private static final int NUM_ROWS = 4;
protected void onCreate(Bundle savedInstanceState) {
private void buildRowsAdapter() {
mRowsAdapter = new ArrayObjectAdapter(new ListRowPresenter());
for (int i = 0; i &lt; NUM_ROWS; ++i) {
ArrayObjectAdapter listRowAdapter = new ArrayObjectAdapter(
new StringPresenter());
listRowAdapter.add("Media Item 1");
listRowAdapter.add("Media Item 2");
listRowAdapter.add("Media Item 3");
HeaderItem header = new HeaderItem(i, "Category " + i, null);
mRowsAdapter.add(new ListRow(header, listRowAdapter));
<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="">Android TV</a> sample app.</p>
<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>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>
protected void updateBackground(Drawable drawable) {
<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>
protected void clearBackground() {
protected OnItemSelectedListener getDefaultItemSelectedListener() {
return new OnItemSelectedListener() {
public void onItemSelected(Object item, Row row) {
if (item instanceof Movie ) {
URI uri = ((Movie)item).getBackdropURI();
} else {
<p class="note">
<strong>Note:</strong> The implementation above is a simple example shown for purposes of
illustration. When creating this function in your own app, you should consider running the
background update action in a separate thread for better performance. In addition, if you are
planning on updating the background in response to users scrolling through items, consider adding
a time to delay a background image update until the user settles on an item. This technique avoids
excessive background image updates.