diff options
| -rw-r--r-- | docs/html/training/training_toc.cs | 18 | ||||
| -rw-r--r-- | docs/html/training/tv/playback/browse.jd (renamed from docs/html/preview/tv/ui/browse.jd) | 130 | ||||
| -rw-r--r-- | docs/html/training/tv/playback/details.jd (renamed from docs/html/preview/tv/ui/details.jd) | 131 | ||||
| -rw-r--r-- | docs/html/training/tv/playback/index.jd | 49 |
4 files changed, 230 insertions, 98 deletions
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." </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 --> diff --git a/docs/html/preview/tv/ui/browse.jd b/docs/html/training/tv/playback/browse.jd index d6b97c17e2b6..9b25166b7507 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 -<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> -<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> +<h2 id="layout">Create a Media Browse Layout</h2> + +<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> <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" @@ -42,10 +55,13 @@ page.title=BrowseFragment </LinearLayout> </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">Updating the Background</h2> +<h2 id="background">Update 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() { @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 index 8b8fa8b5b4bd..6391a495d2f3 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 -<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> <!-- file: res/layout/details.xml --> @@ -147,7 +170,9 @@ public class MediaItemDetailsFragment extends DetailsFragment { /> </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> <application> @@ -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() { @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 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 + +<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> |