To start with, it would be very useful to be able to see any map in landscape mode.

Go back to your Project window in Xcode and add the following method to MapController.m:

- (BOOL)shouldAutorotateToInterfaceOrientation:
          (UIInterfaceOrientation)toInterfaceOrientation {

  return YES;
}

That's all you have to do to view the map in landscape mode. You can move back and forth between landscape and portrait mode and MapKit.framework takes care of it for you! (This is starting to be real fun.)

What about showing your location on the map? That's just as easy!

In the MapController.m file, uncomment out viewDidLoad and add the code in bold.

- (void)viewDidLoad {
  [super viewDidLoad];

  mapView.showsUserLocation = YES;
}

showsUserLocation is a MKMapView property that tells the Map view whether to show the user location. If YES, you get that same blue pulsing dot displayed in the built-in Map application.

If you were to compile and run the application as it stands, you'd get what you see in Figure 5-5 — a map of the USA in landscape mode with a blue dot that represents the phone's current location. (There may be a lag until the iPhone is able to determine that location, but you should see it eventually.) Of course, to see it in landscape mode, you have to turn the iPhone, or choose Hardware

Figure 5-5. Displaying a map in landscape mode with a user location.

Okay, now you've got a blue dot on a map of the good ol' US of A. Cute, but still not that useful for the purposes of the app.

As I mention at the beginning of this chapter, ideally, when you get to San Francisco (or wherever), you should see a map that centers on San Francisco as opposed to the United States. To get there from here, however, is also pretty easy.

First you need to look at how you center the map.

Back in your Project window, add the following code to MapController.m:

- (void)updateRegionLatitude:(float) latitude
         longitude:(float) longitude
         latitudeDelta:(float) latitudeDelta
   longitudeDelta:(float) longitudeDelta {

  MKCoordinateRegion region;
  region.center.latitude = latitude;
  region.center.longitude = longitude;
  region.span.latitudeDelta = latitudeDelta;
  region.span.longitudeDelta = longitudeDelta;
  [mapView setRegion:region animated:NO];
}

Also add the declaration to the MapController.h file.

Setting the region is how you center the map and set the zoom level. You accomplish all this with the following statement:

[mapView setRegion:region animated:NO];

A region is a Map View property that specifies four things (as illustrated in Figure 5-6).

Although the span values provide an implicit zoom value for the map, the actual region you see displayed may not equal the span you specify because the map will go to the zoom level that best fits the region that is set. This also means that even if you just change the center coordinate in the map, the zoom level may change because distances represented by a particular span may change at different latitudes and longitudes. To account for that, those smart developers at Apple included a property you can set that will change the center coordinate without changing the zoom level.

@property (nonatomic) CLLocationCoordinate2D centerCoordinate

When you change the value of this property with a new CLLocationCoordinate2D, the map is centered on the new coordinate, and updates span values to maintain the current zoom level.

That CLLocationCoordinate2D type is something you'll be using a lot, so I'd like to explain that before I take you any further.

CLLocationCoordinate2D type is a structure that contains a geographical coordinate using the WGS 84 reference frame (the reference coordinate system used by the Global Positioning System).

typedef struct {
CLLocationDegrees latitude;
CLLocationDegrees longitude;
} CLLocationCoordinate2D;

Here's a little explanation:

To center the map display on San Francisco, you send the updateRegionLatitude:longitude: latitudeDelta:longitudeDelta message (the code you just entered) when the view is loaded in the viewDidLoad: method. You already added some code there to display the current location, so add the code in bold to MapController.m.

- (void)viewDidLoad {

  [super viewDidLoad];
  mapView.showsUserLocation = YES;
  CLLocationCoordinate2D initialCoordinate =
                                 [trip initialCoordinate];
  [self updateRegionLatitude:
                  initialCoordinate.latitude

longitude:initialCoordinate.longitude
                  latitudeDelta:.06 longitudeDelta:.06];
  self.title = [trip mapTitle];
}

Figure 5-6. How regions work.

Take a look at what adding the bold stuff does:

For all of this to work, of course, you have to add the following code to Trip.m. This code returns the latitude and longitude for San Francisco.

- (CLLocationCoordinate2D)initialCoordinate {

  CLLocationCoordinate2D startCoordinate;
  startCoordinate.latitude = 37.774929;
  startCoordinate.longitude = −122.419415;
  return startCoordinate;
}

- (NSString*) mapTitle{

  return @" map";
}

You of course have to include the MapKit in Trip, so add the following to Trip.h:

#import <MapKit/MapKit.h>

You also have to add the following to Trip.h (just stick it in after the braces):

- (CLLocationCoordinate2D)initialCoordinate;
- (NSString*)mapTitle;

If you compile and build your project, you should see what's shown in Figure 5-7.

Figure 5-7. Regions determine what you see on the map.

But what if the Internet isn't available? The Apple Human Interface Guidelines (and common sense) say that you should keep the user informed of what's going on. By virtue of the fact that you've made the MapController a MKMapView delegate, your app is in the position to send a message in the event of a load failure. Adding the following code to the MapController.m file makes it final:

- (void)mapViewDidFailLoadingMap:(MKMapView *)mapView
                              withError:(NSError *)error {

  NSLog(@"Unresolved error %@, %@", error,
                                        [error userInfo]);

  UIAlertView *alert = [[UIAlertView alloc]
      initWithTitle:@"Unable to load the map"
      message:@"Check to see if you have internet access"
      delegate:self cancelButtonTitle: @"Thanks"
      otherButtonTitles:nil];
  [alert show];
  [alert release];
}

At this point, when the user touches Map in the Main view, RoadTrip displays a map centered on San Francisco, and if you pan over to Cupertino (or wherever you are), you can see the blue dot.

- (void)viewDidLoad {
  [super viewDidLoad];
  mapView.showsUserLocation = YES;
  CLLocationCoordinate2D initialCoordinate =
                                           [map initialCoordi
   nate];
  [self updateRegionLatitude: initialCoordinate.latitude longi
   tude:
               initialCoordinate.longitude
latitudeDelta:.06 longitudeDelta:.06];
self.title = [trip mapTitle];
  [mapView.userLocation addObserver:self forKeyPath:@"location"
                                           options:0
   context:NULL];
}

- (void)observeValueForKeyPath:(NSString *) keyPath
               ofObject:(id)object change:(NSDictionary *) change
               context:(void *) context {

  NSLog (@"Location changed");
}

An annotation plays a similar role to the dictionary you created in Chapter 2 of this minibook, where the dictionary was meant to hold the text to be displayed in the cell of a table view. Both dictionaries and annotations act as models for their corresponding view, with a view controller connecting the two.

Annotation objects are any object that conforms to the MKAnnotation protocol and are typically existing classes in your application's model. The job of an Annotation object is to know its location (coordinate) on the map along with the text to be displayed in the callout. The MKAnnotation protocol requires a class that adopts that protocol to implement the coordinate property. In this case, it makes sense for Site and Hotel model objects to add the responsibilities of an annotation object to their bag of tricks. After all, the Site and Hotel model objects already know what thing you want to see or what hotel you're going to stay at, respectively. It makes sense for these objects to have the coordinate and callout data as well.

Of course, the only problem is that you haven't yet created those objects. In fact, you don't create them until Book VI, where I show you how to use plists and core data to access data and store objects, respectively.

So in this case, just as an illustration, I'm going to have you add an Annotation object just to get you into the rhythm.

Here's what you need to do to make the annotations thing happen:

What you did here was this:

Trip is creating a MapAnnotation that will initialize its coordinate property with the latitude and longitude of San Francisco, which will be used by the Map view to position the annotation.

You will also need to import MapAnnotation

#import "MapAnnotation.h"

and add the method declaration to the Trip.h file.

- (NSArray*) createAnnotations;

Finally, add the code in bold to the viewDidLoad: method in MapController.m so your code can send a message to Trip to create the annotations.

- (void)viewDidLoad {

  [super viewDidLoad];
  mapView.showsUserLocation = YES;
  CLLocationCoordinate2D initialCoordinate =
                              [trip initialCoordinate];
  [self updateRegionLatitude:initialCoordinate.latitude
   longitude:initialCoordinate.longitude
           latitudeDelta:.06 longitudeDelta:.06];
  self.title = [trip mapTitle];
  [mapView.userLocation addObserver:self
   forKeyPath:@"location"  options:0 context:NULL];
  annotations = [[NSMutableArray alloc]
                                      initWithCapacity:1];
  [annotations  addObjectsFromArray:
                                [trip createAnnotations]];
}

The MapController object creates an array of annotation objects. (I'll show you how it's used next.) You'll also need to add the new annotations instance variable to MapController.h:

NSMutableArray       *annotations;

So far so good. MapAnnotation has adopted the MKAnnotation protocol, declared a coordinate property, and implemented title and subtitle methods. The MapController object then creates an array of these annotations (in this case one). The only thing left to do is send the array to the Map view to get the annotations displayed.

Displaying the annotations is easy. All you have to do is add the line of code in bold to the viewDidLoad method in MapController.m.

- (void)viewDidLoad {

  [super viewDidLoad];
  mapView.showsUserLocation = YES;
  CLLocationCoordinate2D initialCoordinate =
                              [trip initialCoordinate];
  [self updateRegionLatitude:initialCoordinate.latitude
   longitude:initialCoordinate.longitude
           latitudeDelta:.06 longitudeDelta:.06];
  self.title = [trip mapTitle];
  [mapView.userLocation addObserver:self
    forKeyPath:@"location"  options:0 context:NULL];
  NSMutableArray* annotations = [[NSMutableArray alloc]
                                      initWithCapacity:1];
  [annotations  addObjectsFromArray:
                                [trip createAnnotations]];
  [mapView addAnnotations:annotations];
}

The MapController sends the addAnnotations: message to the Map view, passing it an array of objects that conform to the MKAnnotation protocol; that is, each one has a coordinate property and an optional title (and subtitle) method if you want to actually display something in the annotation callout.

The Map view places annotations on the screen by sending its delegate the mapView:viewForAnnotation: message. This message is sent for each annotation object in the array. Here you can create a custom view or return nil to use the default view. (If you don't implement this delegate method — which you won't, in this case — the default view is also used.

Creating your own Annotation views is beyond the scope of this book (although I will tell you that the most efficient way to provide the content for an Annotation view is to set its image property). Fortunately, the default Annotation view is fine for your purposes. It displays a pin in the location specified in the coordinate property of the Annotation delegate — MapAnnotation in this case, and later Sight and Hotel), and when the user touches the pin, the optional title and subtitle text will display if the title and subtitle methods are implemented in the annotation delegate.

If you compile and build your project, you can check out one of the annotations you just added in Figure 5-8.

Figure 5-8. An annotation.