diff options
Diffstat (limited to 'docs/html/training/basics/location/locationmanager.jd')
| -rw-r--r-- | docs/html/training/basics/location/locationmanager.jd | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/docs/html/training/basics/location/locationmanager.jd b/docs/html/training/basics/location/locationmanager.jd new file mode 100644 index 0000000..61abcbd --- /dev/null +++ b/docs/html/training/basics/location/locationmanager.jd @@ -0,0 +1,120 @@ +page.title=Using the Location Manager +parent.title=Making Your App Location Aware +parent.link=index.html + +trainingnavtop=true +next.title=Obtaining the Current Location +next.link=currentlocation.html + +@jd:body + + +<!-- This is the training bar --> +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="locationmanager.html#TaskDeclarePermissions">Declare Proper Permissions in Android Manifest</a></li> + <li><a href="locationmanager.html#TaskGetLocationManagerRef">Get a Reference to LocationManager</a></li> + <li><a href="locationmanager.html#TaskPickLocationProvider">Pick a Location Provider</a></li> + <li><a href="locationmanager.html#TaskVerifyProvider">Verify the Location Provider is Enabled</a></li> +</ol> + +<h2>You should also read</h2> + +<ul> + <li><a href="{@docRoot}guide/topics/location/index.html">Location and Maps</a></li> +</ul> + +<h2>Try it out</h2> + +<div class="download-box"> +<a href="http://developer.android.com/shareables/training/LocationAware.zip" class="button">Download + the sample app</a> +<p class="filename">LocationAware.zip</p> +</div> + +</div> +</div> + +<p>Before your application can begin receiving location updates, it needs to perform some simple steps to set up access. In this lesson, you'll learn what these steps entail.</p> + +<h2 id="TaskDeclarePermissions">Declare Proper Permissions in Android Manifest</h2> + +<p>The first step of setting up location update access is to declare proper permissions in the manifest. If permissions are missing, the application will get a {@link java.lang.SecurityException} at runtime.</p> + +<p>Depending on the {@link android.location.LocationManager} methods used, either {@link android.Manifest.permission#ACCESS_COARSE_LOCATION} or {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission is needed. For example, you need to declare the {@link android.Manifest.permission#ACCESS_COARSE_LOCATION} permission if your application uses a network-based location provider only. The more accurate GPS requires the {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission. +Note that declaring the {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission implies {@link android.Manifest.permission#ACCESS_COARSE_LOCATION} already.</p> + +<p>Also, if a network-based location provider is used in the application, you'll need to declare the internet permission as well.</p> + +<pre> +<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> +<uses-permission android:name="android.permission.INTERNET" /> +</pre> + +<h2 id="TaskGetLocationManagerRef">Get a Reference to LocationManager</h2> + +<p>{@link android.location.LocationManager} is the main class through which your application can access location services on Android. Similar to other system services, a reference can be obtained from calling the {@link android.content.Context#getSystemService(java.lang.String) getSystemService()} method. If your application intends to receive location updates in the foreground (within an {@link android.app.Activity}), you should usually perform this step in the {@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method.</p> + +<pre> +LocationManager locationManager = + (LocationManager) this.getSystemService(Context.LOCATION_SERVICE); +</pre> + +<h2 id="TaskPickLocationProvider">Pick a Location Provider</h2> + +<p>While not required, most modern Android-powered devices can receive location updates through multiple underlying technologies, which are abstracted to an application as {@link android.location.LocationProvider} objects. Location providers may have different performance characteristics in terms of time-to-fix, accuracy, monetary cost, power consumption, and so on. Generally, a location provider with a greater accuracy, like the GPS, requires a longer fix time than a less accurate one, such as a network-based location provider.</p> + +<p>Depending on your application's use case, you have to choose a specific location provider, or multiple providers, based on similar tradeoffs. For example, a points of interest check-in application would require higher location accuracy than say, a retail store locator where a city level location fix would suffice. The snippet below asks for a provider backed by the GPS.</p> + +<pre> +LocationProvider provider = + locationManager.getProvider(LocationManager.GPS_PROVIDER); +</pre> + +<p>Alternatively, you can provide some input criteria such as accuracy, power requirement, monetary cost, and so on, and let Android decide a closest match location provider. The snippet below asks for a location provider with fine accuracy and no monetary cost. Note that the criteria may not resolve to any providers, in which case a null will be returned. Your application should be prepared to gracefully handle the situation.</p> + +<pre> +// Retrieve a list of location providers that have fine accuracy, no monetary cost, etc +Criteria criteria = new Criteria(); +criteria.setAccuracy(Criteria.ACCURACY_FINE); +criteria.setCostAllowed(false); +... +String providerName = locManager.getBestProvider(criteria, true); + +// If no suitable provider is found, null is returned. +if (providerName != null) { + ... +} +</pre> + +<h2 id="TaskVerifyProvider">Verify the Location Provider is Enabled</h2> + +<p>Some location providers such as the GPS can be disabled in Settings. It is good practice to check whether the desired location provider is currently enabled by calling the {@link android.location.LocationManager#isProviderEnabled(java.lang.String) isProviderEnabled()} method. If the location provider is disabled, you can offer the user an opportunity to enable it in Settings by firing an {@link android.content.Intent} with the {@link android.provider.Settings#ACTION_LOCATION_SOURCE_SETTINGS} action.</p> + +<pre> +@Override +protected void onStart() { + super.onStart(); + + // This verification should be done during onStart() because the system calls + // this method when the user returns to the activity, which ensures the desired + // location provider is enabled each time the activity resumes from the stopped state. + LocationManager locationManager = + (LocationManager) getSystemService(Context.LOCATION_SERVICE); + final boolean gpsEnabled = locationManager.isProviderEnabled(LocationManager.GPS_PROVIDER); + + if (!gpsEnabled) { + // Build an alert dialog here that requests that the user enable + // the location services, then when the user clicks the "OK" button, + // call enableLocationSettings() + } +} + +private void enableLocationSettings() { + Intent settingsIntent = new Intent(Settings.ACTION_LOCATION_SOURCE_SETTINGS); + startActivity(settingsIntent); +} +</pre> |