Programming with Android Part 3 – Building WikiWhere

We will continue from where we left off in the last instalment and extend our basic application into a more useful application. If you are keeping track, we're an hour and fifteen minutes into our development and we have our application environment setup and ready to program in Android.

Over the next hour we will create an application that will show the wiki entries near our location, display that information on a map and embed the wiki page into the application. This application highlights three key features of the Android platform;

1. Focus on LBS that makes locative media easier to produce.
2. Deep web integration from consuming web services to embedding web page.
3.  Simple map integration via Google Maps.

What is WikiWhere

WikiWhere is a buzzword-compliant mobile application that gives you access to local wiki knowledge where ever you are. Using your Android phone, WikiWhere searches wiki for entries near your location and passes that information to you. Discover your neighbourhood or visit others. 

1:20 Back from Break. You aren't paid to sit there you know.

We are now going to get started with the WikiWhere application. Let's go through the first step and create an application shell using the Eclipse project builder. Just as in the previous part, select File >> New Project >> Android Project to launch a new project. Add the details for WikiWhere. I've attached a screenshot of the details below.

Step 1. Create the MapView

The main user interface will be a MapView so we want to change the interface of our WikiWhere class from Activity to MapActivity and implement the onRouteDisplayed method.

Next we have to implement the map in the view. Android separates the device layout / views from the source code to simplify development. A graphic designer can modify the XML layout without impacting the underlying source code. I'm a strong believer in letting programmers do the programming and not the UI or graphic design. Windows 3.1 was designed by programmers. Case closed.

The layouts are located in the res/layout folder in the project. We will edit the main.xml file and replace it with the following code:

This layout file adds three components. At the top will be a button to search for wiki entries. The main view is a Google Maps view. And finally, the bottom component is a holder for the zoom in/out control on the map. You will have to apply for your own Google Maps key and you can do that from this site

Step 2. Permissions

The next step is to tell Android that we need access to the maps library and permission to access the internet from the device. All the configurations is located in the AndroidManifest.xml file. This file controls all the permissions and OS access for the application. It would be worth your while to become very familiar with that file. The Android/Eclipse toolkit provides a graphical interface to simplify the editing of the file. Personally, I prefer to use the raw xml (click on the far right tab when in the graphical interface) but really its up to you.

The first step is to add the library to the application. Add the <uses-library tag after the activity tag and before the application tag. Like this;

Next, we will add the permissions to the file:

This is all the changes that need to occur to get a MapView running on the device. If you setup a Run Configuration identical to Part 2 and run the application in the emulator you should see this;

That's it for adding a draggable map into your application. Click and drag the map around.

Step 3. Adding Extra Components

As a final step we will add a zoom button and center the map on a closer area. Add this code to your WikiWhere.java file;

This adds a zoom panel at the bottom, centers the map on a location (Kits Bar in Calgary, AB. home to MobileMonday Calgary every month) and adds a satellite overview to the map. Go ahead run the app again. Pretty cool, huh?

1:40 Accessing the On-Device Location

This next section deals with getting the devices current location from GPS. Android provides a simple interface through the LocationManager to get the location. An important differentiator of the LocationManager is that it listens to the location stream and therefore allows many applications to access the GPS on the device. Many other GPS implementations on mobile devices don't allow multiple applications to access the location. This is a major drawback to running background applications since the OS would dictate which applications receive the location and which ones are stopped. This architecture also means that the time for a location fix is drastically reduced in the device. I will be writing an article outlining the importance of this architecture in an upcoming article on the Android GPS accuracy.

Either way, back to WikiWhere. Androids permission scheme requires that the permissions for GPS and in fact all location types be entered into the AndroidManifest.xml first.

Add the following lines under the other <uses-permissions tag from the previous section:

As I mentionned above the GPS is pushed through a LocationListener. We will be implementing that interface in the WikiWhere class and extending the LocationListener methods in the code.

Initializing the LocationManager is done by calling requestLocationUpdates

The requestLocationUpdates allows you to tailor your listener so you only get updates when a user has moved a certain distance and/or a certain time has passed. In our example above we are getting locations every 5 seconds (5000 ms) or when the user moves more than 500m. Location objects will be pushed to the onLocationChangedMethod whenever updates are available.

For the next part we will create an Overlay to display the users position. Overlays are Androids way of handle icons on a map. There is a default overlay called MyLocationOverlay that is specifically designed to handle the users location updates from GPS. If you were so inclined feel free to write your own map Overlay for the users locations. (We will be doing that later for the Wiki Points).

That code will update the location and display it on the map. Save and run the application on the emulator.

The first thing you will notice is that there is no flashing blue icon on the map. That is because no location has been sent to the emulator. The Android SDK provides a toolkit to help you out here. Select Window>>Open Perspective>>DDMS (You may have to click other and browse for it, if it isn't there). This perspective gives you a large collection of tools to help optimize, debug and monitor applications on the emulator (and devices!). Under the Emulator Control tab scroll down until you see the Location Controls.

 This  control allows you to push one location or a series of locations in GPX or KML format. A fantastic tool for testing applications. Enter the latitude and longitude into the box and click send. This will simulate a GPS location coming into the device and you should immediately see the flashing blue icon in your emulator.

Locations are automatically updated everytime you move. Try playing around with the DDMS Location Control and see how it moves your position around dynamically.

 That is it for the first part of WikiWhere. In the next part we will learn how to call web services, simple parsing of XML and of course the WebView. See you then!

 Final Part