Sample app for Android Training lesson: Making your app location aware.
Change-Id: I205a9e3f98823fbd90c5b770de8fe6ce8a9e345b
diff --git a/samples/training/location-aware/AndroidManifest.xml b/samples/training/location-aware/AndroidManifest.xml
new file mode 100644
index 0000000..0f13b11
--- /dev/null
+++ b/samples/training/location-aware/AndroidManifest.xml
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ Copyright (C) 2012 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ package="com.example.android.location"
+ android:versionCode="1"
+ android:versionName="1.0" >
+ <uses-sdk android:minSdkVersion="7"
+ android:targetSdkVersion="15" />
+
+ <!-- Fine access to location requires this permission.
+ This permission implies access coarse location. -->
+ <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+ <uses-permission android:name="android.permission.INTERNET" />
+
+ <application android:label="@string/app_name" >
+ <activity android:name="com.example.android.location.LocationActivity"
+ android:label="@string/app_name" >
+ <intent-filter>
+ <action android:name="android.intent.action.MAIN" />
+ <category android:name="android.intent.category.LAUNCHER" />
+ </intent-filter>
+ </activity>
+ </application>
+</manifest>
diff --git a/samples/training/location-aware/res/drawable-hdpi/button_default.9.png b/samples/training/location-aware/res/drawable-hdpi/button_default.9.png
new file mode 100644
index 0000000..f19682e
--- /dev/null
+++ b/samples/training/location-aware/res/drawable-hdpi/button_default.9.png
Binary files differ
diff --git a/samples/training/location-aware/res/drawable-hdpi/button_on.9.png b/samples/training/location-aware/res/drawable-hdpi/button_on.9.png
new file mode 100644
index 0000000..0efa25c
--- /dev/null
+++ b/samples/training/location-aware/res/drawable-hdpi/button_on.9.png
Binary files differ
diff --git a/samples/training/location-aware/res/drawable-hdpi/button_pressed.9.png b/samples/training/location-aware/res/drawable-hdpi/button_pressed.9.png
new file mode 100644
index 0000000..7ce743c
--- /dev/null
+++ b/samples/training/location-aware/res/drawable-hdpi/button_pressed.9.png
Binary files differ
diff --git a/samples/training/location-aware/res/drawable-mdpi/button_default.9.png b/samples/training/location-aware/res/drawable-mdpi/button_default.9.png
new file mode 100644
index 0000000..c255f3b
--- /dev/null
+++ b/samples/training/location-aware/res/drawable-mdpi/button_default.9.png
Binary files differ
diff --git a/samples/training/location-aware/res/drawable-mdpi/button_on.9.png b/samples/training/location-aware/res/drawable-mdpi/button_on.9.png
new file mode 100644
index 0000000..edc31c6
--- /dev/null
+++ b/samples/training/location-aware/res/drawable-mdpi/button_on.9.png
Binary files differ
diff --git a/samples/training/location-aware/res/drawable-mdpi/button_pressed.9.png b/samples/training/location-aware/res/drawable-mdpi/button_pressed.9.png
new file mode 100644
index 0000000..7e818ee
--- /dev/null
+++ b/samples/training/location-aware/res/drawable-mdpi/button_pressed.9.png
Binary files differ
diff --git a/samples/training/location-aware/res/drawable-xhdpi/button_default.9.png b/samples/training/location-aware/res/drawable-xhdpi/button_default.9.png
new file mode 100644
index 0000000..800dd00
--- /dev/null
+++ b/samples/training/location-aware/res/drawable-xhdpi/button_default.9.png
Binary files differ
diff --git a/samples/training/location-aware/res/drawable-xhdpi/button_on.9.png b/samples/training/location-aware/res/drawable-xhdpi/button_on.9.png
new file mode 100644
index 0000000..cec21b4
--- /dev/null
+++ b/samples/training/location-aware/res/drawable-xhdpi/button_on.9.png
Binary files differ
diff --git a/samples/training/location-aware/res/drawable-xhdpi/button_pressed.9.png b/samples/training/location-aware/res/drawable-xhdpi/button_pressed.9.png
new file mode 100644
index 0000000..15375d5
--- /dev/null
+++ b/samples/training/location-aware/res/drawable-xhdpi/button_pressed.9.png
Binary files differ
diff --git a/samples/training/location-aware/res/drawable/button_active.xml b/samples/training/location-aware/res/drawable/button_active.xml
new file mode 100644
index 0000000..be091fe
--- /dev/null
+++ b/samples/training/location-aware/res/drawable/button_active.xml
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ Copyright (C) 2012 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
+ <item android:state_pressed="true"
+ android:drawable="@drawable/button_pressed" />
+ <item android:drawable="@drawable/button_on" />
+</selector>
diff --git a/samples/training/location-aware/res/drawable/button_inactive.xml b/samples/training/location-aware/res/drawable/button_inactive.xml
new file mode 100644
index 0000000..4999a21
--- /dev/null
+++ b/samples/training/location-aware/res/drawable/button_inactive.xml
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ Copyright (C) 2012 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
+ <item android:state_pressed="true"
+ android:drawable="@drawable/button_pressed" />
+ <item android:drawable="@drawable/button_default" />
+</selector>
diff --git a/samples/training/location-aware/res/layout/main.xml b/samples/training/location-aware/res/layout/main.xml
new file mode 100644
index 0000000..658d258
--- /dev/null
+++ b/samples/training/location-aware/res/layout/main.xml
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ Copyright (C) 2012 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+ android:layout_width="match_parent"
+ android:layout_height="match_parent"
+ android:orientation="vertical" >
+ <LinearLayout android:layout_width="match_parent"
+ android:layout_height="wrap_content"
+ android:orientation="horizontal" >
+ <Button android:id="@+id/provider_fine"
+ android:layout_width="wrap_content"
+ android:layout_height="wrap_content"
+ android:text="@string/use_fine_provider"
+ android:background="@drawable/button_inactive"
+ android:minWidth="160sp"
+ android:onClick="useFineProvider" />
+
+ <Button android:id="@+id/provider_both"
+ android:layout_width="wrap_content"
+ android:layout_height="wrap_content"
+ android:text="@string/use_both_providers"
+ android:background="@drawable/button_inactive"
+ android:minWidth="160sp"
+ android:onClick="useCoarseFineProviders" />
+ </LinearLayout>
+ <TextView android:id="@+id/label_latlng"
+ android:layout_width="match_parent"
+ android:layout_height="wrap_content"
+ android:textSize="22sp"
+ android:text="@string/latlng" />
+ <TextView android:id="@+id/latlng"
+ android:layout_width="match_parent"
+ android:layout_height="wrap_content"
+ android:textSize="20sp" />
+ <TextView android:id="@+id/label_address"
+ android:layout_width="match_parent"
+ android:layout_height="wrap_content"
+ android:textSize="22sp"
+ android:text="@string/address" />
+ <TextView android:id="@+id/address"
+ android:layout_width="match_parent"
+ android:layout_height="wrap_content"
+ android:textSize="20sp" />
+</LinearLayout>
diff --git a/samples/training/location-aware/res/values/strings.xml b/samples/training/location-aware/res/values/strings.xml
new file mode 100644
index 0000000..4d6a87f
--- /dev/null
+++ b/samples/training/location-aware/res/values/strings.xml
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ Copyright (C) 2012 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<resources>
+ <string name="app_name">Android Training: Location Update</string>
+ <string name="address">Address:</string>
+ <string name="latlng">Lat/Long:</string>
+ <string name="unknown">--Unknown--</string>
+ <string name="not_support_gps">GPS provider not supported</string>
+ <string name="not_support_network">Network provider not supported</string>
+ <string name="use_fine_provider">Use fine provider</string>
+ <string name="use_both_providers">Use both providers</string>
+</resources>
diff --git a/samples/training/location-aware/src/com/example/android/location/LocationActivity.java b/samples/training/location-aware/src/com/example/android/location/LocationActivity.java
new file mode 100644
index 0000000..93f4ce1
--- /dev/null
+++ b/samples/training/location-aware/src/com/example/android/location/LocationActivity.java
@@ -0,0 +1,341 @@
+/*
+ * Copyright (C) 2012 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.android.location;
+
+import android.annotation.SuppressLint;
+import android.app.Activity;
+import android.content.Context;
+import android.location.Address;
+import android.location.Geocoder;
+import android.location.Location;
+import android.location.LocationListener;
+import android.location.LocationManager;
+import android.os.AsyncTask;
+import android.os.Build;
+import android.os.Bundle;
+import android.os.Handler;
+import android.os.Message;
+import android.view.View;
+import android.widget.Button;
+import android.widget.TextView;
+import android.widget.Toast;
+
+import java.io.IOException;
+import java.util.List;
+import java.util.Locale;
+
+public class LocationActivity extends Activity {
+ private TextView mLatLng;
+ private TextView mAddress;
+ private Button mFineProviderButton;
+ private Button mBothProviderButton;
+ private LocationManager mLocationManager;
+ private Handler mHandler;
+ private boolean mGeocoderAvailable;
+ private boolean mUseFine;
+ private boolean mUseBoth;
+
+ // Keys for maintaining UI states after rotation.
+ private static final String KEY_FINE = "use_fine";
+ private static final String KEY_BOTH = "use_both";
+ // UI handler codes.
+ private static final int UPDATE_ADDRESS = 1;
+ private static final int UPDATE_LATLNG = 2;
+
+ private static final int TEN_SECONDS = 10000;
+ private static final int TEN_METERS = 10;
+ private static final int TWO_MINUTES = 1000 * 60 * 2;
+
+ /**
+ * This sample demonstrates how to incorporate location based services in your app and
+ * process location updates. The app also shows how to convert lat/long coordinates to
+ * human-readable addresses.
+ */
+ @SuppressLint("NewApi")
+ @Override
+ public void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+ setContentView(R.layout.main);
+
+ // Restore apps state (if exists) after rotation.
+ if (savedInstanceState != null) {
+ mUseFine = savedInstanceState.getBoolean(KEY_FINE);
+ mUseBoth = savedInstanceState.getBoolean(KEY_BOTH);
+ } else {
+ mUseFine = false;
+ mUseBoth = false;
+ }
+ mLatLng = (TextView) findViewById(R.id.latlng);
+ mAddress = (TextView) findViewById(R.id.address);
+ // Receive location updates from the fine location provider (gps) only.
+ mFineProviderButton = (Button) findViewById(R.id.provider_fine);
+ // Receive location updates from both the fine (gps) and coarse (network) location
+ // providers.
+ mBothProviderButton = (Button) findViewById(R.id.provider_both);
+
+ // The isPresent() helper method is only available on Gingerbread or above.
+ mGeocoderAvailable =
+ Build.VERSION.SDK_INT >= Build.VERSION_CODES.GINGERBREAD && Geocoder.isPresent();
+
+ // Handler for updating text fields on the UI like the lat/long and address.
+ mHandler = new Handler() {
+ public void handleMessage(Message msg) {
+ switch (msg.what) {
+ case UPDATE_ADDRESS:
+ mAddress.setText((String) msg.obj);
+ break;
+ case UPDATE_LATLNG:
+ mLatLng.setText((String) msg.obj);
+ break;
+ }
+ }
+ };
+ // Get a reference to the LocationManager object.
+ mLocationManager = (LocationManager) getSystemService(Context.LOCATION_SERVICE);
+ }
+
+ // Restores UI states after rotation.
+ @Override
+ protected void onSaveInstanceState(Bundle outState) {
+ super.onSaveInstanceState(outState);
+ outState.putBoolean(KEY_FINE, mUseFine);
+ outState.putBoolean(KEY_BOTH, mUseBoth);
+ }
+
+ @Override
+ protected void onResume() {
+ super.onResume();
+ setup();
+ }
+
+ // Stop receiving location updates whenever the Activity becomes invisible.
+ @Override
+ protected void onStop() {
+ super.onStop();
+ mLocationManager.removeUpdates(listener);
+ }
+
+ // Set up fine and/or coarse location providers depending on whether the fine provider or
+ // both providers button is pressed.
+ private void setup() {
+ Location gpsLocation = null;
+ Location networkLocation = null;
+ mLocationManager.removeUpdates(listener);
+ mLatLng.setText(R.string.unknown);
+ mAddress.setText(R.string.unknown);
+ // Get fine location updates only.
+ if (mUseFine) {
+ mFineProviderButton.setBackgroundResource(R.drawable.button_active);
+ mBothProviderButton.setBackgroundResource(R.drawable.button_inactive);
+ // Request updates from just the fine (gps) provider.
+ gpsLocation = requestUpdatesFromProvider(
+ LocationManager.GPS_PROVIDER, R.string.not_support_gps);
+ // Update the UI immediately if a location is obtained.
+ if (gpsLocation != null) updateUILocation(gpsLocation);
+ } else if (mUseBoth) {
+ // Get coarse and fine location updates.
+ mFineProviderButton.setBackgroundResource(R.drawable.button_inactive);
+ mBothProviderButton.setBackgroundResource(R.drawable.button_active);
+ // Request updates from both fine (gps) and coarse (network) providers.
+ gpsLocation = requestUpdatesFromProvider(
+ LocationManager.GPS_PROVIDER, R.string.not_support_gps);
+ networkLocation = requestUpdatesFromProvider(
+ LocationManager.NETWORK_PROVIDER, R.string.not_support_network);
+
+ // If both providers return last known locations, compare the two and use the better
+ // one to update the UI. If only one provider returns a location, use it.
+ if (gpsLocation != null && networkLocation != null) {
+ updateUILocation(getBetterLocation(gpsLocation, networkLocation));
+ } else if (gpsLocation != null) {
+ updateUILocation(gpsLocation);
+ } else if (networkLocation != null) {
+ updateUILocation(networkLocation);
+ }
+ }
+ }
+
+ /**
+ * Method to register location updates with a desired location provider. If the requested
+ * provider is not available on the device, the app displays a Toast with a message referenced
+ * by a resource id.
+ *
+ * @param provider Name of the requested provider.
+ * @param errorResId Resource id for the string message to be displayed if the provider does
+ * not exist on the device.
+ * @return A previously returned {@link android.location.Location} from the requested provider,
+ * if exists.
+ */
+ private Location requestUpdatesFromProvider(final String provider, final int errorResId) {
+ Location location = null;
+ if (mLocationManager.isProviderEnabled(provider)) {
+ mLocationManager.requestLocationUpdates(provider, TEN_SECONDS, TEN_METERS, listener);
+ location = mLocationManager.getLastKnownLocation(provider);
+ } else {
+ Toast.makeText(this, errorResId, Toast.LENGTH_LONG).show();
+ }
+ return location;
+ }
+
+ // Callback method for the "fine provider" button.
+ public void useFineProvider(View v) {
+ mUseFine = true;
+ mUseBoth = false;
+ setup();
+ }
+
+ // Callback method for the "both providers" button.
+ public void useCoarseFineProviders(View v) {
+ mUseFine = false;
+ mUseBoth = true;
+ setup();
+ }
+
+ private void doReverseGeocoding(Location location) {
+ // Since the geocoding API is synchronous and may take a while. You don't want to lock
+ // up the UI thread. Invoking reverse geocoding in an AsyncTask.
+ (new ReverseGeocodingTask(this)).execute(new Location[] {location});
+ }
+
+ private void updateUILocation(Location location) {
+ // We're sending the update to a handler which then updates the UI with the new
+ // location.
+ Message.obtain(mHandler,
+ UPDATE_LATLNG,
+ location.getLatitude() + ", " + location.getLongitude()).sendToTarget();
+
+ // Bypass reverse-geocoding only if the Geocoder service is available on the device.
+ if (mGeocoderAvailable) doReverseGeocoding(location);
+ }
+
+ private final LocationListener listener = new LocationListener() {
+
+ @Override
+ public void onLocationChanged(Location location) {
+ // A new location update is received. Do something useful with it. Update the UI with
+ // the location update.
+ updateUILocation(location);
+ }
+
+ @Override
+ public void onProviderDisabled(String provider) {
+ }
+
+ @Override
+ public void onProviderEnabled(String provider) {
+ }
+
+ @Override
+ public void onStatusChanged(String provider, int status, Bundle extras) {
+ }
+ };
+
+ /** Determines whether one Location reading is better than the current Location fix.
+ * Code taken from
+ * http://developer.android.com/guide/topics/location/obtaining-user-location.html
+ *
+ * @param newLocation The new Location that you want to evaluate
+ * @param currentBestLocation The current Location fix, to which you want to compare the new
+ * one
+ * @return The better Location object based on recency and accuracy.
+ */
+ protected Location getBetterLocation(Location newLocation, Location currentBestLocation) {
+ if (currentBestLocation == null) {
+ // A new location is always better than no location
+ return newLocation;
+ }
+
+ // Check whether the new location fix is newer or older
+ long timeDelta = newLocation.getTime() - currentBestLocation.getTime();
+ boolean isSignificantlyNewer = timeDelta > TWO_MINUTES;
+ boolean isSignificantlyOlder = timeDelta < -TWO_MINUTES;
+ boolean isNewer = timeDelta > 0;
+
+ // If it's been more than two minutes since the current location, use the new location
+ // because the user has likely moved.
+ if (isSignificantlyNewer) {
+ return newLocation;
+ // If the new location is more than two minutes older, it must be worse
+ } else if (isSignificantlyOlder) {
+ return currentBestLocation;
+ }
+
+ // Check whether the new location fix is more or less accurate
+ int accuracyDelta = (int) (newLocation.getAccuracy() - currentBestLocation.getAccuracy());
+ boolean isLessAccurate = accuracyDelta > 0;
+ boolean isMoreAccurate = accuracyDelta < 0;
+ boolean isSignificantlyLessAccurate = accuracyDelta > 200;
+
+ // Check if the old and new location are from the same provider
+ boolean isFromSameProvider = isSameProvider(newLocation.getProvider(),
+ currentBestLocation.getProvider());
+
+ // Determine location quality using a combination of timeliness and accuracy
+ if (isMoreAccurate) {
+ return newLocation;
+ } else if (isNewer && !isLessAccurate) {
+ return newLocation;
+ } else if (isNewer && !isSignificantlyLessAccurate && isFromSameProvider) {
+ return newLocation;
+ }
+ return currentBestLocation;
+ }
+
+ /** Checks whether two providers are the same */
+ private boolean isSameProvider(String provider1, String provider2) {
+ if (provider1 == null) {
+ return provider2 == null;
+ }
+ return provider1.equals(provider2);
+ }
+
+ // AsyncTask encapsulating the reverse-geocoding API. Since the geocoder API is blocked,
+ // we do not want to invoke it from the UI thread.
+ private class ReverseGeocodingTask extends AsyncTask<Location, Void, Void> {
+ Context mContext;
+
+ public ReverseGeocodingTask(Context context) {
+ super();
+ mContext = context;
+ }
+
+ @Override
+ protected Void doInBackground(Location... params) {
+ Geocoder geocoder = new Geocoder(mContext, Locale.getDefault());
+
+ Location loc = params[0];
+ List<Address> addresses = null;
+ try {
+ addresses = geocoder.getFromLocation(loc.getLatitude(), loc.getLongitude(), 1);
+ } catch (IOException e) {
+ e.printStackTrace();
+ // Update address field with the exception.
+ Message.obtain(mHandler, UPDATE_ADDRESS, e.toString()).sendToTarget();
+ }
+ if (addresses != null && addresses.size() > 0) {
+ Address address = addresses.get(0);
+ // Format the first line of address (if available), city, and country name.
+ String addressText = String.format("%s, %s, %s",
+ address.getMaxAddressLineIndex() > 0 ? address.getAddressLine(0) : "",
+ address.getLocality(),
+ address.getCountryName());
+ // Update address field on UI.
+ Message.obtain(mHandler, UPDATE_ADDRESS, addressText).sendToTarget();
+ }
+ return null;
+ }
+ }
+}
