From f666355b2d9dbffffa640aff7731a8ba8309eaaa Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Thu, 2 Oct 2014 10:13:16 -0700 Subject: docs: migrate TV Playback app content Change-Id: I851dac6423cba3b76c85e1ac5b6c03a98272d868 --- docs/html/preview/tv/ui/browse.jd | 198 ------------------------ docs/html/preview/tv/ui/details.jd | 214 -------------------------- docs/html/training/training_toc.cs | 18 +++ docs/html/training/tv/playback/browse.jd | 230 ++++++++++++++++++++++++++++ docs/html/training/tv/playback/details.jd | 247 ++++++++++++++++++++++++++++++ docs/html/training/tv/playback/index.jd | 49 ++++++ 6 files changed, 544 insertions(+), 412 deletions(-) delete mode 100644 docs/html/preview/tv/ui/browse.jd delete mode 100644 docs/html/preview/tv/ui/details.jd create mode 100644 docs/html/training/tv/playback/browse.jd create mode 100644 docs/html/training/tv/playback/details.jd create mode 100644 docs/html/training/tv/playback/index.jd diff --git a/docs/html/preview/tv/ui/browse.jd b/docs/html/preview/tv/ui/browse.jd deleted file mode 100644 index d6b97c17e2b6..000000000000 --- a/docs/html/preview/tv/ui/browse.jd +++ /dev/null @@ -1,198 +0,0 @@ -page.title=BrowseFragment - -@jd:body - -
- -
- -

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

- -

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

- -
-<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
-  android:layout_width="match_parent"
-  android:layout_height="match_parent"
-  android:orientation="vertical"
-  >
-
-  <fragment
-      android:name="android.support.v17.leanback.app.BrowseFragment"
-      android:id="@+id/browse_fragment"
-      android:layout_width="match_parent"
-      android:layout_height="match_parent"
-      />
-</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:

- -
-public class BrowseMediaActivity extends Activity {
-
-    public static final String TAG ="BrowseActivity";
-
-    protected BrowseFragment mBrowseFragment;
-
-    @Override
-    protected void onCreate(Bundle savedInstanceState) {
-        super.onCreate(savedInstanceState);
-        setContentView(R.layout.browse_fragment);
-
-        final FragmentManager fragmentManager = getFragmentManager();
-        mBrowseFragment = (BrowseFragment) fragmentManager.findFragmentById(
-                R.id.browse_fragment);
-
-        // 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.setBrowseParams(params);
-
-    }
-}
-
- - -

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 following example code shows an implementation of a presenter for displaying string - data:

- -
-public class StringPresenter extends Presenter {
-    private static final String TAG = "StringPresenter";
-
-    public ViewHolder onCreateViewHolder(ViewGroup parent) {
-        TextView textView = new TextView(parent.getContext());
-        textView.setFocusable(true);
-        textView.setFocusableInTouchMode(true);
-        textView.setBackground(
-                parent.getContext().getResources().getDrawable(R.drawable.text_bg));
-        return new ViewHolder(textView);
-    }
-
-    public void onBindViewHolder(ViewHolder viewHolder, Object item) {
-        ((TextView) viewHolder.view).setText(item.toString());
-    }
-
-    public void onUnbindViewHolder(ViewHolder viewHolder) {
-        // no op
-    }
-}
-
- -

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:

- -
-private ArrayObjectAdapter mRowsAdapter;
-private static final int NUM_ROWS = 4;
-
-@Override
-protected void onCreate(Bundle savedInstanceState) {
-    ...
-
-    buildRowsAdapter();
-}
-
-private void buildRowsAdapter() {
-    mRowsAdapter = new ArrayObjectAdapter(new ListRowPresenter());
-
-    for (int i = 0; i < 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));
-    }
-
-    mBrowseFragment.setAdapter(mRowsAdapter);
-}
-
- -

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.

- - -

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.

- -

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:

- -
-protected void updateBackground(Drawable drawable) {
-    BackgroundManager.getInstance(this).setDrawable(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:

- -
-protected void clearBackground() {
-    BackgroundManager.getInstance(this).setDrawable(mDefaultBackground);
-}
-
-protected OnItemSelectedListener getDefaultItemSelectedListener() {
-    return new OnItemSelectedListener() {
-        @Override
-        public void onItemSelected(Object item, Row row) {
-            if (item instanceof Movie ) {
-                URI uri = ((Movie)item).getBackdropURI();
-                updateBackground(uri);
-            } else {
-                clearBackground();
-            }
-        }
-    };
-}
-
- -

- Note: 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. -

diff --git a/docs/html/preview/tv/ui/details.jd b/docs/html/preview/tv/ui/details.jd deleted file mode 100644 index 8b8fa8b5b4bd..000000000000 --- a/docs/html/preview/tv/ui/details.jd +++ /dev/null @@ -1,214 +0,0 @@ -page.title=DetailFragment - -@jd:body - -
- -
- -

The media browsing interface classes provided by the - 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. -

- -

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

- - -

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:

- -
-public class DetailsDescriptionPresenter
-        extends AbstractDetailsDescriptionPresenter {
-
-    @Override
-    protected void onBindDescription(ViewHolder viewHolder, Object itemData) {
-        MyMediaItemDetails details = (MyMediaItemDetails) itemData;
-        // In a production app, the itemData object contains the information
-        // needed to display details for the media item:
-        // viewHolder.getTitle().setText(details.getShortTitle());
-
-        // Here we provide static data for testing purposes:
-        viewHolder.getTitle().setText(itemData.toString());
-        viewHolder.getSubtitle().setText("2014   Drama   TV-14");
-        viewHolder.getBody().setText("Lorem ipsum dolor sit amet, consectetur "
-                + "adipisicing elit, sed do eiusmod tempor incididunt ut labore "
-                + " et dolore magna aliqua. Ut enim ad minim veniam, quis "
-                + "nostrud exercitation ullamco laboris nisi ut aliquip ex ea "
-                + "commodo consequat.");
-    }
-}
-
- - -

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.

- -

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.

- -
-public class MediaItemDetailsFragment extends DetailsFragment {
-    private static final String TAG = "MediaItemDetailsFragment";
-    private ArrayObjectAdapter mRowsAdapter;
-
-    @Override
-    public void onCreate(Bundle savedInstanceState) {
-        Log.i(TAG, "onCreate");
-        super.onCreate(savedInstanceState);
-
-        buildDetails();
-    }
-
-    private void buildDetails() {
-        ClassPresenterSelector selector = new ClassPresenterSelector();
-        // Attach your media item details presenter to the row presenter:
-        DetailsOverviewRowPresenter rowPresenter =
-            new DetailsOverviewRowPresenter(new DetailsDescriptionPresenter());
-
-        selector.addClassPresenter(DetailsOverviewRow.class, rowPresenter);
-        selector.addClassPresenter(ListRow.class,
-                new ListRowPresenter());
-        mRowsAdapter = new ArrayObjectAdapter(selector);
-
-        Resources res = getActivity().getResources();
-        DetailsOverviewRow detailsOverview = new DetailsOverviewRow(
-                "Media Item Details");
-
-        // Add images and action buttons to the details view
-        detailsOverview.setImageDrawable(res.getDrawable(R.drawable.jelly_beans));
-        detailsOverview.addAction(new Action(1, "Buy $9.99"));
-        detailsOverview.addAction(new Action(2, "Rent $2.99"));
-        mRowsAdapter.add(detailsOverview);
-
-        // Add a Related items row
-        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(0, "Related Items", null);
-        mRowsAdapter.add(new ListRow(header, listRowAdapter));
-
-        setAdapter(mRowsAdapter);
-    }
-}
-
- - -

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

- -

Start creating the details activity by building a layout that references your implementation - of the {@code DetailsFragment}:

- -
-<!-- file: res/layout/details.xml -->
-
-<fragment xmlns:android="http://schemas.android.com/apk/res/android"
-    android:name="com.example.android.mediabrowser.MediaItemDetailsFragment"
-    android:id="@+id/details_fragment"
-    android:layout_width="match_parent"
-    android:layout_height="match_parent"
-/>
-
- -

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

- -
-public class DetailsActivity extends Activity
-{
-    @Override
-    public void onCreate(Bundle savedInstanceState) {
-        super.onCreate(savedInstanceState);
-        setContentView(R.layout.details);
-    }
-}
-
- -

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>
-  ...
-
-  <activity android:name=".DetailsActivity"
-    android:exported="true"
-    android:theme="@style/Theme.Leanback"/>
-
-</application>
-
- - -

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.

- -

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 {
-    ...
-
-    @Override
-    protected void onCreate(Bundle savedInstanceState) {
-        ...
-
-        // create the media item rows
-        buildRowsAdapter();
-
-        // add a listener for selected items
-        mBrowseFragment.setOnItemClickedListener(
-            new OnItemClickedListener() {
-                @Override
-                public void onItemClicked(Object item, Row row) {
-                    System.out.println("Media Item clicked: " + item.toString());
-                    Intent intent = new Intent(BrowseMediaActivity.this,
-                            DetailsActivity.class);
-                    // pass the item information
-                    intent.getExtras().putLong("id", item.getId());
-                    startActivity(intent);
-                }
-            });
-    }
-}
-
diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index bb00f8077773..d33372b460a7 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -876,6 +876,24 @@ include the action bar on devices running Android 2.1 or higher." +
  • +
    + + Building TV Playback Apps +
    + +
    • + diff --git a/docs/html/training/tv/playback/browse.jd b/docs/html/training/tv/playback/browse.jd new file mode 100644 index 000000000000..9b25166b7507 --- /dev/null +++ b/docs/html/training/tv/playback/browse.jd @@ -0,0 +1,230 @@ +page.title=Creating a Catalog Browser +page.tags="browsefragment","presenter","backgroundmanager" + +trainingnavtop=true + +@jd:body + +
    +
    +

    This lesson teaches you to

    +
      +
    1. Create a Media Browse Layout
      2. +
    2. Display Media Lists
      3. +
    3. Update the Background
      4. +
    + +
    +
    + +

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

    + + +

    Create a Media Browse Layout

    + +

    + 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"
+  android:layout_width="match_parent"
+  android:layout_height="match_parent"
+  android:orientation="vertical"
+  >
+
+  <fragment
+      android:name="android.support.v17.leanback.app.BrowseFragment"
+      android:id="@+id/browse_fragment"
+      android:layout_width="match_parent"
+      android:layout_height="match_parent"
+      />
+</LinearLayout>
+
    + +

    + 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 {
+
+    public static final String TAG ="BrowseActivity";
+
+    protected BrowseFragment mBrowseFragment;
+
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        setContentView(R.layout.browse_fragment);
+
+        final FragmentManager fragmentManager = getFragmentManager();
+        mBrowseFragment = (BrowseFragment) fragmentManager.findFragmentById(
+                R.id.browse_fragment);
+
+        // 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.setBrowseParams(params);
+
+    }
+}
+
    + + +

    Displaying Media Lists

    + +

    + 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 {@link + android.support.v17.leanback.widget.Presenter} for displaying string data: +

    + +
    +public class StringPresenter extends Presenter {
+    private static final String TAG = "StringPresenter";
+
+    public ViewHolder onCreateViewHolder(ViewGroup parent) {
+        TextView textView = new TextView(parent.getContext());
+        textView.setFocusable(true);
+        textView.setFocusableInTouchMode(true);
+        textView.setBackground(
+                parent.getContext().getResources().getDrawable(R.drawable.text_bg));
+        return new ViewHolder(textView);
+    }
+
+    public void onBindViewHolder(ViewHolder viewHolder, Object item) {
+        ((TextView) viewHolder.view).setText(item.toString());
+    }
+
+    public void onUnbindViewHolder(ViewHolder viewHolder) {
+        // no op
+    }
+}
+
    + +

    + 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;
+private static final int NUM_ROWS = 4;
+
+@Override
+protected void onCreate(Bundle savedInstanceState) {
+    ...
+
+    buildRowsAdapter();
+}
+
+private void buildRowsAdapter() {
+    mRowsAdapter = new ArrayObjectAdapter(new ListRowPresenter());
+
+    for (int i = 0; i < 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));
+    }
+
+    mBrowseFragment.setAdapter(mRowsAdapter);
+}
+
    + +

    + 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

    + +

    + 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 {@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) {
+    BackgroundManager.getInstance(this).setDrawable(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 {@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 OnItemViewSelectedListener getDefaultItemViewSelectedListener() {
+    return new OnItemViewSelectedListener() {
+        @Override
+        public void onItemSelected(Object item, Row row) {
+            if (item instanceof Movie ) {
+                URI uri = ((Movie)item).getBackdropURI();
+                updateBackground(uri);
+            } else {
+                clearBackground();
+            }
+        }
+    };
+}
+
    + +

    + Note: 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. +

    diff --git a/docs/html/training/tv/playback/details.jd b/docs/html/training/tv/playback/details.jd new file mode 100644 index 000000000000..6391a495d2f3 --- /dev/null +++ b/docs/html/training/tv/playback/details.jd @@ -0,0 +1,247 @@ +page.title=Building a Details View +page.tags="detailsfragment" + +trainingnavtop=true + +@jd:body + +
    + +
    + +

    + 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 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 {@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 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
+        extends AbstractDetailsDescriptionPresenter {
+
+    @Override
+    protected void onBindDescription(ViewHolder viewHolder, Object itemData) {
+        MyMediaItemDetails details = (MyMediaItemDetails) itemData;
+        // In a production app, the itemData object contains the information
+        // needed to display details for the media item:
+        // viewHolder.getTitle().setText(details.getShortTitle());
+
+        // Here we provide static data for testing purposes:
+        viewHolder.getTitle().setText(itemData.toString());
+        viewHolder.getSubtitle().setText("2014   Drama   TV-14");
+        viewHolder.getBody().setText("Lorem ipsum dolor sit amet, consectetur "
+                + "adipisicing elit, sed do eiusmod tempor incididunt ut labore "
+                + " et dolore magna aliqua. Ut enim ad minim veniam, quis "
+                + "nostrud exercitation ullamco laboris nisi ut aliquip ex ea "
+                + "commodo consequat.");
+    }
+}
+
    + + +

    Extend the Details Fragment

    + +

    + 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 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 {
+    private static final String TAG = "MediaItemDetailsFragment";
+    private ArrayObjectAdapter mRowsAdapter;
+
+    @Override
+    public void onCreate(Bundle savedInstanceState) {
+        Log.i(TAG, "onCreate");
+        super.onCreate(savedInstanceState);
+
+        buildDetails();
+    }
+
+    private void buildDetails() {
+        ClassPresenterSelector selector = new ClassPresenterSelector();
+        // Attach your media item details presenter to the row presenter:
+        DetailsOverviewRowPresenter rowPresenter =
+            new DetailsOverviewRowPresenter(new DetailsDescriptionPresenter());
+
+        selector.addClassPresenter(DetailsOverviewRow.class, rowPresenter);
+        selector.addClassPresenter(ListRow.class,
+                new ListRowPresenter());
+        mRowsAdapter = new ArrayObjectAdapter(selector);
+
+        Resources res = getActivity().getResources();
+        DetailsOverviewRow detailsOverview = new DetailsOverviewRow(
+                "Media Item Details");
+
+        // Add images and action buttons to the details view
+        detailsOverview.setImageDrawable(res.getDrawable(R.drawable.jelly_beans));
+        detailsOverview.addAction(new Action(1, "Buy $9.99"));
+        detailsOverview.addAction(new Action(2, "Rent $2.99"));
+        mRowsAdapter.add(detailsOverview);
+
+        // Add a Related items row
+        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(0, "Related Items", null);
+        mRowsAdapter.add(new ListRow(header, listRowAdapter));
+
+        setAdapter(mRowsAdapter);
+    }
+}
+
    + + +

    Create a Details Activity

    + +

    + 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 {@link android.support.v17.leanback.app.DetailsFragment}: +

    + +
    +<!-- file: res/layout/details.xml -->
+
+<fragment xmlns:android="http://schemas.android.com/apk/res/android"
+    android:name="com.example.android.mediabrowser.MediaItemDetailsFragment"
+    android:id="@+id/details_fragment"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+/>
+
    + +

    + Next, create an activity class that uses the layout shown in the previous code example: +

    + +
    +public class DetailsActivity extends Activity
+{
+    @Override
+    public void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        setContentView(R.layout.details);
+    }
+}
+
    + +

    + 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>
+  ...
+
+  <activity android:name=".DetailsActivity"
+    android:exported="true"
+    android:theme="@style/Theme.Leanback"/>
+
+</application>
+
    + + +

    Define a Listener for Clicked Items

    + +

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

    + +
    +public class BrowseMediaActivity extends Activity {
+    ...
+
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        ...
+
+        // create the media item rows
+        buildRowsAdapter();
+
+        // add a listener for selected items
+        mBrowseFragment.OnItemViewClickedListener(
+            new OnItemViewClickedListener() {
+                @Override
+                public void onItemClicked(Object item, Row row) {
+                    System.out.println("Media Item clicked: " + item.toString());
+                    Intent intent = new Intent(BrowseMediaActivity.this,
+                            DetailsActivity.class);
+                    // pass the item information
+                    intent.getExtras().putLong("id", item.getId());
+                    startActivity(intent);
+                }
+            });
+    }
+}
+
    diff --git a/docs/html/training/tv/playback/index.jd b/docs/html/training/tv/playback/index.jd new file mode 100644 index 000000000000..d7167e7e8aab --- /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

    + +
    +
    + +

    + 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.
    +
    -- cgit v1.2.3-59-g8ed1b