Merge "docs: Adds new topic: Change Location Settings" into mnc-docs
diff --git a/docs/html/training/location/change-location-settings.jd b/docs/html/training/location/change-location-settings.jd
new file mode 100644
index 0000000..70733eb
--- /dev/null
+++ b/docs/html/training/location/change-location-settings.jd
@@ -0,0 +1,251 @@
+page.title=Changing Location Settings
+trainingnavtop=true
+@jd:body
+
+<div id="tb-wrapper">
+ <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="#get-settings">Get Current Location Settings</a></li>
+ <li><a href="#prompt">Prompt the User to Change Location Settings</a></li>
+ </ol>
+
+ <h2>You should also read</h2>
+ <ul>
+ <li>
+ <a href="https://developers.google.com/android/guides/setup"
+ class="external-link">Setting up Google Play Services</a>
+ </li>
+ <li>
+ <a href="retrieve-current.html">Getting the Last Known Location</a>
+ </li>
+ </ul>
+ </div>
+</div>
+
+<p>If your app needs to request location or receive permission updates, the
+ device needs to enable the appropriate system settings, such as GPS or Wi-Fi
+ scanning. Rather than directly enabling services such as the device's GPS,
+ your app specifies the required level of accuracy/power consumption and
+ desired update interval, and the device automatically makes the appropriate
+ changes to system settings. These settings are defined by the
+ <a href="https://developers.google.com/android/reference/com/google/android/gms/location/LocationRequest"
+ class="external-link">{@code LocationRequest}</a>
+ data object. </p>
+
+<p>This lesson shows you how to use the
+ <a href="https://developers.google.com/android/reference/com/google/android/gms/location/SettingsApi">Settings API</a>
+ to check which settings are enabled, and present the Location Settings
+ dialog for the user to update their settings with a single tap.</p>
+
+<h2 id="connect">Connect to Location Services</h2>
+
+<p>In order to use the location services provided by Google Play Services and
+ the fused location provider, connect your app using the
+ <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient">Google API Client</a>,
+ then check the current location settings and prompt the user to enable the
+ required settings if needed. For details on connecting with the
+ Google API client, see <a href="retrieve-current.html">Getting the Last Known Location</a>.</p>
+
+<p>Apps that use location services must request location permissions. For this
+ lesson, coarse location detection is sufficient. Request this permission
+ with the <code>uses-permission</code> element in your app manifest, as shown
+ in the following example:</p>
+
+<pre><code><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_COARSE_LOCATION"/>
+</manifest>
+</code></pre>
+
+<p>If the device is running Android 6.0 or higher, and your app's target
+ SDK is 23 or higher, the app has to list the permissions in the manifest
+ <em>and</em> request those permissions at run time. For more information, see
+<a href="{@docRoot}training/permissions/requesting.html">Requesting Permissions at Run Time</a>.</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="https://developers.google.com/android/reference/com/google/android/gms/location/LocationRequest.html">{@code LocationRequest}</a>.
+ The parameters determine the level of accuracy for location requests. For
+ details of all available location request options, see the
+ <a href="https://developers.google.com/android/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="https://developers.google.com/android/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="https://developers.google.com/android/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="https://developers.google.com/android/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="https://developers.google.com/android/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="https://developers.google.com/android/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="https://developers.google.com/android/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="https://developers.google.com/android/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
+ to determine the location.</li>
+ <li><a href="https://developers.google.com/android/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="https://developers.google.com/android/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>
+protected void createLocationRequest() {
+ LocationRequest mLocationRequest = new LocationRequest();
+ mLocationRequest.setInterval(10000);
+ mLocationRequest.setFastestInterval(5000);
+ mLocationRequest.setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY);
+}
+</pre>
+
+<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="get-settings">Get Current Location Settings</h2>
+
+<p>Once you have connected to Google Play services and the location services
+ API, you can get the current location settings of a user's device. To do
+ this, create a
+ <a href="{@docRoot}reference/com/google/android/gms/location/LocationSettingsRequest.Builder"><code>LocationSettingsRequest.Builder</code></a>,
+ and add one or more location requests. The following code snippet shows how
+ to add the location request that was created in the previous step:</p>
+
+<pre>LocationSettingsRequest.Builder builder = new LocationSettingsRequest.Builder()
+ .addLocationRequest(mLocationRequest);
+</pre>
+
+<p>Next check whether the current location settings are satisfied:</p>
+
+<pre>PendingResult<LocationSettingsResult> result =
+ LocationServices.SettingsApi.checkLocationSettings(mGoogleClient,
+ builder.build());</pre>
+
+<p>When the <a href="{@docRoot}reference/com/google/android/gms/common/api/PendingResult"><code>PendingResult</code></a>
+ returns, your app can check the location settings by looking at the status
+ code from the <a href="{@docRoot}reference/com/google/android/gms/location/LocationSettingsResult"><code>LocationSettingsResult</code></a>
+ object. To get even more details about the the current state of the relevant
+ location settings, your app can call the
+ <a href="{@docRoot}reference/com/google/android/gms/location/LocationSettingsResult">{@code LocationSettingsResult}</a>
+ object's
+ <a href="{@docRoot}reference/com/google/android/gms/location/LocationSettingsResult#getLocationSettingsStates"><code>getLocationSettingsStates()</code></a>
+ method.</p>
+
+<h2 id="prompt">Prompt the User to Change Location Settings</h2>
+
+<p>To determine whether the location settings are appropriate for the location
+ request, check the status code from the
+ <a href="{@docRoot}reference/com/google/android/gms/location/LocationSettingsResult">{@code LocationSettingsResult}</a>
+ object. A status code of <code>RESOLUTION_REQUIRED</code> indicates that the
+ settings must be changed. To prompt the user for permission to modify the
+ location settings, call
+ <a href="{@docRoot}reference/com/google/android/gms/common/api/Status#startResolutionForResult(android.app.Activity, int)">
+ {@code startResolutionForResult(Activity, int)}</a>.
+ This method brings up a dialog asking for the user's permission to modify
+ location settings. The following code snippet shows how to check the location
+ settings, and how to call {@code startResolutionForResult(Activity, int)}.
+</p>
+
+<pre>result.setResultCallback(new ResultCallback<LocationSettingsResult>()) {
+ @Override
+ public void onResult(LocationSettingsResult result) {
+ final Status status = result.getStatus();
+ final LocationSettingsStates = result.getLocationSettingsStates();
+ switch (status.getStatusCode()) {
+ case LocationSettingsStatusCodes.SUCCESS:
+ // All location settings are satisfied. The client can
+ // initialize location requests here.
+ ...
+ break;
+ case LocationSettingsStatusCodes.RESOLUTION_REQUIRED:
+ // Location settings are not satisfied, but this can be fixed
+ // by showing the user a dialog.
+ try {
+ // Show the dialog by calling startResolutionForResult(),
+ // and check the result in onActivityResult().
+ status.startResolutionForResult(
+ OuterClass.this,
+ REQUEST_CHECK_SETTINGS);
+ } catch (SendIntentException e) {
+ // Ignore the error.
+ }
+ break;
+ case LocationSettingsStatusCodes.SETTINGS_CHANGE_UNAVAILABLE:
+ // Location settings are not satisfied. However, we have no way
+ // to fix the settings so we won't show the dialog.
+ ...
+ break;
+ }
+ }
+ });</pre>
+
+ <p>The next lesson,
+ <a href="receive-location-updates.html">Receiving Location Updates</a>, shows
+ you how to receive periodic location updates.</p>
diff --git a/docs/html/training/location/index.jd b/docs/html/training/location/index.jd
index 8ed2071..dd6825c 100644
--- a/docs/html/training/location/index.jd
+++ b/docs/html/training/location/index.jd
@@ -79,6 +79,10 @@
Learn how to retrieve the last known location of an Android device, which
is usually equivalent to the user's current location.
</dd> <dt>
+ <b><a href="change-location-settings.html">Changing Location Settings</a></b>
+ <dt> <dd>
+ Learn how to detect and apply system settings for location features.
+ </dd> <dt>
<b><a href="receive-location-updates.html">Receiving Location
Updates</a></b>
</dt> <dd>
diff --git a/docs/html/training/location/receive-location-updates.jd b/docs/html/training/location/receive-location-updates.jd
index 208dc17..d82905f 100644
--- a/docs/html/training/location/receive-location-updates.jd
+++ b/docs/html/training/location/receive-location-updates.jd
@@ -7,8 +7,7 @@
<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="#get-last-location">Get the Last Known Location</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>
@@ -19,7 +18,7 @@
<ul>
<li>
<a href="{@docRoot}google/play-services/setup.html">Setting up Google Play
- Services</a>
+ Services</a>
</li>
<li>
<a href="retrieve-current.html">Getting the Last Known Location</a>
@@ -64,16 +63,7 @@
<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>
+<h2 id="get-last-location">Get the Last Known Location</h2>
<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
@@ -101,112 +91,13 @@
</manifest>
</pre>
-<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>
-protected void createLocationRequest() {
- LocationRequest mLocationRequest = new LocationRequest();
- mLocationRequest.setInterval(10000);
- mLocationRequest.setFastestInterval(5000);
- mLocationRequest.setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY);
-}
-</pre>
-
-<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
+<p>Before requesting location updates, your app must connect to location
+ services and make a location request. The lesson on
+ <a href="change-location-settings.html">Changing Location Settings</a>
+ shows you how to do this. Once a location request is in place 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>
diff --git a/docs/html/training/location/retrieve-current.jd b/docs/html/training/location/retrieve-current.jd
index 206345f..c49b666 100644
--- a/docs/html/training/location/retrieve-current.jd
+++ b/docs/html/training/location/retrieve-current.jd
@@ -77,7 +77,7 @@
<pre>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.google.android.gms.location.sample.basiclocationsample" >
-
+
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
</manifest>
</pre>
@@ -180,5 +180,6 @@
when the location is not available.</p>
<p>The next lesson,
- <a href="receive-location-updates.html">Receiving Location Updates</a>, shows
- you how to receive periodic location updates.</p>
+ <a href="change-location-settings.html">Changing Location Settings</a>, shows
+ you how to detect the current location settings, and prompt the user to
+ change settings as appropriate for your app's requirements.</p>
diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs
index 3d1cf39..ff2f8d4 100644
--- a/docs/html/training/training_toc.cs
+++ b/docs/html/training/training_toc.cs
@@ -780,6 +780,11 @@
</a>
</li>
<li>
+ <a href="<?cs var:toroot ?>training/location/change-location-settings.html">
+ Changing Location Settings
+ </a>
+ </li>
+ <li>
<a href="<?cs var:toroot ?>training/location/receive-location-updates.html">
Receiving Location Updates
</a>
