From f666355b2d9dbffffa640aff7731a8ba8309eaaa Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Thu, 2 Oct 2014 10:13:16 -0700 Subject: [PATCH] docs: migrate TV Playback app content Change-Id: I851dac6423cba3b76c85e1ac5b6c03a98272d868 --- docs/html/training/training_toc.cs | 18 +++ .../tv/ui => training/tv/playback}/browse.jd | 130 ++++++++++------- .../tv/ui => training/tv/playback}/details.jd | 131 +++++++++++------- docs/html/training/tv/playback/index.jd | 49 +++++++ 4 files changed, 230 insertions(+), 98 deletions(-) rename docs/html/{preview/tv/ui => training/tv/playback}/browse.jd (51%) rename docs/html/{preview/tv/ui => training/tv/playback}/details.jd (54%) create mode 100644 docs/html/training/tv/playback/index.jd diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index bb00f80777731..d33372b460a70 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/preview/tv/ui/browse.jd b/docs/html/training/tv/playback/browse.jd similarity index 51% rename from docs/html/preview/tv/ui/browse.jd rename to docs/html/training/tv/playback/browse.jd index d6b97c17e2b6a..9b25166b75073 100644 --- a/docs/html/preview/tv/ui/browse.jd +++ b/docs/html/training/tv/playback/browse.jd @@ -1,30 +1,43 @@ -page.title=BrowseFragment +page.title=Creating a Catalog Browser +page.tags="browsefragment","presenter","backgroundmanager" + +trainingnavtop=true @jd:body -
    -
    -

    In this document

    + -

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

    -

    Media Browse Layout

    +

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

    +

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