Beginning Android

/>
 <application android:label='@string/app_name'>
  <uses-library android:name='com.google.android.maps' />
  <activity android:name='.NooYawk' 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>

That is pretty much all you need for starters, plus to subclass your activity from MapActivity. If you were to do nothing else, and built that project and tossed it in the emulator, you’d get a nice map of the world. Note, however, that MapActivity is abstract — you need to implement isRouteDisplayed() to indicate if you are supplying some sort of driving directions or not.

In theory, the user could pan around the map using the directional pad. However, that’s not terribly useful when the user has the whole world in her hands.

Since a map of the world is not much good by itself, we need to add a few things…

Exercising Your Control

You can find your MapView widget by findViewById(), no different than any other widget. The widget itself then offers a getMapController() method. Between the MapView and MapController, you have a fair bit of capability to determine what the map shows and how it behaves. The following sections cover zoom and center, the features you will most likely want to use.

Zoom

The map of the world you start with is rather broad. Usually, people looking at a map on a phone will be expecting something a bit narrower in scope, such as a few city blocks.

You can control the zoom level directly via the setZoom() method on the MapController. This takes an integer representing the level of zoom, where 1 is the world view and 21 is the tightest zoom you can get. Each level is a doubling of the effective resolution: 1 has the equator measuring 256 pixels wide, while 21 has the equator measuring 268,435,456 pixels wide. Since the phone’s display probably doesn’t have 268,435,456 pixels in either dimension, the user sees a small map focused on one tiny corner of the globe. A level of 16 will show you several city blocks in each dimension and is probably a reasonable starting point for you to experiment with.

If you wish to allow users to change the zoom level, you will need to do a few things:

• First, pick a spot on the screen where you want the zoom controls to appear. These are not huge, and they only appear when being used, so they can overlay the actual map itself if you choose. In the layout previously shown, for example, the zoom controls are placed over the map, in the lower-left corner of the screen. You should use a LinearLayout or other simple container for the zoom controls’ position in your layout.

• In your activity’s onCreate() method, get your zoom controls’ container via findViewById().

• Add the result o f map.getZoomControls() to that container.

For example, here are the lines from the NooYawk activity’s onCreate() method that accomplish the latter points:

ViewGroup zoom = (ViewGroup)findViewById(R.id.zoom);
zoom.addView(map.getZoomControls());

Then, you can manually get the zoom controls to appear by calling displayZoomControls() on your MapView, or they will automatically appear when the user pans the map as seen in Figure 34-1.

Figure 34-1. Map with zoom indicator and compass rose

Center

Typically, you will need to control what the map is showing, beyond the zoom level, such as the user’s current location, or a location saved with some data in your activity. To change the map’s position, call setCenter() on the MapController.

This takes a GeoPoint as a parameter. A GeoPoint represents a location, via latitude and longitude. The catch is that the GeoPoint stores latitude and longitude as integers representing the actual latitude and longitude multiplied by 1E6. This saves a bit of memory versus storing a float or double, and it probably speeds up some internal calculations Android needs to do to convert the GeoPoint into a map position. However, it does mean you have to remember to multiply the “real world” latitude and longitude by 1E6.

Rugged Terrain

Just as the Google Maps you use on your full-size computer can display satellite imagery, so too can Android maps.

MapView offers toggleSatellite(), which, as the names suggest, toggles on and off the satellite perspective on the area being viewed. You can have the user trigger these via an options menu or, in the case of NooYawk, via keypresses:

@Override
public boolean onKeyDown(int keyCode, KeyEvent event) {
 if (keyCode == KeyEvent.KEYCODE_S) {
  map.setSatellite(!map.isSatellite());
  return(true);
 } else if (keyCode == KeyEvent.KEYCODE_Z) {
  map.displayZoomControls(true);
  return(true);
 }
 return(super.onKeyDown(keyCode,