AndroidExample < CS422

CS422 Web>AndroidCoding>AndroidExample (2010-03-24, Main.cpable2) (raw view)EditAttach
---+ Android Example

This example will guide you through using a basic Android framework, how activities interact with each other and demonstrating map capabilities.

To begin, please watch this video on how android manages applications people develop:

http://www.youtube.com/watch?v=fL6gSd4ugSI

Next lets download the test application that was thrown together for you!

Sample Application: [[%ATTACHURL%/testapp.zip][testapp.zip]]

Extract this zip archive somewhere you will remember.

Lets load up eclipse and import the project. Click on the File menu and select new project. We want an android project with the name test. We want to create the project from existing source. Browse to the location that you extracted the zip file to. We want to use the Google APIs for platform 2.1 (Though it will work on other versions of the platform too.)

The application's name should be test and the min sdk version should be 2. <br />Once you fill out that information, click on finish.

Note in order to run the example, you must create an AVD in the AVD manager that utilizes the google APIs, preferably in android 2.1.

Once the program is imported, we need to fix it's permissions since zip files do not preserve them. Right click on the test folder, select Android Tools from the drop down menu and select to fix project properties (This may not be nessecary if you are developing this on windows).

Now that the program is open, lets try running it. Remember, you must have already created an AVD with google APIs. You can do this in the AVD manager (Just click the button that looks like a cell phone in Eclipse).

You will be presented with a screen with 3 UIC buildings and the option to enter your own Longitude and Latitude pair. Select a building and a pop up of the option you selected (called a Toast) will echo your selection. Map view will then load and the building will be marked by an android. Pressing the back button will return you to the selection screen. If you enter your own co-ordinate pair, it must be in 1e6, 1e6 format. You will be taken to a screen where you can enter this information as well with a button entitled "Map it!".

---++ Examining the code

So how do we code something like this? Well, as you saw from the video, each screen is generally noted as an activity. Every time you prepare to switch screens, its called creating an intent. This intent lets you pass information in a bundle to be passed on to the next screen while the current screens state is saved on the activity stack.
---+++ !AndroidManifest.xml
 This file is important because it tells Android which files and classes are in the project. We must mark each activity in this file as well as mark which permissions we would like to have, such as internet access (so we can download the map tiles in map view). This is the file in which you can set the application name and version number as well.

---+++ Test.java
 Test.java is the first file executed in project, so lets look at it. First thing that catches our eye is the list of locations in a String array followed by their longitude and latitude co-ordinates. We also note that the test class extends the list activity instead of a regular activity. This is important since the list activity has an view we want to link into that allows us to track item selections.

We set the !ListAdapter (The thing that lets us use list view) to use the xml layout of list_item.xml. We can find this file under test\res\layout in the file tree and is available freely from the android dev resources. We then create a list view object and set it to being a regular old list view. After that we turn on the text filter, and create an item selection listener and it creates an anonymous inner class we can flush out.

In here, the only thing we really care about is the id. List index's start from 0 to the total size of locations. There are 3 things happening here, first, we create the toast pop-up.

Next we begin making an alert dialog. This dialog is never shown because these dialogs do not behave how one would expect on android. When you create a dialog, and display it, it is exclusive to the activity that starts it, so when we start the map activity, for example, the alert dialog is hidden behind the map activity. For this reason, we commented out the actual displaying of the alert dialog, but left it for you to see how to create a context free alert dialog.

Finally, we have an if statement that checks which ID was selected. If a building was selected, we pull its co-ordinates from the co-ordinates array and place them in a bundle. This bundle lets us place objects inside of an intent we create so that we can send information to the next screen. We create an intent and note that it is called map.class. When map.java is compiled, it becomes map.class, so remember this small detail. We then attach our bundle to the intent, and start the activity. Activities can return results, like sub programs, however, that is beyond the scope of this sample application.

---+++ Map.java
 Map.java is our next focus now, however, in order to use it, we need to create a small, almost useless helper class that lets us manage points called *itemizedOverlay.java*. We will not get into how it works as the code is trivial but it allows us to store multiple map points so we can display multiple points at once if we so choose.

Now that we have seen our helper class, lets look at the primary class. Notice how it extends !MapActivity instead of !ListActivity. As class variables to the activity, we create zoom controls and the variables needed to keep track of the overlays. isRouteDisplayed() is a stub from implementing !MapActivity. It lets android know if you are displaying a route. In this case, we never will be.

Finally, we have the guts of map view. The first thing we do is create a bundle and extract the data we sent this activity inside of savedInstanceState and set the view to main.xml. We will take a look at main.xml after we finish the description of this class.

The next thing we do is attach the zoom controls (we defined these in the xml file and as class variables) and then attach our map overlays (the markers for the buildings) to the map as well. Note that our marker is an android icon, we saved it in test\res\drawable in the file tree. After that, its fairly simple to take the co-ordinates we passed to the activity and place them in the overlay list. After we do that, we tell the map to update our display of overlays. It's pretty simple and straight forward :).

---+++ main.xml
 main.xml is a major player to the map view. While generally, it is available on the android resources, theres 2 very important things to note. First of all, we added zoom controls, as you can see by the last segment in the file called linear layout. However, the critical thing is to notice in the middle segment of the file is android:apikey. You see this is my Google Maps API key. It does you no good. Why is that? This API key is generated from your installation of the SDK. To generate your own API key, you need to follow google's instructions here:<br /><a href="http://code.google.com/android/maps-api-signup.html " title="Get a Google Maps API Key!">http://code.google.com/android/maps-api-signup.html </a>

*NOTE:* When asked for a "keystore password", enter the default password of *android*.

---+++ input.java
 Out next stop is input.java. This file allows the user to enter a co-ordinate pair in 1e6, 1e6 style to be passed on to the map activity. Here our class extends regular old activity. However, we set the layout to *textinput.xml*. The textbox is called an editText widget, and the the button is called a Button. After you take a good look at this schema, head back to the input.java file.

The first thing we do is add a click listener to the button. When its clicked, it instantiates an anonymous inner class that gets the text from the text box then parses it to make sure it is properly formatted. I allowed the user to be quite liberal in how they delimited the co-ordinates so the code is a little large. The user can separate values by a space, a comma, or a comma and a space. If I detect the user did not enter valid values for the co-ordinates correctly, I alert them with a toast pop up and the user can alter their input and try again, or use the back button to return to the previous activity. Once the values are entered correctly, I create a bundle just as before. I package the 2 values given to me by the user and send them to the map activity to be processed by creating an intent, attaching my bundle to it and then starting my intent.

Note that if I press back while I am in map view if I came from the co-ordinate entry screen, I return to the co-ordinate entry screen, not the building list as I did before since that was the previous activity I was in. I can press back again to return to the building selection screen.

---++ The End?

That's the test program in a nutshell! Its pretty easy to follow, and the xml templates can be generated using the built in GUI generator if you so choose or you can type it out yourself. Good luck in making Android Applications!