Hello, MapView

A MapView allows you to create your own map-viewing Activity. First, we'll create a simple Activity that can view and navigate a map. Then we will add some overlay items.

1. Start a new project/Activity called HelloMapView.
2. Because we're using the Google Maps library, which is not a part of the standard Android library, we need to declare it in the Android Manifest. Open the AndroidManifest.xml file and add the following as a child of the <application> element:

   <uses-library android:name="com.google.android.maps" />

3. We also need access to the internet in order to retrieve the Google Maps tiles, so the application must request the INTERNET permissions. In the manifest file, add the following as a child of the <manifest> element:

   <uses-permission android:name="android.permission.INTERNET" />

4. Now open the main layout file for your project. Define a layout with a com.google.android.maps.MapView inside a android.widget.RelativeLayout:

   <?xml version="1.0" encoding="utf-8"?>
   <RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
       android:id="@+id/mainlayout"
       android:orientation="vertical"
       android:layout_width="fill_parent"
       android:layout_height="fill_parent" >
   
       <com.google.android.maps.MapView
           android:id="@+id/mapview"
           android:layout_width="fill_parent"
           android:layout_height="fill_parent"
           android:clickable="true"
           android:apiKey="Your Maps API Key"
       />
   
   </RelativeLayout>
   

   The clickable attribute defines whether you want to allow user-interaction with the map. In this case, we set it "true" so that the user can navigate.

   The apiKey attribute holds the Google Maps API Key that proves your application and signer certificate has been registered with the Google Maps service. Because MapView uses Google Maps data, this key is required in order to receive the map data, even while you are developing. Registration is free and it only takes a couple minutes to register your certificate and receive a Maps API Key. For instructions on getting a key, read Obtaining a Maps API Key. (For the purpose of this tutorial, you should register with the fingerprint of the SDK debug certificate.) Once you've acquired the Maps API Key, insert it for the apiKey value.

5. Now open the HelloMapView.java file. For this Activity, we're going to extend the special sub-class of Activity called MapActivity, so change the class declaration to extend MapActicity, instead of Activity:

   public class HelloMapView extends MapActivity {

6. The isRouteDisplayed() method is required, so add it inside the class:

   @Override
   protected boolean isRouteDisplayed() {
       return false;
   }
   

   You can actually run this now, but all it does is allow you to pan around the map.

   Android provides a handy ZoomControls widget for zooming in and out of a View. MapView can automatically hook one for us by requesting it with the getZoomControls() method. Let's do this.

7. Go back to the layout file. We need a new ViewGroup element, in which we'll place the ZoomControls. Just below the MapView element (but inside the RelativeLayout), add this element:

   <LinearLayout
       android:id="@+id/zoomview"
       android:layout_width="wrap_content"
       android:layout_height="wrap_content"
       android:layout_alignBottom="@id/mapview"
       android:layout_centerHorizontal="true"
   />

   It doesn't really matter what kind of ViewGroup we use, because we just want a container that we can position within our root RelativeLayout.

   The last two attributes are available only to an element that's a child of a RelativeLayout. layout_alignBottom aligns the bottom of this element to the bottom of the element identified with a resource tag (which must be a sibling to this element). layout_centerHorizontal centers this on the horizontal plane.

8. Now go back to the HelloMapView class. We'll now retrieve the ZoomControls object from the MapView and add it to our new layout element. First, at the top of the HelloMapView, instantiate handles for the MapView and LinearLayout, plus a ZoomControl object:

   LinearLayout linearLayout;
   MapView mapView;
   ZoomControls mZoom;

9. Then initialize each of these in onCreate(). We'll capture the LinearLayout and MapView through their layout resources. Then get the ZoomControls from the MapView::

   linearLayout = (LinearLayout) findViewById(R.id.zoomview);
   mapView = (MapView) findViewById(R.id.mapview);
   mZoom = (ZoomControls) mapView.getZoomControls();

   By using the ZoomControls object provided by MapView, we don't have to do any of the work required to actually perform the zoom operations. The ZoomControls widget that MapView returns for us is already hooked into the MapView and works as soon as we add it to the layout. The controls will appear whenever the user touches the map, then dissapear after a few moments of inactivity.

10. Now just plug our ZoomControls into the LinearLayout we added:

    linearLayout.addView(mZoom);

11. Run it.

So, we now have full interaction controls. All well and good, but what we really want our map for is custom markers and layovers. Let's add some Overlay objects to our map. To do this, we're going to implement the ItemizedOverlay class, which can manage a whole set of Overlay items for us.

1. Create a new Java class named HelloItemizedOverlay that implements ItemizedOverlay.

   When using Eclipse, right-click the package name in the Eclipse Package Explorer, and select New > Class. Fill-in the Name field as HelloItemizedOverlay. For the Superclass, enter com.google.android.maps.ItemizedOverlay. Click the checkbox for Constructors from superclass. Click Finish.

2. First thing, we need an OverlayItem ArrayList, in which we'll put each of the OverlayItem objects we want on our map. Add this at the top of the HelloItemizedOverlay class:

   private ArrayList<OverlayItem> mOverlays = new ArrayList<OverlayItem>();

3. All the constructor does is define the default marker to be used on each of the OverlayItems. In order for the Drawable to actually get drawn, it must have its bounds defined. And we want the center-point at the bottom of the image to be the point at which it's attached to the map coordinates. We handle all this with the boundCenterBottom() method. Wrap this around our defaultMarker, so the super constructor call looks like this:

   super(boundCenterBottom(defaultMarker));

4. In order to add new OverlayItems to our ArrayList, we need a new public method. We'll handle this with the following method:

   public void addOverlay(OverlayItem overlay) {
       mOverlays.add(overlay);
       populate();
   }

   Each time we add a new OverlayItem, we must call populate(), which will read each of out OverlayItems and prepare them to be drawn.

5. In order for the populate() method to read each OverlayItem, it will make a request to createItem(int). We must define this method to properly read from our ArrayList. Replace the existing contents of the createItem method with a get() call to our ArrayList:

   @Override
   protected OverlayItem createItem(int i) {
     return mOverlays.get(i);
   }
   

6. We're also required to override the size() method. Replace the existing contents of the method with a size request to our ArrayList:

   return mOverlays.size();

That's it for the HelloItemizedOverlay class. We're now ready to use it.

Go back to the HelloMapView class. We'll start by creating one OverlayItem, adding to an instance of our HelloItemizedOverlay, and then adding this to the MapView.

First, we need the image that we'll use for our map overlay. Here, we'll use the Android on the right as our marker. Drag this image (or your own) to the res/drawable/ directory of your project workspace.

Now we're ready to work in the HelloMapView:

1. First we need some more types. Add the following at the top of the HelloMapView class:

   List<Overlay> mapOverlays;
   Drawable drawable;
   HelloItemizedOverlay itemizedOverlay;

2. Now pick up where we left off in the onCreate() method. Instantiate the new fields:

   mapOverlays = mapView.getOverlays();
   drawable = this.getResources().getDrawable(R.drawable.androidmarker);
   itemizedoverlay = new HelloItemizedOverlay(drawable);

   All overlay elements on a map are held by the MapView, so when we want to add some, we must first retrieve the List with getOverlays() methods. We instantiate the Drawable, which will be used as our map marker, by using our Context resources to get the Drawable we placed in the res/drawable/ directory (androidmarker.png). Our HelloItemizedOverlay takes the Drawable in order to set the default marker.

3. Now let's make our first OverlayItem by creating a GeoPoint that defines our map coordinates, then pass it to a new OverlayItem:

   GeoPoint point = new GeoPoint(19240000,-99120000);
   OverlayItem overlayitem = new OverlayItem(point, "", "");

   GeoPoint coordinates are based in microdegrees (degrees * 1e6). The OverlayItem takes this GeoPoint and two strings. Here, we won't concern ourselves with the strings, which can display text when we click our marker, because we haven't yet written the click handler for the OverlayItem.

4. All that's left is for us to add this OverlayItem to our collection in the HelloItemizedOverlay, and add this to the List of Overlay objects retrieved from the MapView:

   itemizedoverlay.addOverlay(overlayitem);
   mapOverlays.add(itemizedoverlay);

5. Run it!

We've sent our droid to Mexico City. Hola, Mundo!

You should see the following:

Because we created our ItemizedOverlay class with an ArrayList, we can continue adding new OverlayItems. Try adding another one. Before the addOverlay() method is called, add these lines:

GeoPoint point2 = new GeoPoint(35410000, 139460000);
OverlayItem overlayitem2 = new OverlayItem(point2, "", "");

Run it again... We've sent a new droid to Tokyo. Sekai, konichiwa!