diff options
Diffstat (limited to 'docs/html/preview/tv/start/index.jd')
| -rw-r--r-- | docs/html/preview/tv/start/index.jd | 233 |
1 files changed, 233 insertions, 0 deletions
diff --git a/docs/html/preview/tv/start/index.jd b/docs/html/preview/tv/start/index.jd new file mode 100644 index 0000000..11d6ad3 --- /dev/null +++ b/docs/html/preview/tv/start/index.jd @@ -0,0 +1,233 @@ +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="@android: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#v7-appcompat">v7 + appcompat library</a>, which is, in turn, 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>v7 appcompat support library</li> + <li>v4 support library</li> +</ul> + +<p>Two of these libraries (v17 leanback and v7 appcompat) contain resources, which require + you to take specific steps to include them 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> + |