| page.title=Get Started with TV Apps |
| page.tags="leanback","recyclerview","launcher" |
| |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#prerequisites">Prerequisites</a></li> |
| <li><a href="#dev-project">Setup a TV Project</a> |
| <ul> |
| <li><a href="#tv-activity">Create a TV Activity</a></li> |
| <li><a href="#tv-libraries">Add TV Support Libraries</a></li> |
| </ul> |
| </li> |
| <li><a href="#build-it">Build TV Apps</a></li> |
| <li><a href="#run">Run TV Apps</a></li> |
| |
| </ol> |
| </div> |
| </div> |
| |
| <p>This guide describes how to prepare your development environment and projects for building |
| TV apps, including updating your existing app to run on TV devices.</p> |
| |
| |
| <h2 id="prerequisites">Prerequisites</h2> |
| |
| <p>Before you begin setting up to build apps for TV, you must:</p> |
| |
| <ul> |
| <li><strong><a href="{@docRoot}preview/setup-sdk.html"> |
| Set up the Preview SDK</a></strong> |
| <br> |
| The preview SDK provides the developer tools needed to build and test apps for TV. |
| </li> |
| <li><strong><a href="{@docRoot}preview/setup-sdk.html#project"> |
| Create a Preview SDK Project</a></strong> |
| <br> |
| In order to access new APIs for TV devices, you must create a project that targets the preview |
| release level or modify an existing project to target the preview release. |
| </li> |
| </ul> |
| |
| |
| <h2 id="dev-project">Set up a TV Project</h2> |
| |
| <p>TV apps use the same structure as those for phones and tablets. This means you can modify |
| your existing apps to also run on TV devices or create new apps based on what you already know |
| about building apps for Android. This section discusses how to modify an existing app, or create a |
| new one, to run on TV devices.</p> |
| |
| <p>These are the main steps to creating an app that runs on TV devices. Only the first |
| is required:</p> |
| |
| <ul> |
| <li><strong>Activity for TV</strong> - (Required) In your application manifest, you must |
| declare an activity that is intended to run on TV devices.</li> |
| <li><strong>TV Support Libraries</strong> - (Optional) There are several Support Libraries |
| available for TV devices that provide widgets for building user interfaces.</li> |
| </ul> |
| |
| |
| <h3 id="tv-activity">Create a TV Activity</h3> |
| |
| <p>An application intended to run on TV devices must declare a launcher activity for TV |
| in its manifest using a {@code android.intent.category.LEANBACK_LAUNCHER} intent filter. |
| This filter identifies your app as being built for TV, enabling it to be displayed in the |
| Google Play store app running on TV devices. Declaring this intent also identifies which activity |
| in your app should be launched when a user selects its icon on the TV home screen.</p> |
| |
| <p class="caution"> |
| <strong>Caution:</strong> If you do not include the {@code LEANBACK_LAUNCHER} intent filter in |
| your app, it is not visible to users running the Google Play store on TV devices. Also, if your |
| app does not have this filter when you load it onto a TV device using developer tools, the app |
| does not appear in the TV user interface. |
| </p> |
| |
| <p>The following code snippet shows how to include this intent filter in your manifest:</p> |
| |
| <pre> |
| <application> |
| ... |
| <activity |
| android:name="com.example.android.MainActivity" |
| android:label="@string/app_name" > |
| |
| <intent-filter> |
| <action android:name="android.intent.action.MAIN" /> |
| <category android:name="android.intent.category.LAUNCHER" /> |
| </intent-filter> |
| </activity> |
| |
| <activity |
| android:name="com.example.android.<strong>TvActivity</strong>" |
| android:label="@string/app_name" |
| android:theme="@style/Theme.Leanback"> |
| |
| <intent-filter> |
| <action android:name="android.intent.action.MAIN" /> |
| <category android:name="<strong>android.intent.category.LEANBACK_LAUNCHER</strong>" /> |
| </intent-filter> |
| |
| </activity> |
| </application> |
| </pre> |
| |
| <p>The second activity manifest entry in the example above specifies that activity as |
| the main one when your app launches on an TV device.</p> |
| |
| <p>If you have an existing app that you are modifying for TV use, your app should not use the same |
| activity layout for TV that it does for phones and tablets. The user interface of your TV app (or |
| TV portion of your existing app) should provide a simpler interface that can be easily navigated |
| using a remote control from a couch. For guidelines on designing an app for TV, see the |
| <a href="{@docRoot}design/tv/index.html">TV Design</a> guide. For more instructions on |
| developing a user interface appropriate to TV, see the |
| <a href="{@docRoot}preview/tv/ui/index.html">TV User Interface</a> guide. |
| </p> |
| |
| |
| <h3 id="tv-libraries">Add TV Support Libraries</h3> |
| |
| <p>The Preview SDK includes support libraries that are intended for use with TV apps. These |
| libraries provide APIs and user interface widgets for use on TV devices. The libraries are |
| located in the {@code <sdk>/extras/android/support/} directory where you installed the |
| Preview SDK. Here is a list of the libraries and their general purpose:</p> |
| |
| <ul> |
| <li><strong>v17 leanback library</strong> - Provides user interface widgets for TV, including |
| {@code BrowseFragment}, {@code DetailsFragment}, and {@code SearchFragment}. |
| <ul> |
| <li>SDK location: {@code <sdk>/extras/android/support/v17/leanback}</li> |
| <li>Gradle dependency: {@code com.android.support:leanback-v17:20.0.+}</li> |
| <li>Contains resources: Yes</li> |
| </ul> |
| </li> |
| <li><strong>v7 recyclerview library</strong> - Provides classes for managing display of long |
| lists in a memory efficient manner. Several classes in the v17 leanback library depend on the |
| classes in this library. |
| <ul> |
| <li>SDK location: {@code <sdk>/extras/android/support/v7/recyclerview}</li> |
| <li>Gradle dependency: {@code com.android.support:recyclerview-v7:20.0.+}</li> |
| <li>Contains resources: No</li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p class="note"> |
| <strong>Note:</strong> You are not required to use these support libraries for your TV app. |
| However, we strongly recommend using them, particularly for apps that provide a media catalog |
| browsing interface. |
| </p> |
| |
| <p>If you decide to use the v17 leanback library for your app, you should note that it is |
| dependent on the |
| <a href="{@docRoot}tools/support-library/features.html#v4">v4 support library</a>. This means |
| that apps that use the leanback support library should include all of these support |
| libraries:</p> |
| |
| <ul> |
| <li>v17 leanback support library</li> |
| <li>v7 recyclerview support library</li> |
| <li>v4 support library</li> |
| </ul> |
| |
| <p>The v17 leanback library contain resources, which requires |
| you to take specific steps to include it in app projects. For instructions on |
| importing a support library with resources, see |
| <a href="http://developer.android.com/tools/support-library/setup.html#libs-with-res"> |
| Support Library Setup</a>. |
| </p> |
| |
| |
| <h2 id="build-it">Build TV Apps</h2> |
| |
| <p>After you have completed the steps described above, it's time to start building apps for |
| the big screen! Check out these additional topics to help you build your app for TV: |
| |
| <ul> |
| <li><a href="{@docRoot}preview/tv/ui/index.html">User Interface</a> - The user interface of |
| TV devices is different from those of other Android devices. See this topic to find out how |
| to build TV user interfaces and to learn about the widgets provided to simplify that task. |
| </li> |
| <li><a href="{@docRoot}preview/tv/games/index.html">Games for TV</a> - TV devices are great |
| platforms for games. See this topic for information on building great game experiences for |
| TV.</li> |
| <li><a href="{@docRoot}preview/tv/start/hardware-features.html">Hardware features</a> - TV |
| devices do not contain hardware features normally found on other Android devices. See this |
| topic for information on unsupported hardware features and what to do about them. |
| </li> |
| </ul> |
| |
| |
| <h2 id="run">Run TV Apps</h2> |
| |
| <p>Running your app is an important part of the development process. The AVD Manager in the |
| Android SDK provides the device definitions that allows you to create virtual TV devices for |
| running and testing your applications.</p> |
| |
| <p>To create an virtual TV device:</p> |
| |
| <ol> |
| <li>Start the AVD Manager. For more information, see the |
| <a href="{@docRoot}tools/help/avd-manager.html">AVD Manager</a> help.</li> |
| <li>In the AVD Manager dialog, click the <strong>Device Definitions</strong> tab.</li> |
| <li>Select one of the Android TV device definitions, such as |
| <strong>Large Android TV</strong>, and click <strong>Create AVD</strong>.</li> |
| <li>Select the emulator options and click <strong>OK</strong> to create the AVD. |
| <p class="note"> |
| <strong>Note:</strong> For best performance of the TV emulator device, enable the <strong>Use |
| Host GPU</strong> option and CPU platform image that supports hardware acceleration. For |
| more information on hardware acceleration of the emulator, see |
| <a href="{@docRoot}tools/devices/emulator.html#acceleration">Using the Emulator</a>. |
| </p> |
| </li> |
| </ol> |
| |
| <p>To test your application on the virtual TV device:</p> |
| |
| <ol> |
| <li>Compile your TV application in your development environment.</li> |
| <li>Run the application from your development environment and choose the TV virtual device as |
| the target.</li> |
| </ol> |
| |
| <p>For more information about using emulators see, <a href="{@docRoot}tools/devices/emulator.html"> |
| Using the Emulator</a>. For more information about deploying apps to emulators from |
| Eclipse with ADT, see <a href="{@docRoot}http://developer.android.com/tools/building/building-eclipse.html"> |
| Building and Running from Eclipse with ADT</a>.</p> |
| |