diff options
Diffstat (limited to 'docs/html/training')
| -rw-r--r-- | docs/html/training/enterprise/app-compatibility.jd | 274 | ||||
| -rw-r--r-- | docs/html/training/enterprise/index.jd | 8 | ||||
| -rw-r--r-- | docs/html/training/location/receive-location-updates.jd | 943 | ||||
| -rw-r--r-- | docs/html/training/material/drawables.jd | 10 | ||||
| -rw-r--r-- | docs/html/training/training_toc.cs | 30 | ||||
| -rw-r--r-- | docs/html/training/tv/discovery/recommendations.jd | 233 | ||||
| -rw-r--r-- | docs/html/training/tv/discovery/searchable.jd | 383 | ||||
| -rw-r--r-- | docs/html/training/wearables/ui/lists.jd | 51 |
8 files changed, 1251 insertions, 681 deletions
diff --git a/docs/html/training/enterprise/app-compatibility.jd b/docs/html/training/enterprise/app-compatibility.jd new file mode 100644 index 0000000..1ae1ee3 --- /dev/null +++ b/docs/html/training/enterprise/app-compatibility.jd @@ -0,0 +1,274 @@ +page.title=Ensuring Compatibility with Managed Profiles +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#prevent_failed_intents">Prevent Failed Intents</a></li> + <li><a href="#sharing_files">Share Files Across Profiles</a></li> + <li><a href="#testing_apps">Test your App for Compatibility with Managed + Profiles</a></li> +</ol> + +<!-- related docs (NOT javadocs) --> +<h2>Resources</h2> +<ul> + <li><a href="{@docRoot}samples/BasicManagedProfile/index.html">BasicManagedProfile</a></li> +</ul> + +</div> +</div> + +<p>The Android platform allows devices to have +<a href="{@docRoot}about/versions/android-5.0.html#Enterprise">managed +profiles</a>. A managed profile is controlled by an administrator, and the +functionality available to it is set separately from the functionality of the +user's primary profile. This approach lets enterprises control the environment +where company-specific apps and data are running on a user's device, while still +letting users use their personal apps and profiles.</p> + +<p>This lesson shows you how to modify your application so it functions +reliably on a device with managed profiles. You don't need to do anything +besides the ordinary app-development best practices. However, some of these best +practices become especially important on devices with managed profiles. This +document highlights the issues you need to be aware of.</p> + +<h2 id="overview">Overview</h2> + +<p>Users often want to use their personal devices in an enterprise setting. This +situation can present enterprises with a dilemma. If the user can use their own +device, the enterprise has to worry that confidential information (like employee +emails and contacts) are on a device the enterprise does not control. </p> + +<p>To address this situation, Android 5.0 (API level 21) allows enterprises to +set up <i>managed profiles</i>. If a device has a managed profile, the profile's +settings are under the control of the enterprise administrator. The +administrator can choose which apps are allowed for that profile, and can +control just what device features are available to the profile.</p> + +<p>If a device has a managed profile, there are implications for apps +running on the device, no matter which profile the app is running under:</p> + +<ul> + +<li>By default, most intents do not cross from one profile to the other. If an +app running on profile fires an intent, there is no handler for the intent on +that profile, and the intent is not allowed to cross to the other profile +due to profile restrictions, the request fails and the app may shut down +unexpectedly.</li> +<li>The profile administrator can limit which system apps are available on the +managed profile. This restriction can also result in there being no handler for +some common intents on the managed profile.</li> +<li>Since the managed and unmanaged profiles have separate storage areas, a +file URI that is valid on one profile is not valid on the other. Any +intent fired on one profile might be handled on the other (depending on profile +settings), so it is not safe to attach file URIs to intents.</li> + +</ul> + +<h2 id="prevent_failed_intents">Prevent Failed Intents</h2> + +<p>On a device with a managed profile, there are restrictions on whether intents +can cross from one profile to another. In most cases, when an intent is fired +off, it is handled on the same profile where it is fired. If there is no handler +for the intent <em>on that profile</em>, the intent is not handled and the app +that fired it may shut down unexpectedly—even if there's a handler for the +intent on the other profile.</p> + +<p>The profile administrator can choose which intents are +allowed to cross from one profile to another. Since the administrator makes +this decision, there's no way for you +to know in advance <em>which</em> intents are allowed to cross this boundary. The +administrator sets this policy, and is free to change it at any time.</p> + +<p>Before your app starts an activity, you should verify that there is a +suitable resolution. You +can verify that there is an acceptable resolution by calling {@link +android.content.Intent#resolveActivity Intent.resolveActivity()}. If there is no +way to resolve the intent, the method returns +<code>null</code>. If the method returns non-null, there is at least one way to +resolve the intent, and it is safe to fire off the intent. In this case, the +intent could be resolvable either +because there is a handler on the current profile, or because the intent is +allowed to cross to a handler on the other profile. (For more information about +resolving intents, see <a +href="{@docRoot}guide/components/intents-common.html">Common Intents</a>.)</p> + +<p>For example, if your app needs to set timers, it would need to check that +there's a valid handler for the {@link +android.provider.AlarmClock#ACTION_SET_TIMER} intent. If the app cannot resolve +the intent, it should take an appropriate action (such as showing an error +message).</p> + +<pre>public void startTimer(String message, int seconds) { + + // Build the "set timer" intent + Intent timerIntent = new Intent(AlarmClock.ACTION_SET_TIMER) + .putExtra(AlarmClock.EXTRA_MESSAGE, message) + .putExtra(AlarmClock.EXTRA_LENGTH, seconds) + .putExtra(AlarmClock.EXTRA_SKIP_UI, true); + + // Check if there's a handler for the intent + <strong>if (timerIntent.resolveActivity(getPackageManager()) == null)</strong> { + + // Can't resolve the intent! Fail this operation cleanly + // (perhaps by showing an error message) + + } else { + // Intent resolves, it's safe to fire it off + startActivity(timerIntent); + + } +} +</pre> + +<h2 id="sharing_files">Share Files Across Profiles</h2> + +<p>Sometimes an app needs to provide other apps with access to its own files. +For example, an image gallery app might want to share its images with image +editors. There are two ways you would ordinarily share a file: with a <em>file +URI</em> or a <em>content URI</em>.</p> + +<p>A file URI begins with the <code>file:</code> prefix, followed by the +absolute path of the file on the device's storage. However, because the +managed profile and the personal profile use separate storage areas, a file URI +that is valid on one profile is not valid on the other. This situation +means that if you +attach a file URI to an intent, and the intent is handled on the other profile, +the handler is not able to access the file.</p> + +<p>Instead, you should share files with <em>content URIs</em>. Content URIs +identify the file in a more secure, shareable fashion. The content URI contains +the file path, but also the authority that provides the file, and an ID number +identifying the file. You can generate a content ID for any file by using a +{@link android.support.v4.content.FileProvider}. You can then share that content +ID with other apps (even on the other profile). The recipient can use the +content ID to get access to the actual file.</p> + +<p>For example, here's how you would get the content URI for a specific file +URI:</p> + +<pre>// Open File object from its file URI +File fileToShare = new File(<em>fileUriToShare</em>); + +Uri contentUriToShare = FileProvider.getUriForFile(getContext(), + <em>"com.example.myapp.fileprovider"</em>, fileToShare);</pre> + +<p>When you call the {@link +android.support.v4.content.FileProvider#getUriForFile getUriForFile()} method, +you must include the file provider's authority (in this example, +<code>"com.example.myapp.fileprovider"</code>), which is specified in the +<a href="{@docRoot}guide/topics/manifest/provider-element.html"><code><provider></code></a> +element of your app manifest. +For more information about sharing files with content URIs, see +<a href="{@docRoot}training/secure-file-sharing/index.html">Sharing +Files</a>.</p> + +<h2 id="testing_apps">Test your App for Compatibility with Managed Profiles</h2> + +<p>You should test your app in a managed-profile environment to +catch problems that would cause your app to fail on a device with +managed profiles. In particular, testing on a managed-profile device is a good +way to make sure that your app handles intents properly: not firing intents that +can't be handled, not attaching URIs that don't work cross-profile, and so +on.</p> + +<p>We have provided a sample app, <a +href="{@docRoot}samples/BasicManagedProfile/index.html">BasicManagedProfile</a>, +which you can use to set up a managed profile on an Android device that runs +Android 5.0 (API level 21) and higher. This app offers you a simple way to test +your app in a managed-profile environment. You can also use this app to +configure the managed profile as follows:</p> + +<ul> + + <li>Specify which default apps are available on the managed + profile</li> + + <li>Configure which intents are allowed to cross from one profile to + the other</li> + +</ul> + +<p>If you manually install an app over a USB cable to a device which has a +managed profile, the app is installed on both the managed and the unmanaged +profile. Once you have installed the app, you can test the app under the +following conditions:</p> + +<ul> + + <li>If an intent would ordinarily be handled by a default app (for example, + the camera app), try disabling that default app on the managed profile, and + verify that the app handles this appropriately.</li> + + <li>If you fire an intent expecting it to be handled by some other app, try +enabling and disabling that intent's permission to cross from one profile to +another. Verify that the app behaves properly under both circumstances. If the +intent is not allowed to cross between profiles, verify the app's behavior both +when there is a suitable handler on the app's profile, and when there is not. +For example, if your app fires a map-related intent, try each of the following +scenarios: + + <ul> + +<li>The device allows map intents to cross from one profile to the other, and +there is a suitable handler on the other profile (the profile the app is not +running on)</li> + +<li>The device does not allow map intents to cross between profiles, but there +is a suitable handler on the app's profile</li> + +<li>The device does not allow map intents to cross between profiles, and there +is no suitable handler for map intents on the device's profile</li> + + </ul> + </li> + +<li>If you attach content to an intent, verify that the intent behaves properly +both when it is handled on the app's profile, and when it crosses between +profiles.</li> + +</ul> + +<h3 id="testing_tips">Testing on managed profiles: Tips and tricks</h3> + +<p>There are a few tricks that you may find helpful in testing on a +managed-profile device.</p> + +<ul> + +<li>As noted, when you side-load an app on a managed profile device, it is +installed on both profiles. If you wish, you can delete the app from one profile +and leave it on the other.</li> + +<li>Most of the activity manager commands available in the <a +href="{@docRoot}tools/help/adb.html">Android Debug Bridge</a> (adb) shell +support the <code>--user</code> flag, which lets you specify which user to run +as. By specifying a user, you can choose whether to run as the unmanaged or +managed profile. For +more information, see <a href="{@docRoot}tools/help/adb.html#am">Android Debug +Bridge: Using activity manager (am)</a>.</li> + +<li>To find the active users on a device, use the adb package manager's +<code>list users</code> command. The first number in the output string is the +user ID, which you can use with the <code>--user</code> flag. For more +information, see <a href="{@docRoot}tools/help/adb.html#pm">Android Debug +Bridge: Using package manager (pm)</a>.</li> + +</ul> + +<p>For example, to find the users on a device, you would run this command:</p> + +<pre class="no-pretty-print">$ <strong>adb shell pm list users</strong> +UserInfo{0:Drew:13} running +UserInfo{10:Work profile:30} running</pre> + +<p>In this case, the unmanaged profile ("Drew") has the user ID 0, and the +managed profile has the user ID 10. To run an app in the work profile, you +would use a command like this:</p> + +<pre class="no-pretty-print">$ adb shell am start --user 10 \ +-n "<em>com.example.myapp/com.example.myapp.testactivity</em>" \ +-a android.intent.action.MAIN -c android.intent.category.LAUNCHER</pre> diff --git a/docs/html/training/enterprise/index.jd b/docs/html/training/enterprise/index.jd index 2926f71..0ac68cc 100644 --- a/docs/html/training/enterprise/index.jd +++ b/docs/html/training/enterprise/index.jd @@ -47,4 +47,12 @@ for the enterprise.</p> Policies</a></b></dt> <dd>In this lesson, you will learn how to create a security-aware application that manages access to its content by enforcing device management policies</dd> + + <dt><b><a href="app-compatibility.html">Ensuring Compatibility with Managed Profiles</a></b></dt> + + <dd>In this lesson, you will learn the best practices to follow to ensure + that your app functions properly on devices that use <a + href="{@docRoot}about/versions/android-5.0.html#Enterprise">managed + profiles</a></dd> + </dl> diff --git a/docs/html/training/location/receive-location-updates.jd b/docs/html/training/location/receive-location-updates.jd index e6e8c51..208dc17 100644 --- a/docs/html/training/location/receive-location-updates.jd +++ b/docs/html/training/location/receive-location-updates.jd @@ -1,612 +1,417 @@ page.title=Receiving Location Updates trainingnavtop=true @jd:body + <div id="tb-wrapper"> -<div id="tb"> - -<h2>This lesson teaches you to</h2> -<ol> - <li><a href="#Permissions">Request Location Permission</a></li> - <li><a href="#PlayServices">Check for Google Play Services</a></li> - <li><a href="#DefineCallbacks">Define Location Services Callbacks</a></li> - <li><a href="#UpdateParameters">Specify Update Parameters</a></li> - <li><a href="#StartUpdates">Start Location Updates</a></li> - <li><a href="#StopUpdates">Stop Location Updates</a></li> -</ol> - -<h2>You should also read</h2> -<ul> + <div id="tb"> + + <h2>This lesson teaches you how to</h2> + <ol> + <li><a href="#connect">Connect to Location Services</a></li> + <li><a href="#location-request">Set Up a Location Request</a></li> + <li><a href="#updates">Request Location Updates</a></li> + <li><a href="#callback">Define the Location Update Callback</a></li> + <li><a href="#stop-updates">Stop Location Updates</a></li> + <li><a href="#save-state">Save the State of the Activity</a></li> + </ol> + + <h2>You should also read</h2> + <ul> <li> - <a href="{@docRoot}google/play-services/setup.html">Setup Google Play Services SDK</a> + <a href="{@docRoot}google/play-services/setup.html">Setting up Google Play + Services</a> </li> <li> - <a href="retrieve-current.html">Retrieving the Current Location</a> + <a href="retrieve-current.html">Getting the Last Known Location</a> </li> - </ul> + </ul> -<h2>Try it out</h2> + <h2>Try it out</h2> -<div class="download-box"> - <a href="http://developer.android.com/shareables/training/LocationUpdates.zip" class="button">Download the sample</a> - <p class="filename">LocationUpdates.zip</p> + <ul> + <li> + <a href="https://github.com/googlesamples/android-play-location/tree/master/LocationUpdates" class="external-link">LocationUpdates</a> + </li> + </ul> + </div> </div> -</div> -</div> +<p>If your app can continuously track location, it can deliver more relevant + information to the user. For example, if your app helps the user find their + way while walking or driving, or if your app tracks the location of assets, it + needs to get the location of the device at regular intervals. As well as the + geographical location (latitude and longitude), you may want to give the user + further information such as the bearing (horizontal direction of travel), + altitude, or velocity of the device. This information, and more, is available + in the {@link android.location.Location} object that your app can retrieve + from the + <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html">fused + location provider</a>.</p> + +<p>While you can get a device's location with + <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html#getLastLocation(com.google.android.gms.common.api.GoogleApiClient)">{@code getLastLocation()}</a>, + as illustrated in the lesson on + <a href="retrieve-current.html">Getting the Last Known Location</a>, + a more direct approach is to request periodic updates from the fused location + provider. In response, the API updates your app periodically with the best + available location, based on the currently-available location providers such + as WiFi and GPS (Global Positioning System). The accuracy of the location is + determined by the providers, the location permissions you've requested, and + the options you set in the location request.</p> + +<p>This lesson shows you how to request regular updates about a device's + location using the + <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html#requestLocationUpdates(com.google.android.gms.common.api.GoogleApiClient, com.google.android.gms.location.LocationRequest, com.google.android.gms.location.LocationListener)">{@code requestLocationUpdates()}</a> + method in the fused location provider. + +<h2 id="connect">Connect to Location Services</h2> + +<p>Location services for apps are provided through Google Play services and the + fused location provider. In order to use these services, you connect your app + using the Google API Client and then request location updates. For details on + connecting with the + <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code GoogleApiClient}</a>, + follow the instructions in + <a href="retrieve-current.html">Getting the Last Known Location</a>, including + requesting the current location.</p> + +<p>The last known location of the device provides a handy base from which to + start, ensuring that the app has a known location before starting the + periodic location updates. The lesson on + <a href="retrieve-current.html">Getting the Last Known Location</a> shows you + how to get the last known location by calling + <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html#getLastLocation(com.google.android.gms.common.api.GoogleApiClient)">{@code getLastLocation()}</a>. + The snippets in the following sections assume that your app has already + retrieved the last known location and stored it as a + {@link android.location.Location} object in the global variable + {@code mCurrentLocation}.</p> + +<p>Apps that use location services must request location permissions. In this + lesson you require fine location detection, so that your app can get as + precise a location as possible from the available location providers. Request + this permission with the + {@code uses-permission} element in your app manifest, as shown in the + following example:</p> -<p> - If your app does navigation or tracking, you probably want to get the user's - location at regular intervals. While you can do this with -<code><a href="{@docRoot}reference/com/google/android/gms/location/LocationClient.html#getLastLocation()">LocationClient.getLastLocation()</a></code>, - a more direct approach is to request periodic updates from Location Services. In - response, Location Services automatically updates your app with the best available location, - based on the currently-available location providers such as WiFi and GPS. -</p> -<p> - To get periodic location updates from Location Services, you send a request using a location - client. Depending on the form of the request, Location Services either invokes a callback - method and passes in a {@link android.location.Location} object, or issues an - {@link android.content.Intent} that contains the location in its extended data. The accuracy and - frequency of the updates are affected by the location permissions you've requested and the - parameters you pass to Location Services with the request. -</p> -<!-- Request permission --> -<h2 id="Permissions">Specify App Permissions</h2> -<p> - Apps that use Location Services must request location permissions. Android has two location - permissions, {@link android.Manifest.permission#ACCESS_COARSE_LOCATION ACCESS_COARSE_LOCATION} - and {@link android.Manifest.permission#ACCESS_FINE_LOCATION ACCESS_FINE_LOCATION}. The - permission you choose affects the accuracy of the location updates you receive. - For example, If you request only coarse location permission, Location Services obfuscates the - updated location to an accuracy that's roughly equivalent to a city block. -</p> -<p> - Requesting {@link android.Manifest.permission#ACCESS_FINE_LOCATION ACCESS_FINE_LOCATION} implies - a request for {@link android.Manifest.permission#ACCESS_COARSE_LOCATION ACCESS_COARSE_LOCATION}. -</p> -<p> - For example, to add the coarse location permission to your manifest, insert the following as a - child element of - the -<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> - element: -</p> <pre> -<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.google.android.gms.location.sample.locationupdates" > + + <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/> +</manifest> </pre> -<!-- Check for Google Play services --> -<h2 id="PlayServices">Check for Google Play Services</h2> -<p> - Location Services is part of the Google Play services APK. Since it's hard to anticipate the - state of the user's device, you should always check that the APK is installed before you attempt - to connect to Location Services. To check that the APK is installed, call -<code><a href="{@docRoot}reference/com/google/android/gms/common/GooglePlayServicesUtil.html#isGooglePlayServicesAvailable(android.content.Context)">GooglePlayServicesUtil.isGooglePlayServicesAvailable()</a></code>, - which returns one of the - integer result codes listed in the API reference documentation. If you encounter an error, - call -<code><a href="{@docRoot}reference/com/google/android/gms/common/GooglePlayServicesUtil.html#getErrorDialog(int, android.app.Activity, int)">GooglePlayServicesUtil.getErrorDialog()</a></code> - to retrieve localized dialog that prompts users to take the correct action, then display - the dialog in a {@link android.support.v4.app.DialogFragment}. The dialog may allow the - user to correct the problem, in which case Google Play services may send a result back to your - activity. To handle this result, override the method - {@link android.support.v4.app.FragmentActivity#onActivityResult onActivityResult()} - -</p> -<p class="note"> - <strong>Note:</strong> To make your app compatible with - platform version 1.6 and later, the activity that displays the - {@link android.support.v4.app.DialogFragment} must subclass - {@link android.support.v4.app.FragmentActivity} instead of {@link android.app.Activity}. Using - {@link android.support.v4.app.FragmentActivity} also allows you to call - {@link android.support.v4.app.FragmentActivity#getSupportFragmentManager - getSupportFragmentManager()} to display the {@link android.support.v4.app.DialogFragment}. -</p> -<p> - Since you usually need to check for Google Play services in more than one place in your code, - define a method that encapsulates the check, then call the method before each connection - attempt. The following snippet contains all of the code required to check for Google - Play services: -</p> + +<h2 id="location-request">Set Up a Location Request</h2> + +<p>To store parameters for requests to the fused location provider, create a + <a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html">{@code LocationRequest}</a>. + The parameters determine the levels of accuracy requested. For details of all + the options available in the location request, see the + <a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html">{@code LocationRequest}</a> + class reference. This lesson sets the update interval, fastest update + interval, and priority, as described below:</p> + +<dl> + <dt> + Update interval + </dt> + <dd> + <a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#setInterval(long)">{@code setInterval()}</a> + - This method sets the rate in milliseconds at which your app prefers to + receive location updates. Note that the location updates may be faster than + this rate if another app is receiving updates at a faster rate, or slower + than this rate, or there may be no updates at all (if the device has no + connectivity, for example). + </dd> + <dt> + Fastest update interval + </dt> + <dd> + <a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#setFastestInterval(long)">{@code setFastestInterval()}</a> + - This method sets the <strong>fastest</strong> rate in milliseconds at which + your app can handle location updates. You need to set this rate because + other apps also affect the rate at which updates are sent. The Google Play + services location APIs send out updates at the fastest rate that any app + has requested with + <a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#setInterval(long)">{@code setInterval()}</a>. + If this rate is faster + than your app can handle, you may encounter problems with UI flicker or data + overflow. To prevent this, call + <a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#setFastestInterval(long)">{@code setFastestInterval()}</a> + to set an upper limit to the update rate. + </dd> + <dt>Priority</dt> + <dd> + <p> + <a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#setPriority(int)">{@code setPriority()}</a> + - This method sets the priority of the request, which gives the Google Play + services location services a strong hint about which location sources to use. + The following values are supported:</p> + <ul> + <li> + <a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#PRIORITY_BALANCED_POWER_ACCURACY">{@code PRIORITY_BALANCED_POWER_ACCURACY}</a> + - Use this setting to request location precision to within a city + block, which is an accuracy of approximately 100 meters. This is + considered a coarse level of accuracy, and is likely to consume less + power. With this setting, the location services are likely to use WiFi + and cell tower positioning. Note, however, that the choice of location + provider depends on many other factors, such as which sources are + available.</li> + <li> + <a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#PRIORITY_HIGH_ACCURACY">{@code PRIORITY_HIGH_ACCURACY}</a> + - Use this setting to request the most precise location possible. With + this setting, the location services are more likely to use GPS + (Global Positioning System) to determine the location.</li> + <li><a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#PRIORITY_LOW_POWER">{@code PRIORITY_LOW_POWER}</a> + - Use this setting to request city-level precision, which is + an accuracy of approximately 10 kilometers. This is considered a + coarse level of accuracy, and is likely to consume less power.</li> + <li><a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#PRIORITY_NO_POWER">{@code PRIORITY_NO_POWER}</a> + - Use this setting if you need negligible impact on power consumption, + but want to receive location updates when available. With this + setting, your app does not trigger any location updates, but + receives locations triggered by other apps.</li> + </ul> + </dd> +</dl> + +<p>Create the location request and set the parameters as shown in this + code sample:</p> + <pre> -public class MainActivity extends FragmentActivity { - ... - // Global constants - /* - * Define a request code to send to Google Play services - * This code is returned in Activity.onActivityResult - */ - private final static int - CONNECTION_FAILURE_RESOLUTION_REQUEST = 9000; - ... - // Define a DialogFragment that displays the error dialog - public static class ErrorDialogFragment extends DialogFragment { - // Global field to contain the error dialog - private Dialog mDialog; - // Default constructor. Sets the dialog field to null - public ErrorDialogFragment() { - super(); - mDialog = null; - } - // Set the dialog to display - public void setDialog(Dialog dialog) { - mDialog = dialog; - } - // Return a Dialog to the DialogFragment. - @Override - public Dialog onCreateDialog(Bundle savedInstanceState) { - return mDialog; - } - } - ... - /* - * Handle results returned to the FragmentActivity - * by Google Play services - */ - @Override - protected void onActivityResult( - int requestCode, int resultCode, Intent data) { - // Decide what to do based on the original request code - switch (requestCode) { - ... - case CONNECTION_FAILURE_RESOLUTION_REQUEST : - /* - * If the result code is Activity.RESULT_OK, try - * to connect again - */ - switch (resultCode) { - case Activity.RESULT_OK : - /* - * Try the request again - */ - ... - break; - } - ... - } - ... - } - ... - private boolean servicesConnected() { - // Check that Google Play services is available - int resultCode = - GooglePlayServicesUtil. - isGooglePlayServicesAvailable(this); - // If Google Play services is available - if (ConnectionResult.SUCCESS == resultCode) { - // In debug mode, log the status - Log.d("Location Updates", - "Google Play services is available."); - // Continue - return true; - // Google Play services was not available for some reason - } else { - // Get the error code - int errorCode = connectionResult.getErrorCode(); - // Get the error dialog from Google Play services - Dialog errorDialog = GooglePlayServicesUtil.getErrorDialog( - errorCode, - this, - CONNECTION_FAILURE_RESOLUTION_REQUEST); - // If Google Play services can provide an error dialog - if (errorDialog != null) { - // Create a new DialogFragment for the error dialog - ErrorDialogFragment errorFragment = - new ErrorDialogFragment(); - // Set the dialog in the DialogFragment - errorFragment.setDialog(errorDialog); - // Show the error dialog in the DialogFragment - errorFragment.show( - getSupportFragmentManager(), - "Location Updates"); - } - } - } - ... +protected void createLocationRequest() { + LocationRequest mLocationRequest = new LocationRequest(); + mLocationRequest.setInterval(10000); + mLocationRequest.setFastestInterval(5000); + mLocationRequest.setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY); } </pre> -<p> - Snippets in the following sections call this method to verify that Google Play services is - available. -</p> -<!-- - Define Location Services Callbacks - --> -<h2 id="DefineCallbacks">Define Location Services Callbacks</h2> -<p> - Before you request location updates, you must first implement the interfaces that Location - Services uses to communicate connection status to your app: -</p> -<dl> - <dt> -<code><a href="{@docRoot}reference/com/google/android/gms/common/GooglePlayServicesClient.ConnectionCallbacks.html">ConnectionCallbacks</a></code> - </dt> - <dd> - Specifies methods that Location Services calls when a location client is connected or - disconnected. - </dd> - <dt> -<code><a href="{@docRoot}reference/com/google/android/gms/common/GooglePlayServicesClient.OnConnectionFailedListener.html">OnConnectionFailedListener</a></code> - </dt> - <dd> - Specifies a method that Location Services calls if an error occurs while attempting to - connect the location client. This method uses the previously-defined {@code showErrorDialog} - method to display an error dialog that attempts to fix the problem using Google Play - services. - </dd> -</dl> -<p> - The following snippet shows how to specify the interfaces and define the methods: -</p> + +<p>The priority of + <a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#PRIORITY_HIGH_ACCURACY">{@code PRIORITY_HIGH_ACCURACY}</a>, + combined with the + {@link android.Manifest.permission#ACCESS_FINE_LOCATION ACCESS_FINE_LOCATION} + permission setting that you've defined in the app manifest, and a fast update + interval of 5000 milliseconds (5 seconds), causes the fused location + provider to return location updates that are accurate to within a few feet. + This approach is appropriate for mapping apps that display the location in + real time.</p> + +<p class="note"><strong>Performance hint:</strong> If your app accesses the + network or does other long-running work after receiving a location update, + adjust the fastest interval to a slower value. This adjustment prevents your + app from receiving updates it can't use. Once the long-running work is done, + set the fastest interval back to a fast value.</p> + +<h2 id="updates">Request Location Updates</h2> + +<p>Now that you've set up a location request containing your app's requirements + for the location updates, you can start the regular updates by calling + <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html#requestLocationUpdates(com.google.android.gms.common.api.GoogleApiClient, com.google.android.gms.location.LocationRequest, com.google.android.gms.location.LocationListener)">{@code requestLocationUpdates()}</a>. + Do this in the + <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.ConnectionCallbacks.html#onConnected(android.os.Bundle)">{@code onConnected()}</a> + callback provided by Google API Client, which is called when the client is + ready.</p> + +<p>Depending on the form of the request, the fused location provider either + invokes the + <a href="{@docRoot}reference/com/google/android/gms/location/LocationListener.html">{@code LocationListener.onLocationChanged()}</a> + callback method and passes it a {@link android.location.Location} object, or + issues a + <a href="{@docRoot}reference/android/app/PendingIntent.html">{@code PendingIntent}</a> + that contains the location in its extended data. The accuracy and frequency of + the updates are affected by the location permissions you've requested and the + options you set in the location request object.</p> + +<p>This lesson shows you how to get the update using the + <a href="{@docRoot}reference/com/google/android/gms/location/LocationListener.html">{@code LocationListener}</a> + callback approach. Call + <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html#requestLocationUpdates(com.google.android.gms.common.api.GoogleApiClient, com.google.android.gms.location.LocationRequest, com.google.android.gms.location.LocationListener)">{@code requestLocationUpdates()}</a>, + passing it your instance of the + <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code GoogleApiClient}</a>, + the + <a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html">{@code LocationRequest}</a> + object, + and a <a href="{@docRoot}reference/com/google/android/gms/location/LocationListener.html">{@code LocationListener}</a>. + Define a {@code startLocationUpdates()} method, called from the + <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.ConnectionCallbacks.html#onConnected(android.os.Bundle)">{@code onConnected()}</a> + callback, as shown in the following code sample:</p> + <pre> -public class MainActivity extends FragmentActivity implements - GooglePlayServicesClient.ConnectionCallbacks, - GooglePlayServicesClient.OnConnectionFailedListener { +@Override +public void onConnected(Bundle connectionHint) { ... - /* - * Called by Location Services when the request to connect the - * client finishes successfully. At this point, you can - * request the current location or start periodic updates - */ - @Override - public void onConnected(Bundle dataBundle) { - // Display the connection status - Toast.makeText(this, "Connected", Toast.LENGTH_SHORT).show(); + if (mRequestingLocationUpdates) { + startLocationUpdates(); } - ... - /* - * Called by Location Services if the connection to the - * location client drops because of an error. - */ - @Override - public void onDisconnected() { - // Display the connection status - Toast.makeText(this, "Disconnected. Please re-connect.", - Toast.LENGTH_SHORT).show(); - } - ... - /* - * Called by Location Services if the attempt to - * Location Services fails. - */ - @Override - public void onConnectionFailed(ConnectionResult connectionResult) { - /* - * Google Play services can resolve some errors it detects. - * If the error has a resolution, try sending an Intent to - * start a Google Play services activity that can resolve - * error. - */ - if (connectionResult.hasResolution()) { - try { - // Start an Activity that tries to resolve the error - connectionResult.startResolutionForResult( - this, - CONNECTION_FAILURE_RESOLUTION_REQUEST); - /* - * Thrown if Google Play services canceled the original - * PendingIntent - */ - } catch (IntentSender.SendIntentException e) { - // Log the error - e.printStackTrace(); - } - } else { - /* - * If no resolution is available, display a dialog to the - * user with the error. - */ - showErrorDialog(connectionResult.getErrorCode()); - } - } - ... +} + +protected void startLocationUpdates() { + LocationServices.FusedLocationApi.requestLocationUpdates( + mGoogleApiClient, mLocationRequest, this); } </pre> -<h3>Define the location update callback</h3> -<p> - Location Services sends location updates to your app either as an {@link android.content.Intent} - or as an argument passed to a callback method you define. This lesson shows you how to get the - update using a callback method, because that pattern works best for most use cases. If you want - to receive updates in the form of an {@link android.content.Intent}, read the lesson - <a href="activity-recognition.html">Recognizing the User's Current Activity</a>, which - presents a similar pattern. -</p> -<p> - The callback method that Location Services invokes to send a location update to your app is - specified in the -<code><a href="{@docRoot}reference/com/google/android/gms/location/LocationListener.html">LocationListener</a></code> - interface, in the method -<code><a href="{@docRoot}reference/com/google/android/gms/location/LocationListener.html#onLocationChanged(android.location.Location)">onLocationChanged()</a></code>. - The incoming argument is a {@link android.location.Location} object containing the location's - latitude and longitude. The following snippet shows how to specify the interface and define - the method: -</p> + +<p>Notice that the above code snippet refers to a boolean flag, + {@code mRequestingLocationUpdates}, used to track whether the user has + turned location updates on or off. For more about retaining the value of this + flag across instances of the activity, see + <a href="#save-state">Save the State of the Activity</a>. + +<h2 id="callback">Define the Location Update Callback</h2> + +<p>The fused location provider invokes the + <a href="{@docRoot}reference/com/google/android/gms/location/LocationListener.html#onLocationChanged(android.location.Location)">{@code LocationListener.onLocationChanged()}</a> + callback method. The incoming argument is a {@link android.location.Location} + object containing the location's latitude and longitude. The following snippet + shows how to implement the + <a href="{@docRoot}reference/com/google/android/gms/location/LocationListener.html">{@code LocationListener}</a> + interface and define the method, then get the timestamp of the location update + and display the latitude, longitude and timestamp on your app's user + interface:</p> + <pre> -public class MainActivity extends FragmentActivity implements - GooglePlayServicesClient.ConnectionCallbacks, - GooglePlayServicesClient.OnConnectionFailedListener, - LocationListener { +public class MainActivity extends ActionBarActivity implements + ConnectionCallbacks, OnConnectionFailedListener, LocationListener { ... - // Define the callback method that receives location updates @Override public void onLocationChanged(Location location) { - // Report to the UI that the location was updated - String msg = "Updated Location: " + - Double.toString(location.getLatitude()) + "," + - Double.toString(location.getLongitude()); - Toast.makeText(this, msg, Toast.LENGTH_SHORT).show(); + mCurrentLocation = location; + mLastUpdateTime = DateFormat.getTimeInstance().format(new Date()); + updateUI(); + } + + private void updateUI() { + mLatitudeTextView.setText(String.valueOf(mCurrentLocation.getLatitude())); + mLongitudeTextView.setText(String.valueOf(mCurrentLocation.getLongitude())); + mLastUpdateTimeTextView.setText(mLastUpdateTime); } - ... } </pre> -<p> - Now that you have the callbacks prepared, you can set up the request for location updates. - The first step is to specify the parameters that control the updates. -</p> -<!-- Specify update parameters --> -<h2 id="UpdateParameters">Specify Update Parameters</h2> -<p> - Location Services allows you to control the interval between updates and the location accuracy - you want, by setting the values in a -<code><a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html">LocationRequest</a></code> - object and then sending this object as part of your request to start updates. -</p> -<p> - First, set the following interval parameters: -</p> -<dl> - <dt> - Update interval - </dt> - <dd> - Set by -<code><a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#setInterval(long)">LocationRequest.setInterval()</a></code>. - This method sets the rate in milliseconds at which your app prefers to receive location - updates. If no other apps are receiving updates from Location Services, your app will - receive updates at this rate. - </dd> - <dt> - Fastest update interval - </dt> - <dd> - Set by -<code><a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#setFastestInterval(long)">LocationRequest.setFastestInterval()</a></code>. - This method sets the <b>fastest</b> rate in milliseconds at which your app can handle - location updates. You need to set this rate because other apps also affect the rate - at which updates are sent. Location Services sends out updates at the fastest rate that any - app requested by calling -<code><a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#setInterval(long)">LocationRequest.setInterval()</a></code>. - If this rate is faster than your app can handle, you may encounter problems with UI flicker - or data overflow. To prevent this, call -<code><a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#setFastestInterval(long)">LocationRequest.setFastestInterval()</a></code> - to set an upper limit to the update rate. - <p> - Calling -<code><a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#setFastestInterval(long)">LocationRequest.setFastestInterval()</a></code> - also helps to save power. When you request a preferred update rate by calling -<code><a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#setInterval(long)">LocationRequest.setInterval()</a></code>, - and a maximum rate by calling -<code><a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#setFastestInterval(long)">LocationRequest.setFastestInterval()</a></code>, - then your app gets the same update rate as the fastest rate in the system. If other - apps have requested a faster rate, you get the benefit of a faster rate. If no other - apps have a faster rate request outstanding, your app receives updates at the rate you specified - with -<code><a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#setInterval(long)">LocationRequest.setInterval()</a></code>. - </p> - </dd> -</dl> -<p> - Next, set the accuracy parameter. In a foreground app, you need constant location updates with - high accuracy, so use the setting -<code><a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#PRIORITY_HIGH_ACCURACY">LocationRequest.PRIORITY_HIGH_ACCURACY</a></code>. -</p> -<p> - The following snippet shows how to set the update interval and accuracy in - {@link android.support.v4.app.FragmentActivity#onCreate onCreate()}: -</p> + +<h2 id="stop-updates">Stop Location Updates</h2> + +<p>Consider whether you want to stop the location updates when the activity is + no longer in focus, such as when the user switches to another app or to a + different activity in the same app. This can be handy to reduce power + consumption, provided the app doesn't need to collect information even when + it's running in the background. This section shows how you can stop the + updates in the activity's + {@link android.app.Activity#onPause onPause()} method.</p> + +<p>To stop location updates, call + <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html#removeLocationUpdates(com.google.android.gms.common.api.GoogleApiClient, com.google.android.gms.location.LocationListener)">{@code removeLocationUpdates()}</a>, + passing it your instance of the + <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code GoogleApiClient}</a> + object and a + <a href="{@docRoot}reference/com/google/android/gms/location/LocationListener.html">{@code LocationListener}</a>, + as shown in the following code sample:</p> + <pre> -public class MainActivity extends FragmentActivity implements - GooglePlayServicesClient.ConnectionCallbacks, - GooglePlayServicesClient.OnConnectionFailedListener, - LocationListener { - ... - // Global constants - ... - // Milliseconds per second - private static final int MILLISECONDS_PER_SECOND = 1000; - // Update frequency in seconds - public static final int UPDATE_INTERVAL_IN_SECONDS = 5; - // Update frequency in milliseconds - private static final long UPDATE_INTERVAL = - MILLISECONDS_PER_SECOND * UPDATE_INTERVAL_IN_SECONDS; - // The fastest update frequency, in seconds - private static final int FASTEST_INTERVAL_IN_SECONDS = 1; - // A fast frequency ceiling in milliseconds - private static final long FASTEST_INTERVAL = - MILLISECONDS_PER_SECOND * FASTEST_INTERVAL_IN_SECONDS; - ... - // Define an object that holds accuracy and frequency parameters - LocationRequest mLocationRequest; - ... - @Override - protected void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - // Create the LocationRequest object - mLocationRequest = LocationRequest.create(); - // Use high accuracy - mLocationRequest.setPriority( - LocationRequest.PRIORITY_HIGH_ACCURACY); - // Set the update interval to 5 seconds - mLocationRequest.setInterval(UPDATE_INTERVAL); - // Set the fastest update interval to 1 second - mLocationRequest.setFastestInterval(FASTEST_INTERVAL); - ... - } - ... +@Override +protected void onPause() { + super.onPause(); + stopLocationUpdates(); +} + +protected void stopLocationUpdates() { + LocationServices.FusedLocationApi.removeLocationUpdates( + mGoogleApiClient, this); } </pre> -<p class="note"> - <strong>Note:</strong> If your app accesses the network or does other long-running work after - receiving a location update, adjust the fastest interval to a slower value. This prevents your - app from receiving updates it can't use. Once the long-running work is done, set the fastest - interval back to a fast value. -</p> -<!-- Start Location Updates --> -<h2 id="StartUpdates">Start Location Updates</h2> -<p> - To send the request for location updates, create a location client in - {@link android.support.v4.app.FragmentActivity#onCreate onCreate()}, then connect it and make - the request by calling -<code><a href="{@docRoot}reference/com/google/android/gms/location/LocationClient.html#requestLocationUpdates(com.google.android.gms.location.LocationRequest, com.google.android.gms.location.LocationListener)">requestLocationUpdates()</a></code>. - Since your client must be connected for your app to receive updates, you should - connect the client in - {@link android.support.v4.app.FragmentActivity#onStart onStart()}. This ensures that you always - have a valid, connected client while your app is visible. Since you need a connection before you - can request updates, make the update request in -<code><a href="{@docRoot}reference/com/google/android/gms/common/GooglePlayServicesClient.ConnectionCallbacks.html#onConnected(android.os.Bundle)">ConnectionCallbacks.onConnected()</a></code> -</p> -<p> - Remember that the user may want to turn off location updates for various reasons. You should - provide a way for the user to do this, and you should ensure that you don't start updates in - {@link android.support.v4.app.FragmentActivity#onStart onStart()} if updates were previously - turned off. To track the user's preference, store it in your app's - {@link android.content.SharedPreferences} in - {@link android.support.v4.app.FragmentActivity#onPause onPause()} and retrieve it in - {@link android.support.v4.app.FragmentActivity#onResume onResume()}. -</p> -<p> - The following snippet shows how to set up the client in - {@link android.support.v4.app.FragmentActivity#onCreate onCreate()}, and how to connect it - and request updates in {@link android.support.v4.app.FragmentActivity#onStart onStart()}: -</p> + +<p>Use a boolean, {@code mRequestingLocationUpdates}, to track + whether location updates are currently turned on. In the activity's + {@link android.app.Activity#onResume onResume()} method, check + whether location updates are currently active, and activate them if not:</p> + <pre> -public class MainActivity extends FragmentActivity implements - GooglePlayServicesClient.ConnectionCallbacks, - GooglePlayServicesClient.OnConnectionFailedListener, - LocationListener { - ... - // Global variables - ... - LocationClient mLocationClient; - boolean mUpdatesRequested; - ... - @Override - protected void onCreate(Bundle savedInstanceState) { - ... - // Open the shared preferences - mPrefs = getSharedPreferences("SharedPreferences", - Context.MODE_PRIVATE); - // Get a SharedPreferences editor - mEditor = mPrefs.edit(); - /* - * Create a new location client, using the enclosing class to - * handle callbacks. - */ - mLocationClient = new LocationClient(this, this, this); - // Start with updates turned off - mUpdatesRequested = false; - ... - } - ... - @Override - protected void onPause() { - // Save the current setting for updates - mEditor.putBoolean("KEY_UPDATES_ON", mUpdatesRequested); - mEditor.commit(); - super.onPause(); - } - ... - @Override - protected void onStart() { - ... - mLocationClient.connect(); +@Override +public void onResume() { + super.onResume(); + if (mGoogleApiClient.isConnected() && !mRequestingLocationUpdates) { + startLocationUpdates(); } - ... - @Override - protected void onResume() { - /* - * Get any previous setting for location updates - * Gets "false" if an error occurs - */ - if (mPrefs.contains("KEY_UPDATES_ON")) { - mUpdatesRequested = - mPrefs.getBoolean("KEY_UPDATES_ON", false); - - // Otherwise, turn off location updates - } else { - mEditor.putBoolean("KEY_UPDATES_ON", false); - mEditor.commit(); - } - } - ... - /* - * Called by Location Services when the request to connect the - * client finishes successfully. At this point, you can - * request the current location or start periodic updates - */ - @Override - public void onConnected(Bundle dataBundle) { - // Display the connection status - Toast.makeText(this, "Connected", Toast.LENGTH_SHORT).show(); - // If already requested, start periodic updates - if (mUpdatesRequested) { - mLocationClient.requestLocationUpdates(mLocationRequest, this); - } - } - ... } </pre> -<p> - For more information about saving preferences, read -<a href="{@docRoot}training/basics/data-storage/shared-preferences.html">Saving Key-Value Sets</a>. -</p> -<!-- - Stop Location Updates - --> -<h2 id="StopUpdates">Stop Location Updates</h2> -<p> - To stop location updates, save the state of the update flag in - {@link android.support.v4.app.FragmentActivity#onPause onPause()}, and stop updates in - {@link android.support.v4.app.FragmentActivity#onStop onStop()} by calling -<code><a href="{@docRoot}reference/com/google/android/gms/location/LocationClient.html#removeLocationUpdates(com.google.android.gms.location.LocationListener)">removeLocationUpdates(LocationListener)</a></code>. - For example: -</p> + +<h2 id="save-state">Save the State of the Activity</h2> + +<p>A change to the device's configuration, such as a change in screen + orientation or language, can cause the current activity to be destroyed. Your + app must therefore store any information it needs to recreate the activity. + One way to do this is via an instance state stored in a + {@link android.os.Bundle} object.</p> + +<p>The following code sample shows how to use the activity's + <a href="{@docRoot}reference/android/app/Activity.html#onSaveInstanceState(android.os.Bundle)">{@code onSaveInstanceState()}</a> + callback to save the instance state:</p> + <pre> -public class MainActivity extends FragmentActivity implements - GooglePlayServicesClient.ConnectionCallbacks, - GooglePlayServicesClient.OnConnectionFailedListener, - LocationListener { +public void onSaveInstanceState(Bundle savedInstanceState) { + savedInstanceState.putBoolean(REQUESTING_LOCATION_UPDATES_KEY, + mRequestingLocationUpdates); + savedInstanceState.putParcelable(LOCATION_KEY, mCurrentLocation); + savedInstanceState.putString(LAST_UPDATED_TIME_STRING_KEY, mLastUpdateTime); + super.onSaveInstanceState(savedInstanceState); +} +</pre> + +<p>Define an {@code updateValuesFromBundle()} method to restore + the saved values from the previous instance of the activity, if they're + available. Call the method from the activity's + {@link android.app.Activity#onCreate onCreate()} method, as shown in the + following code sample:</p> + +<pre> +@Override +public void onCreate(Bundle savedInstanceState) { ... - /* - * Called when the Activity is no longer visible at all. - * Stop updates and disconnect. - */ - @Override - protected void onStop() { - // If the client is connected - if (mLocationClient.isConnected()) { - /* - * Remove location updates for a listener. - * The current Activity is the listener, so - * the argument is "this". - */ - removeLocationUpdates(this); + updateValuesFromBundle(savedInstanceState); +} + +private void updateValuesFromBundle(Bundle savedInstanceState) { + if (savedInstanceState != null) { + // Update the value of mRequestingLocationUpdates from the Bundle, and + // make sure that the Start Updates and Stop Updates buttons are + // correctly enabled or disabled. + if (savedInstanceState.keySet().contains(REQUESTING_LOCATION_UPDATES_KEY)) { + mRequestingLocationUpdates = savedInstanceState.getBoolean( + REQUESTING_LOCATION_UPDATES_KEY); + setButtonsEnabledState(); + } + + // Update the value of mCurrentLocation from the Bundle and update the + // UI to show the correct latitude and longitude. + if (savedInstanceState.keySet().contains(LOCATION_KEY)) { + // Since LOCATION_KEY was found in the Bundle, we can be sure that + // mCurrentLocationis not null. + mCurrentLocation = savedInstanceState.getParcelable(LOCATION_KEY); + } + + // Update the value of mLastUpdateTime from the Bundle and update the UI. + if (savedInstanceState.keySet().contains(LAST_UPDATED_TIME_STRING_KEY)) { + mLastUpdateTime = savedInstanceState.getString( + LAST_UPDATED_TIME_STRING_KEY); } - /* - * After disconnect() is called, the client is - * considered "dead". - */ - mLocationClient.disconnect(); - super.onStop(); + updateUI(); } - ... } </pre> -<p> - You now have the basic structure of an app that requests and receives periodic location updates. - You can combine the features described in this lesson with the geofencing, activity recognition, - or reverse geocoding features described in other lessons in this class. -</p> -<p> - The next lesson, <a href="display-address.html">Displaying a Location Address</a>, shows you how - to use the current location to display the current street address. -</p> + +<p>For more about saving instance state, see the + <a href="{@docRoot}reference/android/app/Activity.html#ConfigurationChanges">Android + Activity</a> class reference.</p> + +<p class="note"><strong>Note:</strong> For a more persistent storage, you can + store the user's preferences in your app's + {@link android.content.SharedPreferences}. Set the shared preference in + your activity's {@link android.app.Activity#onPause onPause()} method, and + retrieve the preference in {@link android.app.Activity#onResume onResume()}. + For more information about saving preferences, read + <a href="{@docRoot}training/basics/data-storage/shared-preferences.html">Saving + Key-Value Sets</a>.</p> + +<p>The next lesson, + <a href="display-address.html">Displaying a Location Address</a>, shows + you how to display the street address for a given location.</p> diff --git a/docs/html/training/material/drawables.jd b/docs/html/training/material/drawables.jd index fd21e3d..820a004 100644 --- a/docs/html/training/material/drawables.jd +++ b/docs/html/training/material/drawables.jd @@ -83,6 +83,16 @@ class.</p> <h2 id="VectorDrawables">Create Vector Drawables</h2> +<!-- video box --> +<a class="notice-developers-video" + href="https://www.youtube.com/watch?v=wlFVIIstKmA" + style="margin-top:18px"> +<div> + <h3>Video</h3> + <p>Android Vector Graphics</p> +</div> +</a> + <p>In Android 5.0 (API Level 21) and above, you can define vector drawables, which scale without losing definition. You need only one asset file for a vector image, as opposed to an asset file for each screen density in the case of bitmap images. To create a vector image, you define the details diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 2489b91..00eca7c 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -891,25 +891,30 @@ include the action bar on devices running Android 2.1 or higher." <div class="nav-section-header"> <a href="<?cs var:toroot ?>training/tv/start/index.html" + ja-lang="TV アプリのビルド" description="How to start building TV apps or extend your existing app to run on TV devices."> Building TV Apps</a> </div> <ul> <li> - <a href="<?cs var:toroot ?>training/tv/start/start.html"> + <a href="<?cs var:toroot ?>training/tv/start/start.html" + ja-lang="TV アプリのビルドを開始する"> Getting Started with TV Apps</a> </li> <li> - <a href="<?cs var:toroot ?>training/tv/start/hardware.html"> + <a href="<?cs var:toroot ?>training/tv/start/hardware.html" + ja-lang="TV ハードウェアを処理する"> Handling TV Hardware</a> </li> <li> - <a href="<?cs var:toroot ?>training/tv/start/layouts.html"> + <a href="<?cs var:toroot ?>training/tv/start/layouts.html" + ja-lang="TV 向けレイアウトをビルドする"> Building TV Layouts</a> </li> <li> - <a href="<?cs var:toroot ?>training/tv/start/navigation.html"> + <a href="<?cs var:toroot ?>training/tv/start/navigation.html" + ja-lang="TV 用のナビゲーションを作成する"> Creating TV Navigation</a> </li> </ul> @@ -918,20 +923,24 @@ include the action bar on devices running Android 2.1 or higher." <li class="nav-section"> <div class="nav-section-header"> <a href="<?cs var:toroot ?>training/tv/playback/index.html" + ja-lang="TV 再生アプリのビルド" 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"> + <a href="<?cs var:toroot ?>training/tv/playback/browse.html" + ja-lang="カタログ ブラウザを作成する"> Creating a Catalog Browser</a> </li> <li> - <a href="<?cs var:toroot ?>training/tv/playback/details.html"> + <a href="<?cs var:toroot ?>training/tv/playback/details.html" + ja-lang="詳細ビューをビルドする"> Building a Details View</a> </li> <li> - <a href="<?cs var:toroot ?>training/tv/playback/now-playing.html"> + <a href="<?cs var:toroot ?>training/tv/playback/now-playing.html" + ja-lang="再生中カードを表示する"> Displaying a Now Playing Card</a> </li> </ul> @@ -949,6 +958,9 @@ include the action bar on devices running Android 2.1 or higher." Recommending TV Content</a> </li> <li> + <a href="<?cs var:toroot ?>training/tv/discovery/searchable.html"> + Making TV Apps Searchable</a> + <li> <a href="<?cs var:toroot ?>training/tv/discovery/in-app-search.html"> Searching within TV Apps</a> </li> @@ -1713,6 +1725,10 @@ results." Enhancing Security with Device Management Policies </a> </li> + <li><a href="<?cs var:toroot ?>training/enterprise/app-compatibility.html"> + Ensuring Compatibility with Managed Profiles + </a> + </li> </ul> </li> </ul> diff --git a/docs/html/training/tv/discovery/recommendations.jd b/docs/html/training/tv/discovery/recommendations.jd index 0f6d256..d348c14 100644 --- a/docs/html/training/tv/discovery/recommendations.jd +++ b/docs/html/training/tv/discovery/recommendations.jd @@ -14,6 +14,11 @@ trainingnavtop=true <li><a href="#build">Build Recommendations</a></li> <li><a href="#run-service">Run Recommendations Service</a></li> </ol> + <h2>Try it out</h2> + <ul> + <li><a class="external-link" href="https://github.com/googlesamples/androidtv-Leanback">Android + Leanback sample app</a></li> + </ul> </div> </div> @@ -25,7 +30,7 @@ trainingnavtop=true <p> The Android framework assists with minimum-input interaction by providing a recommendations row - on the home screen. Content recommendations appear as the first row of the TV launch screen after + on the home screen. Content recommendations appear as the first row of the TV home screen after the first use of the device. Contributing recommendations from your app's content catalog can help bring users back to your app. </p> @@ -37,7 +42,9 @@ trainingnavtop=true <p> This lesson teaches you how to create recommendations and provide them to the Android framework - so your app content can be easily discovered and enjoyed by users. + so users can easily discover and enjoy your app content. This discussion describes some code from + the <a class="external-link" href="https://github.com/googlesamples/androidtv-Leanback">Android + Leanback sample app</a>. </p> @@ -46,7 +53,7 @@ trainingnavtop=true <p> Content recommendations are created with background processing. In order for your application to contribute to recommendations, create a service that periodically adds listings from your - app's catalog to the system list of recommendations. + app's catalog to the system's list of recommendations. </p> <p> @@ -54,26 +61,50 @@ trainingnavtop=true create a recommendation service for your application: </p> + +<p class="code-caption"> + <a href="https://github.com/googlesamples/androidtv-Leanback/blob/master/app/src/main/java/com/example/android/tvleanback/UpdateRecommendationsService.java" target="_blank"> + UpdateRecommendationsService.java</a> +</p> <pre> -public class RecommendationsService extends IntentService { +public class UpdateRecommendationsService extends IntentService { + private static final String TAG = "UpdateRecommendationsService"; private static final int MAX_RECOMMENDATIONS = 3; - public RecommendationsService() { + public UpdateRecommendationsService() { super("RecommendationService"); } @Override protected void onHandleIntent(Intent intent) { - MovieDatabase database = MovieDatabase.instance(getApplicationContext()); - List<Movie> recommendations = database.recommendations(); + Log.d(TAG, "Updating recommendation cards"); + HashMap<String, List<Movie>> recommendations = VideoProvider.getMovieList(); + if (recommendations == null) return; int count = 0; try { - for (Movie movie : recommendations) { - // build the individual content recommendations - buildRecommendation(getApplicationContext(), movie); - + RecommendationBuilder builder = new RecommendationBuilder() + .setContext(getApplicationContext()) + .setSmallIcon(R.drawable.videos_by_google_icon); + + for (Map.Entry<String, List<Movie>> entry : recommendations.entrySet()) { + for (Movie movie : entry.getValue()) { + Log.d(TAG, "Recommendation - " + movie.getTitle()); + + builder.setBackground(movie.getCardImageUrl()) + .setId(count + 1) + .setPriority(MAX_RECOMMENDATIONS - count) + .setTitle(movie.getTitle()) + .setDescription(getString(R.string.popular_header)) + .setImage(movie.getCardImageUrl()) + .setIntent(buildPendingIntent(movie)) + .build(); + + if (++count >= MAX_RECOMMENDATIONS) { + break; + } + } if (++count >= MAX_RECOMMENDATIONS) { break; } @@ -82,6 +113,21 @@ public class RecommendationsService extends IntentService { Log.e(TAG, "Unable to update recommendation", e); } } + + private PendingIntent buildPendingIntent(Movie movie) { + Intent detailsIntent = new Intent(this, DetailsActivity.class); + detailsIntent.putExtra("Movie", movie); + + TaskStackBuilder stackBuilder = TaskStackBuilder.create(this); + stackBuilder.addParentStack(DetailsActivity.class); + stackBuilder.addNextIntent(detailsIntent); + // Ensure a unique PendingIntents, otherwise all recommendations end up with the same + // PendingIntent + detailsIntent.setAction(Long.toString(movie.getId())); + + PendingIntent intent = stackBuilder.getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT); + return intent; + } } </pre> @@ -90,125 +136,165 @@ public class RecommendationsService extends IntentService { app manifest. The following code snippet illustrates how to declare this class as a service: </p> +<p class="code-caption"> + <a href="https://github.com/googlesamples/androidtv-Leanback/blob/master/app/src/main/AndroidManifest.xml" target="_blank"> + AndroidManifest.xml</a> +</p> <pre> <manifest ... > <application ... > ... - <service android:name=".RecommendationsService" - android:enabled="true" android:exported="true"/> + <service + android:name="com.example.android.tvleanback.UpdateRecommendationsService" + android:enabled="true" /> </application> </manifest> </pre> +<h3 id="refreshing">Refreshing Recommendations</h3> + +<p>Base your recommendations on user behavior and data such as play lists, wish lists, and associated +content. When refreshing recommendations, don't just remove and repost them, because doing so causes +the recommendations to appear at the end of the recommendations row. Once a content item, such as a +movie, has been played, <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html#Removing"> +remove it</a> from the recommendations.</p> <h2 id="build">Build Recommendations</h2> <p> - Once your recommendation server starts running, it must create recommendations and pass them to + Once your recommendation service starts running, it must create recommendations and pass them to the Android framework. The framework receives the recommendations as {@link android.app.Notification} objects that use a specific template and are marked with a specific category. </p> -<p> - The following code example demonstrates how to get an instance of the {@link - android.app.NotificationManager}, build a recommendation, and post it to the manager: -</p> +<h3 id="setting-ui">Setting the Values</h3> -<pre> -public class RecommendationsService extends IntentService { +<p>To set the UI element values for the recommendation card, you create a builder class that follows +the builder pattern described as follows. First, you set the values of the recommendation card +elements.</p> +<p class="code-caption"> + <a href="https://github.com/googlesamples/androidtv-Leanback/blob/master/app/src/main/java/com/example/android/tvleanback/RecommendationBuilder.java" target="_blank"> + RecommendationBuilder.java</a> +</p> +<pre> +public class RecommendationBuilder { ... - public Notification buildRecommendation(Context context, Movie movie) - throws IOException { + public RecommendationBuilder setTitle(String title) { + mTitle = title; + return this; + } + + public RecommendationBuilder setDescription(String description) { + mDescription = description; + return this; + } - if (mNotificationManager == null) { - mNotificationManager = (NotificationManager) - mContext.getSystemService(Context.NOTIFICATION_SERVICE); + public RecommendationBuilder setImage(String uri) { + mImageUri = uri; + return this; } - Bundle extras = new Bundle(); - if (mBackgroundUri != movie.getBackgroundUri()) { - extras.putString(EXTRA_BACKGROUND_IMAGE_URL, movie.getBackgroundUri()); + public RecommendationBuilder setBackground(String uri) { + mBackgroundUri = uri; + return this; } +... +</pre> + +<h3 id="create-notification">Creating the Notification</h3> + +<p> + Once you've set the values, you then build the notification, assigning the values from the builder + class to the notification, and calling {@link android.support.v4.app.NotificationCompat.Builder#build() + NotificationCompat.Builder.build()}. +</p> + +<p> + Also, be sure to call + {@link android.support.v4.app.NotificationCompat.Builder#setLocalOnly(boolean) setLocalOnly()} + so the {@link android.support.v4.app.NotificationCompat.BigPictureStyle} notification won't show up + on other devices. +</p> + +<p> + The following code example demonstrates how to build a recommendation, and post it to the manager. +</p> + +<p class="code-caption"> + <a href="https://github.com/googlesamples/androidtv-Leanback/blob/master/app/src/main/java/com/example/android/tvleanback/RecommendationBuilder.java" target="_blank"> + RecommendationBuilder.java</a> +</p> +<pre> +public class RecommendationBuilder { + ... + + public Notification build() throws IOException { + ... - // build the recommendation as a Notification object Notification notification = new NotificationCompat.BigPictureStyle( - new NotificationCompat.Builder(context) - .setContentTitle(movie.getTitle()) - .setContentText(movie.getDescription()) - .setContentInfo(APP_NAME) - .setGroup("ActionMovies") - .setSortKey("0.8") - .setPriority(movie.getPriority()) - .setColor(#FFFF2020) - .setCategory("recommendation") - .setLargeIcon(movie.getImage()) - .setSmallIcon(movie.getSmallIcon()) - .setContentIntent(buildPendingIntent(movie.getId())) + new NotificationCompat.Builder(mContext) + .setContentTitle(mTitle) + .setContentText(mDescription) + .setPriority(mPriority) + .setLocalOnly(true) + .setOngoing(true) + .setColor(mContext.getResources().getColor(R.color.fastlane_background)) + .setCategory(Notification.CATEGORY_RECOMMENDATION) + .setLargeIcon(image) + .setSmallIcon(mSmallIcon) + .setContentIntent(mIntent) .setExtras(extras)) .build(); - // post the recommendation to the NotificationManager - mNotificationManager.notify(movie.getId(), notification); + mNotificationManager.notify(mId, notification); mNotificationManager = null; return notification; } - - private PendingIntent buildPendingIntent(long id) { - Intent detailsIntent = new Intent(this, DetailsActivity.class); - detailsIntent.putExtra("id", id); - - TaskStackBuilder stackBuilder = TaskStackBuilder.create(this); - stackBuilder.addParentStack(DetailsActivity.class); - stackBuilder.addNextIntent(detailsIntent); - // Ensure each PendingIntent is unique - detailsIntent.setAction(Long.toString(id)); - - PendingIntent intent = stackBuilder.getPendingIntent( - 0, PendingIntent.FLAG_UPDATE_CURRENT); - return intent; - } } </pre> - -<h3 id="run-service">Run Recommendations Service</h3> +<h2 id="run-service">Run Recommendations Service</h3> <p> Your app's recommendation service must run periodically in order to create current recommendations. To run your service, create a class that runs a timer and invokes it at regular intervals. The following code example extends the {@link android.content.BroadcastReceiver} class to start periodic execution of a recommendation service - every 12 hours: + every half hour: </p> +<p class="code-caption"> + <a href="https://github.com/googlesamples/androidtv-Leanback/blob/master/app/src/main/java/com/example/android/tvleanback/BootupActivity.java" target="_blank"> + BootupActivity.java</a> +</p> <pre> -public class BootupReceiver extends BroadcastReceiver { +public class BootupActivity extends BroadcastReceiver { private static final String TAG = "BootupActivity"; private static final long INITIAL_DELAY = 5000; @Override public void onReceive(Context context, Intent intent) { + Log.d(TAG, "BootupActivity initiated"); if (intent.getAction().endsWith(Intent.ACTION_BOOT_COMPLETED)) { scheduleRecommendationUpdate(context); } } private void scheduleRecommendationUpdate(Context context) { - AlarmManager alarmManager = (AlarmManager)context.getSystemService( - Context.ALARM_SERVICE); - Intent recommendationIntent = new Intent(context, - UpdateRecommendationsService.class); - PendingIntent alarmIntent = PendingIntent.getService(context, 0, - recommendationIntent, 0); + Log.d(TAG, "Scheduling recommendations update"); + + AlarmManager alarmManager = (AlarmManager) context.getSystemService(Context.ALARM_SERVICE); + Intent recommendationIntent = new Intent(context, UpdateRecommendationsService.class); + PendingIntent alarmIntent = PendingIntent.getService(context, 0, recommendationIntent, 0); alarmManager.setInexactRepeating(AlarmManager.ELAPSED_REALTIME_WAKEUP, INITIAL_DELAY, - AlarmManager.INTERVAL_HALF_DAY, + AlarmManager.INTERVAL_HALF_HOUR, alarmIntent); } } @@ -221,10 +307,15 @@ public class BootupReceiver extends BroadcastReceiver { following sample code demonstrates how to add this configuration to the manifest: </p> +<p class="code-caption"> + <a href="https://github.com/googlesamples/androidtv-Leanback/blob/master/app/src/main/AndroidManifest.xml" target="_blank"> + AndroidManifest.xml</a> +</p> <pre> <manifest ... > <application ... > - <receiver android:name=".BootupReceiver" android:enabled="true" + <receiver android:name="com.example.android.tvleanback.BootupActivity" + android:enabled="true" android:exported="false"> <intent-filter> <action android:name="android.intent.action.BOOT_COMPLETED"/> @@ -234,7 +325,7 @@ public class BootupReceiver extends BroadcastReceiver { </manifest> </pre> -<p class="important"> +<p class="note"> <strong>Important:</strong> Receiving a boot completed notification requires that your app requests the {@link android.Manifest.permission#RECEIVE_BOOT_COMPLETED} permission. For more information, see {@link android.content.Intent#ACTION_BOOT_COMPLETED}. diff --git a/docs/html/training/tv/discovery/searchable.jd b/docs/html/training/tv/discovery/searchable.jd new file mode 100644 index 0000000..5d3b9e3 --- /dev/null +++ b/docs/html/training/tv/discovery/searchable.jd @@ -0,0 +1,383 @@ +page.title=Making TV Apps Searchable +page.tags="search","searchable" + +trainingnavtop=true + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + <h2>This lesson teaches you to</h2> + <ol> + <li><a href="#columns">Identify Columns</a></li> + <li><a href="#provide">Provide Search Suggestion Data</a></li> + <li><a href="#suggestions">Handle Search Suggestions</a></li> + <li><a href="#terms">Handle Search Terms</a></li> + <li><a href="#details">Deep Link to Your App in the Details Screen</a></li> + </ol> + <h2>You should also read</h2> + <ul> + <li><a href="{@docRoot}guide/topics/search/index.html">Search</a></li> + <li><a href="{@docRoot}training/search/index.html">Adding Search Functionality</a></li> + </ul> + <h2>Try it out</h2> + <ul> + <li><a class="external-link" href="https://github.com/googlesamples/androidtv-Leanback">Android Leanback sample app</a></li> + </ul> +</div> +</div> + +<p>Android TV uses the Android <a href="{@docRoot}guide/topics/search/index.html">search interface</a> +to retrieve content data from installed apps and deliver search results to the user. Your app's +content data can be included with these results, to give the user instant access to the content in +your app.</p> + +<p>Your app must provide Android TV with the data fields from which it generates suggested search +results as the user enters characters in the search dialog. To do that, your app must implement a +<a href="{@docRoot}guide/topics/providers/content-providers.html">Content Provider</a> that serves +up the suggestions along with a <a href="{@docRoot}guide/topics/search/searchable-config.html"> +{@code searchable.xml}</a> configuration file that describes the content +provider and other vital information for Android TV. You also need an activity that handles the +intent that fires when the user selects a suggested search result. All of this is described in +more detail in <a href="{@docRoot}guide/topics/search/adding-custom-suggestions.html">Adding Custom +Suggestions</a>. Here are described the main points for Android TV apps.</p> + +<p>This lesson builds on your knowledge of using search in Android to show you how to make your app +searchable in Android TV. Be sure you are familiar with the concepts explained in the +<a href="{@docRoot}guide/topics/search/index.html">Search API guide</a> before following this lesson. +See also the training <a href="{@docRoot}training/search/index.html">Adding Search Functionality</a>.</p> + +<p>This discussion describes some code from the +<a class="external-link" href="https://github.com/googlesamples/androidtv-Leanback">Android Leanback sample app</a>, +available on GitHub.</p> + +<h2 id="columns">Identify Columns</h2> + +<p>The {@link android.app.SearchManager} describes the data fields it expects by representing them as +columns of an SQLite database. Regardless of your data's format, you must map your data fields to +these columns, usually in the class that accessess your content data. For information about building +a class that maps your existing data to the required fields, see +<a href="{@docRoot}guide/topics/search/adding-custom-suggestions.html#SuggestionTable"> +Building a suggestion table</a>.</p> + +<p>The {@link android.app.SearchManager} class includes several columns for Android TV. Some of the +more important columns are described below.</p> + +<table> +<tr> + <th>Value</th> + <th>Description</th> +</tr><tr> + <td>{@code SUGGEST_COLUMN_TEXT_1}</td> + <td>The name of your content <strong>(required)</strong></td> +</tr><tr> + <td>{@code SUGGEST_COLUMN_TEXT_2}</td> + <td>A text description of your content</td> +</tr><tr> + <td>{@code SUGGEST_COLUMN_RESULT_CARD_IMAGE}</td> + <td>An image/poster/cover for your content</td> +</tr><tr> + <td>{@code SUGGEST_COLUMN_CONTENT_TYPE}</td> + <td>The MIME type of your media <strong>(required)</strong></td> +</tr><tr> + <td>{@code SUGGEST_COLUMN_VIDEO_WIDTH}</td> + <td>The resolution width of your media</td> +</tr><tr> + <td>{@code SUGGEST_COLUMN_VIDEO_HEIGHT}</td> + <td>The resolution height of your media</td> +</tr><tr> + <td>{@code SUGGEST_COLUMN_PRODUCTION_YEAR}</td> + <td>The production year of your content <strong>(required)</strong></td> +</tr><tr> + <td>{@code SUGGEST_COLUMN_DURATION}</td> + <td>The duration in milliseconds of your media</td> +</tr> +</table> + +<p>The search framework requires the following columns:</p> +<ul> + <li>{@link android.app.SearchManager#SUGGEST_COLUMN_TEXT_1}</li> + <li>{@link android.app.SearchManager#SUGGEST_COLUMN_CONTENT_TYPE}</li> + <li>{@link android.app.SearchManager#SUGGEST_COLUMN_PRODUCTION_YEAR}</li> +</ul> + +<p>When the values of these columns for your content match the values for the same content from other +providers found by Google servers, the system provides a +<a href="{@docRoot}training/app-indexing/deep-linking.html">deep link</a> to your app in the details +view for the content, along with links to the apps of other providers. This is discussed more in +<a href="#details">Display Content in the Details Screen</a>, below.</p> + +<p>Your application's database class might define the columns as follows:</p> + +<p class="code-caption"><a href="https://github.com/googlesamples/androidtv-Leanback/blob/master/app/src/main/java/com/example/android/tvleanback/VideoDatabase.java#L41" target="_blank"> +VideoDatabase.java</a></p> +<pre> +public class VideoDatabase { + //The columns we'll include in the video database table + public static final String KEY_NAME = SearchManager.SUGGEST_COLUMN_TEXT_1; + public static final String KEY_DESCRIPTION = SearchManager.SUGGEST_COLUMN_TEXT_2; + public static final String KEY_ICON = SearchManager.SUGGEST_COLUMN_RESULT_CARD_IMAGE; + public static final String KEY_DATA_TYPE = SearchManager.SUGGEST_COLUMN_CONTENT_TYPE; + public static final String KEY_IS_LIVE = SearchManager.SUGGEST_COLUMN_IS_LIVE; + public static final String KEY_VIDEO_WIDTH = SearchManager.SUGGEST_COLUMN_VIDEO_WIDTH; + public static final String KEY_VIDEO_HEIGHT = SearchManager.SUGGEST_COLUMN_VIDEO_HEIGHT; + public static final String KEY_AUDIO_CHANNEL_CONFIG = + SearchManager.SUGGEST_COLUMN_AUDIO_CHANNEL_CONFIG; + public static final String KEY_PURCHASE_PRICE = SearchManager.SUGGEST_COLUMN_PURCHASE_PRICE; + public static final String KEY_RENTAL_PRICE = SearchManager.SUGGEST_COLUMN_RENTAL_PRICE; + public static final String KEY_RATING_STYLE = SearchManager.SUGGEST_COLUMN_RATING_STYLE; + public static final String KEY_RATING_SCORE = SearchManager.SUGGEST_COLUMN_RATING_SCORE; + public static final String KEY_PRODUCTION_YEAR = SearchManager.SUGGEST_COLUMN_PRODUCTION_YEAR; + public static final String KEY_COLUMN_DURATION = SearchManager.SUGGEST_COLUMN_DURATION; + public static final String KEY_ACTION = SearchManager.SUGGEST_COLUMN_INTENT_ACTION; +... +</pre> + +<p>When you build the map from the {@link android.app.SearchManager} columns to your data fields, you +must also specify the {@link android.provider.BaseColumns#_ID} to give each row a unique ID.</p> + +<p class="code-caption"><a href="https://github.com/googlesamples/androidtv-Leanback/blob/master/app/src/main/java/com/example/android/tvleanback/VideoDatabase.java#L83" target="_blank"> +VideoDatabase.java</a></p> +<pre> +... + private static HashMap<String, String> buildColumnMap() { + HashMap<String, String> map = new HashMap<String, String>(); + map.put(KEY_NAME, KEY_NAME); + map.put(KEY_DESCRIPTION, KEY_DESCRIPTION); + map.put(KEY_ICON, KEY_ICON); + map.put(KEY_DATA_TYPE, KEY_DATA_TYPE); + map.put(KEY_IS_LIVE, KEY_IS_LIVE); + map.put(KEY_VIDEO_WIDTH, KEY_VIDEO_WIDTH); + map.put(KEY_VIDEO_HEIGHT, KEY_VIDEO_HEIGHT); + map.put(KEY_AUDIO_CHANNEL_CONFIG, KEY_AUDIO_CHANNEL_CONFIG); + map.put(KEY_PURCHASE_PRICE, KEY_PURCHASE_PRICE); + map.put(KEY_RENTAL_PRICE, KEY_RENTAL_PRICE); + map.put(KEY_RATING_STYLE, KEY_RATING_STYLE); + map.put(KEY_RATING_SCORE, KEY_RATING_SCORE); + map.put(KEY_PRODUCTION_YEAR, KEY_PRODUCTION_YEAR); + map.put(KEY_COLUMN_DURATION, KEY_COLUMN_DURATION); + map.put(KEY_ACTION, KEY_ACTION); + map.put(BaseColumns._ID, "rowid AS " + + BaseColumns._ID); + map.put(SearchManager.SUGGEST_COLUMN_INTENT_DATA_ID, "rowid AS " + + SearchManager.SUGGEST_COLUMN_INTENT_DATA_ID); + map.put(SearchManager.SUGGEST_COLUMN_SHORTCUT_ID, "rowid AS " + + SearchManager.SUGGEST_COLUMN_SHORTCUT_ID); + return map; + } +... +</pre> + +<p>In the example above, notice the mapping to the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA_ID} +field. This is the portion of the URI that points to the content unique to the data in this row — +that is, the last part of the URI describing where the content is stored. The first part of the URI, +when it is common to all of the rows in the table, is set in the +<a href="{@docRoot}guide/topics/search/searchable-config.html"> {@code searchable.xml}</a> file as the +<a href="{@docRoot}guide/topics/search/searchable-config.html#searchSuggestIntentData"> +{@code android:searchSuggestIntentData}</a> attribute, as described in +<a href="#suggestions">Handle Search Suggestions</a>, below. + +<p>If the first part of the URI is different for each row in the +table, you map that value with the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} field. +When the user selects this content, the intent that fires provides the intent data from the +combination of the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA_ID} +and either the {@code android:searchSuggestIntentData} attribute or the +{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} field value.</p> + +<h2 id="provide">Provide Search Suggestion Data</h2> + +<p>Implement a <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Provider</a> +to return search term suggestions to the Android TV search dialog. The system queries your content +provider for suggestions by calling the {@link android.content.ContentProvider#query(android.net.Uri, +java.lang.String[], java.lang.String, java.lang.String[], java.lang.String) query()} method each time +a letter is typed. In your implementation of {@link android.content.ContentProvider#query(android.net.Uri, +java.lang.String[], java.lang.String, java.lang.String[], java.lang.String) query()}, your content +provider searches your suggestion data and returns a {@link android.database.Cursor} that points to +the rows you have designated for suggestions.</p> + +<p class="code-caption"><a href="https://github.com/googlesamples/androidtv-Leanback/blob/master/app/src/main/java/com/example/android/tvleanback/VideoContentProvider.java" target="_blank"> +VideoContentProvider.java</a></p> +<pre> +@Override + public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, + String sortOrder) { + // Use the UriMatcher to see what kind of query we have and format the db query accordingly + switch (URI_MATCHER.match(uri)) { + case SEARCH_SUGGEST: + Log.d(TAG, "search suggest: " + selectionArgs[0] + " URI: " + uri); + if (selectionArgs == null) { + throw new IllegalArgumentException( + "selectionArgs must be provided for the Uri: " + uri); + } + return getSuggestions(selectionArgs[0]); + default: + throw new IllegalArgumentException("Unknown Uri: " + uri); + } + } + + private Cursor getSuggestions(String query) { + query = query.toLowerCase(); + String[] columns = new String[]{ + BaseColumns._ID, + VideoDatabase.KEY_NAME, + VideoDatabase.KEY_DESCRIPTION, + VideoDatabase.KEY_ICON, + VideoDatabase.KEY_DATA_TYPE, + VideoDatabase.KEY_IS_LIVE, + VideoDatabase.KEY_VIDEO_WIDTH, + VideoDatabase.KEY_VIDEO_HEIGHT, + VideoDatabase.KEY_AUDIO_CHANNEL_CONFIG, + VideoDatabase.KEY_PURCHASE_PRICE, + VideoDatabase.KEY_RENTAL_PRICE, + VideoDatabase.KEY_RATING_STYLE, + VideoDatabase.KEY_RATING_SCORE, + VideoDatabase.KEY_PRODUCTION_YEAR, + VideoDatabase.KEY_COLUMN_DURATION, + VideoDatabase.KEY_ACTION, + SearchManager.SUGGEST_COLUMN_INTENT_DATA_ID + }; + return mVideoDatabase.getWordMatch(query, columns); + } +... +</pre> + +<p>In your manifest file, the content provider receives special treatment. Rather than getting +tagged as an activity, it is described as a +<a href="{@docRoot}guide/topics/manifest/provider-element.html">{@code <provider>}</a>. The +provider includes the {@code android:searchSuggestAuthority} attribute to tell the system the +namespace of your content provider. Also, you must set its {@code android:exported} attribute to +{@code "true"} so that the Android global search can use the results returned from it.</p> + +<p class="code-caption"><a href="https://github.com/googlesamples/androidtv-Leanback/blob/master/app/src/main/AndroidManifest.xml" target="_blank"> +AndroidManifest.xml</a></p> +<pre> +<provider android:name="com.example.android.tvleanback.VideoContentProvider" + android:authorities="com.example.android.tvleanback" + android:exported="true" /> +</pre> + +<h2 id="suggestions">Handle Search Suggestions</h2> + +<p>Your app must include a <a href="{@docRoot}guide/topics/search/searchable-config.html"> +{@code res/xml/searchable.xml}</a> file to configure the search suggestions settings. It inlcudes +the <a href="{@docRoot}guide/topics/search/searchable-config.html#searchSuggestAuthority"> +{@code android:searchSuggestAuthority}</a> attribute to tell the system the namespace of your +content provider. This must match the string value you specify in the +<a href="{@docRoot}guide/topics/manifest/provider-element.html#auth">{@code android:authorities}</a> +attribute of the <a href="{@docRoot}guide/topics/manifest/provider-element.html">{@code <provider>} +</a> element in your {@code AndroidManifest.xml} file.</p> + +The <a href="{@docRoot}guide/topics/search/searchable-config.html">{@code searchable.xml}</a> file +must also include the <a href="{@docRoot}guide/topics/search/searchable-config.html#searchSuggestIntentAction"> +{@code android:searchSuggestIntentAction}</a> with the value {@code "android.intent.action.VIEW"} +to define the intent action for providing a custom suggestion. This is different from the intent +action for providing a search term, explained below. See also, +<a href="{@docRoot}guide/topics/search/adding-custom-suggestions.html#IntentAction">Declaring the +intent action</a> for other ways to declare the intent action for suggestions.</p> + +<p>Along with the intent action, your app must provide the intent data, which you specify with the +<a href="{@docRoot}guide/topics/search/searchable-config.html#searchSuggestIntentData"> +{@code android:searchSuggestIntentData}</a> attribute. This is the first part of the URI that points +to the content. It describes the portion of the URI common to all rows in the mapping table for that +content. The portion of the URI that is unique to each row is established with the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA_ID} field, +as described above in <a href="#columns">Identify Columns</a>. See also, +<a href="{@docRoot}guide/topics/search/adding-custom-suggestions.html#IntentData"> +Declaring the intent data</a> for other ways to declare the intent data for suggestions.</p> + +<p>Also, note the {@code android:searchSuggestSelection=" ?"} attribute which specifies the value passed +as the {@code selection} parameter of the {@link android.content.ContentProvider#query(android.net.Uri, +java.lang.String[], java.lang.String, java.lang.String[], java.lang.String) query()} method where the +question mark ({@code ?}) value is replaced with the query text.</p> + +<p>Finally, you must also include the <a href="{@docRoot}guide/topics/search/searchable-config.html#includeInGlobalSearch"> +{@code android:includeInGlobalSearch}</a> attribute with the value {@code "true"}. Here is an example +<a href="{@docRoot}guide/topics/search/searchable-config.html">{@code searchable.xml}</a> +file:</p> + +<p class="code-caption"><a href="https://github.com/googlesamples/androidtv-Leanback/blob/master/app/src/main/res/xml/searchable.xml" target="_blank"> +Searchable.xml</a></p> +<pre> +<searchable xmlns:android="http://schemas.android.com/apk/res/android" + android:label="@string/search_label" + android:hint="@string/search_hint" + android:searchSettingsDescription="@string/settings_description" + android:searchSuggestAuthority="com.example.android.tvleanback" + android:searchSuggestIntentAction="android.intent.action.VIEW" + android:searchSuggestIntentData="content://com.example.android.tvleanback/video_database_leanback" + android:searchSuggestSelection=" ?" + android:searchSuggestThreshold="1" + android:includeInGlobalSearch="true" + > +</searchable> +</pre> + +<h2 id="terms">Handle Search Terms</h2> + +<p>As soon as the search dialog has a word which matches the value in one of your app's columns +(described in <a href="#identifying">Identifying Columns</a>, above), the system fires the +{@link android.content.Intent#ACTION_SEARCH} intent. The activity in your app which handles that +intent searches the repository for columns with the given word in their values, and returns a list +of content items with those columns. In your {@code AndroidManifest.xml} file, you designate the +activity which handles the {@link android.content.Intent#ACTION_SEARCH} intent like this: + +<p class="code-caption"><a href="https://github.com/googlesamples/androidtv-Leanback/blob/master/app/src/main/AndroidManifest.xml" target="_blank"> +AndroidManifest.xml</a></p> +<pre> +... + <activity + android:name="com.example.android.tvleanback.DetailsActivity" + android:exported="true"> + + <!-- Receives the search request. --> + <intent-filter> + <action android:name="android.intent.action.SEARCH" /> + <!-- No category needed, because the Intent will specify this class component --> + </intent-filter> + + <!-- Points to searchable meta data. --> + <meta-data android:name="android.app.searchable" + android:resource="@xml/searchable" /> + </activity> +... + <!-- Provides search suggestions for keywords against video meta data. --> + <provider android:name="com.example.android.tvleanback.VideoContentProvider" + android:authorities="com.example.android.tvleanback" + android:exported="true" /> +... +</pre> + +<p>The activity must also describe the searchable configuration with a reference to the +<a href="{@docRoot}guide/topics/search/searchable-config.html">{@code searchable.xml}</a> file. +To <a href="{@docRoot}guide/topics/search/search-dialog.html">use the global search dialog</a>, +the manifest must describe which activity should receive search queries. The manifest must also +describe the <a href="{@docRoot}guide/topics/manifest/provider-element.html">{@code <provider>} +</a>element, exactly as it is described in the <a href="{@docRoot}guide/topics/search/searchable-config.html"> +{@code searchable.xml}</a> file.</p> + +<h2 id="details">Deep Link to Your App in the Details Screen</h2> + +<p>If you have set up the search configuration as described in <a href="#suggestions">Handle Search +Suggestions</a> and mapped the {@link android.app.SearchManager#SUGGEST_COLUMN_TEXT_1}, +{@link android.app.SearchManager#SUGGEST_COLUMN_CONTENT_TYPE}, and +{@link android.app.SearchManager#SUGGEST_COLUMN_PRODUCTION_YEAR} fields as described in +<a href="#columns">Identify Columns</a>, a <a href="{@docRoot}training/app-indexing/deep-linking.html"> +deep link</a> to your content appears in the details screen that launches when the user selects a +search result.</p> + +<p>When the user selects the link for your app, identified by the "Available On" button in the +details screen, the system launches the activity which handles the {@link android.content.Intent#ACTION_VIEW} +(set as <a href="{@docRoot}guide/topics/search/searchable-config.html#searchSuggestIntentAction"> +{@code android:searchSuggestIntentAction}</a> with the value {@code "android.intent.action.VIEW"} in +the <a href="{@docRoot}guide/topics/search/searchable-config.html">{@code searchable.xml}</a> file).</p> + +<p>You can also set up a custom intent to launch your activity, and this is demonstrated in the +<a class="external-link" href="https://github.com/googlesamples/androidtv-Leanback">Android Leanback +sample app</a>. Note that the sample app launches its own <code>LeanbackDetailsFragment</code> to +show the details for the selected media, but you should launch the activity that plays the media +immediately to save the user another click or two.</p> + + + + + + diff --git a/docs/html/training/wearables/ui/lists.jd b/docs/html/training/wearables/ui/lists.jd index 1d6e8ed..20f8bbd 100644 --- a/docs/html/training/wearables/ui/lists.jd +++ b/docs/html/training/wearables/ui/lists.jd @@ -82,20 +82,21 @@ the list is displayed properly on both round and square devices:</p> <p>In many cases, each list item consists of an icon and a description. The <em>Notifications</em> sample from the Android SDK implements a custom layout that extends {@link android.widget.LinearLayout} to incorporate these two elements inside each list item. -This layout also implements the methods in the <code>WearableListView.Item</code> interface -to animate the item's icon and fade the text in response to events from +This layout also implements the methods in the +<code>WearableListView.OnCenterProximityListener</code> interface +to change the color of the item's icon and fade the text in response to events from <code>WearableListView</code> as the user scrolls through the list.</p> <pre> public class WearableListItemLayout extends LinearLayout - implements WearableListView.Item { + implements WearableListView.OnCenterProximityListener { + + private ImageView mCircle; + private TextView mName; private final float mFadedTextAlpha; private final int mFadedCircleColor; private final int mChosenCircleColor; - private ImageView mCircle; - private float mScale; - private TextView mName; public WearableListItemLayout(Context context) { this(context, null); @@ -108,6 +109,7 @@ public class WearableListItemLayout extends LinearLayout public WearableListItemLayout(Context context, AttributeSet attrs, int defStyle) { super(context, attrs, defStyle); + mFadedTextAlpha = getResources() .getInteger(R.integer.action_text_faded_alpha) / 100f; mFadedCircleColor = getResources().getColor(R.color.grey); @@ -124,46 +126,27 @@ public class WearableListItemLayout extends LinearLayout mName = (TextView) findViewById(R.id.name); } - // Provide scaling values for WearableListView animations @Override - public float getProximityMinValue() { - return 1f; - } - - @Override - public float getProximityMaxValue() { - return 1.6f; - } - - @Override - public float getCurrentProximityValue() { - return mScale; - } - - // Scale the icon for WearableListView animations - @Override - public void setScalingAnimatorValue(float scale) { - mScale = scale; - mCircle.setScaleX(scale); - mCircle.setScaleY(scale); - } - - // Change color of the icon, remove fading from the text - @Override - public void onScaleUpStart() { + public void onCenterPosition(boolean animate) { mName.setAlpha(1f); ((GradientDrawable) mCircle.getDrawable()).setColor(mChosenCircleColor); } - // Change the color of the icon, fade the text @Override - public void onScaleDownStart() { + public void onNonCenterPosition(boolean animate) { ((GradientDrawable) mCircle.getDrawable()).setColor(mFadedCircleColor); mName.setAlpha(mFadedTextAlpha); } } </pre> +<p>You can also create animator objects to enlarge the icon of the center item in the list. You can +use the <code>onCenterPosition()</code> and <code>onNonCenterPosition()</code> callback methods +in the <code>WearableListView.OnCenterProximityListener</code> interface to manage your +animators. For more information about animators, see +<a href="{@docRoot}guide/topics/graphics/prop-animation.html#object-animator">Animating with +ObjectAnimator</a>.</p> + <h2 id="layout-def">Create a Layout Definition for Items</h2> |