When Whereami launches, we want it to find the current location and display it on a map. In the last chapter, you worked directly with Core Location to find the user’s location. Now this won’t be necessary because an instance of MKMapView knows how to use Core Location to find the user’s location. All you have to do is set the showsUserLocation property of an MKMapView to YES, and it will show the user’s location on the map.
At the end of application:didFinishLaunchingWithOptions:, replace the message that tells the locationManager to update its location with one that tells the MKMapView to show the current location.
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
locationManager = [[CLLocationManager alloc] init];
[locationManager setDelegate:self];
[locationManager setDistanceFilter:kCLDistanceFilterNone];
[locationManager setDesiredAccuracy:kCLLocationAccuracyBest];
// [locationManager startUpdatingLocation];
[worldView setShowsUserLocation:YES];
// This line may say self.window, don't worry about that
[[self window] makeKeyAndVisible];
return YES;
}
Build and run the application. A few moments after the application launches, the map will display a blue annotation dot on your current location. Unfortunately, because you are looking at a map of the entire world, the blue dot is the size of Brazil and not exactly useful for figuring out where you are. Clearly, the application needs to zoom in on the current location. Let’s figure out when and how we can do this.
For now, assume there is a “zoom-in-on-location” message you can send to an instance of MKMapView. The question is when would you send that message? When the application starts, it takes time for the device to determine the location. So you can’t send it in application:didFinishLaunchingWithOptions: because you don’t yet know the location to zoom in on. Nor do you want to continually tell the MKMapView to zoom its map; that would be inefficient.
Instead, how about delegation? MKMapView has a delegate property that you set to be the instance of WhereamiAppDelegate. In WhereamiAppDelegate.h, declare that WhereamiAppDelegate conforms to the MKMapViewDelegate protocol.
@interface WhereamiAppDelegate : NSObject
<UIApplicationDelegate, CLLocationManagerDelegate, MKMapViewDelegate>
{
(While you do not have to declare that a class conforms to a delegate protocol, it is helpful to do so. First, a quick glance at the header file tells you that the class serves as a delegate for a particular type of object. Second, and perhaps more important, Xcode will see this declaration and offer code completion in the implementation file for the methods in that protocol.)
The map view will send messages to its delegate when interesting events happen. Perhaps there is a message in the MKMapViewDelegate protocol for when the map view finds the user’s location. That would be the perfect time to “do the zoom.” We can find out if the protocol declares such a message in the Apple documentation.
There’s nothing more important we can teach you than how to use the Apple documentation. So hang on as we tackle – step-by-step – the questions of when and how to display a zoomed-in map of the current location.
Overall, the documentation has four parts: API Reference, System Guides, Tools Guides, and Sample Code. The API Reference shows you every class, protocol, function, structure, method, and anything else you may use from Cocoa Touch. The System Guides give you high-level overviews and discussion about concepts in Cocoa Touch. The Tools Guide is the manual for Xcode and the rest of the developer tools suite.
While all four parts are useful, the API Reference is absolutely essential to everyday programming. There are so many classes and methods built into Cocoa Touch that it is impossible for a developer to remember them all. At no point in your iOS developer career will you outgrow the API Reference.
From the menu, choose . The organizer window will appear with the Documentation item selected (Figure 5.7). Click the magnifying glass icon and choose Show Find Options to show the Find Options panel, which allows you to tailor your search. In the search box, enter MKMapViewDelegate.
When you search for a term, the results from each part of the documentation are listed in the table on the left side of the window. The top section titled Reference is the API Reference.
Search results from the API Reference are contained in a number of nested categories. Each result has an icon that indicates whether it is a class, a method, a protocol or something else. Collectively, we call these items symbols, and their mappings are shown in Figure 5.8.
In your search results, look under the Reference heading for an item titled MKMapViewDelegate and labeled with a Pr icon. Select that item to see the reference page for the MKMapViewDelegate protocol (Figure 5.9). Then scroll down to the Tasks section, which groups the protocol’s methods by what they used are for.
Recall that we’re looking for a method that the MKMapView will send its delegate when it has found the user’s location. See anything interesting? How about mapView:didUpdateUserLocation:? Blue text in the documentation indicates hyperlinks, so you can click on this method name to get more details (Figure 5.10).
The documentation confirms that this is the method we need, so go ahead and implement a stub for it in WhereamiAppDelegate.m. (If possible, copy and paste the method signature from the documentation; this is best for delegate methods where typos and capitalization errors are especially difficult to diagnose.)
- (void)mapView:(MKMapView *)mv didUpdateUserLocation:(MKUserLocation *)u
{
// Here we are... but how do we actually zoom?
}
Now we know when to zoom, and we can turn our attention to the problem of how. To problem-solve in programming, it’s best to start with the goal and what we already know. The goal is to display a map that is zoomed in on the user’s current location. We know that when the MKMapView finds the user’s location, it sends the message mapView:didUpdateUserLocation: to its delegate. We also know that, in the mapView:didUpdateUserLocation: method, a pointer to an MKUserLocation instance will be available.
In addition, we know from experience that the MKMapView does not automatically zoom in when it finds the user’s location, so it must be told to do so. This, of course, means that MKMapView must implement a method that zooms in on a location. Let’s track this method down in the API Reference.
Search for the MKMapView class. In the class reference page, look for Manipulating the Visible Portion of the Map in the Tasks section. There are a handful of methods and properties in this section; we’ll start at the top with the region property. The details for region tell us that this property is of type MKCoordinateRegion and that it provides an implicit zoom. Sounds perfect. But to set this property, we need to know more about MKCoordinateRegion.
Search for MKCoordinateRegion. Its details are in the Map Kit Data Types Reference. MKCoordinateRegion has two members of types CLLocationCoordinate2D and MKCoordinateSpan. The CLLocationCoordinate2D is the center of the map and the MKCoordinateSpan determines the level of zoom (Figure 5.11).
To set the region property of the map view, we’ll need to package up one of these instances, so let’s find out how we can do this. Search again for MKCoordinateRegion and this time select the Map Kit Functions Reference. One of these functions, MKCoordinateRegionMakeWithDistance, allows you to specify a region with a CLLocationCoordinate2D and the north-south and east-west limits of the zoom in meters. For the limits, we’ll use 250 by 250 meters. For the coordinate, we need the user’s location. Where can we get that?
How about the MKUserLocation object that the MKMapView sends its delegate in the mapView:didUpdateUserLocation: message? Search the documentation for MKUserLocation, and you’ll find it has a property called location that holds the current location of the device. Keep drilling down, and you’ll find that location is a CLLocation object, which has a coordinate property of type CLLocationCoordinate2D. Success! We can use information in the MKUserLocation to prepare an MKCoordinateRegion, which we then can use to set the region property of the map view.
Right now, getting the information from the MKUserLocation takes two steps: we send MKUserLocation the message location and then send the returned CLLocation object the message coordinate. The data returned from coordinate then becomes the MKCoordinateRegion’s center.
But nosing around the API Reference has its rewards. Before we add this code to WhereamiAppDelegate.m, take another look at the MKUserLocation reference. At the top, it tells us that MKUserLocation conforms to the protocol MKAnnotation. Click on the link for that protocol, and you’ll see that classes conforming to it are required to have a property named coordinate of type CLLocationCoordinate2D. So we can simplify the process and send the message coordinate directly to the MKUserLocation.
Now, in WhereamiAppDelegate.m, add the new code to mapView:didUpdateUserLocation:.
- (void)mapView:(MKMapView *)mv didUpdateUserLocation:(MKUserLocation *)u
{
CLLocationCoordinate2D loc = [u coordinate];
MKCoordinateRegion region = MKCoordinateRegionMakeWithDistance(loc, 250, 250);
[worldView setRegion:region animated:YES];
}
Notice that the MKMapView is sent the message setRegion:animated: instead of simply setRegion:. What’s the difference? Check the documentation.
Build and run the application again. When the map figures out where you are in the world, it zooms in on that location.
This is pretty standard workflow for iOS programming: you want an object to do something and you follow the bread crumbs in the API Reference. There will be dead ends and wild goose chases, but eventually you’ll find what you need. As you go through this book, don’t hesitate to look up the classes, protocols, and methods we use to see what else they can do. You want to become as comfortable as possible with the API Reference. The more you use it, the easier it will be to progress as an iOS developer. You cannot be an iOS developer without using the API Reference.
Apple will continue to update the iOS SDK and introduce iOS devices with new features and capabilities. If you understand and are comfortable using the Apple documentation, you will be ready to use whatever Apple dreams up in the future.
Now that Whereami displays a nicely-zoomed map of the current location, we can turn to adding annotations. Let’s start with an introduction to the MKAnnotation protocol.
MKAnnotation is not a delegate protocol. Instead, it declares a set of methods that are useful to any class that wants to put itself on the map. Imagine an application that maps everything in a neighborhood, including restaurants, factories, and train stations. These objects could be very different and hierarchically unrelated in your application, but they all can be added to a map view if they conform to MKAnnotation.
When an object conforming to MKAnnotation is added to an MKMapView, an instance of MKAnnotationView (or one of its subclasses) is created and added to the map view. The MKAnnotationView keeps a pointer to the MKAnnotation-conforming object that it represents so it can ask it for data as needed. The relationships between these objects are shown in Figure 5.12.
Now you’re going to write a new class called MapPoint that will conform to MKAnnotation. When the user tags a location, an instance of MapPoint will be created and represented on the map.
From the menu, select and then . Then choose Cocoa Touch from the iOS section, select Objective-C class, and click Next (Figure 5.13).
On the next pane, select NSObject from the superclass list and hit Next.
A sheet will drop down for you to save the files for this class. Name the class MapPoint and click Save (Figure 5.14). This creates the files MapPoint.h and MapPoint.m and adds them to your project.
In MapPoint.h, declare that MapPoint conforms to MKAnnotation. Also declare two properties and an initializer.
#import <Foundation/Foundation.h>
#import <CoreLocation/CoreLocation.h>
#import <MapKit/MapKit.h>
@interface MapPoint : NSObject <MKAnnotation>
{
NSString *title;
CLLocationCoordinate2D coordinate;
}
// A new designated initializer for instances of MapPoint
- (id)initWithCoordinate:(CLLocationCoordinate2D)c title:(NSString *)t;
// This is a required property from MKAnnotation
@property (nonatomic, readonly) CLLocationCoordinate2D coordinate;
// This is an optional property from MKAnnotation
@property (nonatomic, copy) NSString *title;
@end
The protocol defines coordinate as a read-only property, which means there is a method named coordinate that returns a CLLocationCoordinate2D. While most methods declared in the MKAnnotation protocol are optional, the coordinate method is required – if MapPoint is to conform to the MKAnnotation protocol, it must implement coordinate.
Switch to MapPoint.m. (The keyboard shortcut for switching between the header file and the implementation file is Command-Control-Up arrow.) Synthesize the properties and add the implementations for the initializer and dealloc.
#import "MapPoint.h"
@implementation MapPoint
@synthesize coordinate, title;
- (id)initWithCoordinate:(CLLocationCoordinate2D)c title:(NSString *)t
{
self = [super init];
if (self) {
coordinate = c;
[self setTitle:t];
}
return self;
}
- (void)dealloc
{
[title release];
[super dealloc];
}
@end
Note that you don’t release coordinate in the dealloc method because it is not an Objective-C object and can’t receive messages. The CLLocationCoordinate2D structure’s memory will live inside each instance of MapPoint, and it will be created and destroyed automatically along with the object.
The protocol defines the required coordinate as a read-only property, which means there must be a method named coordinate that returns a CLLocationCoordinate2D, but it doesn’t have to be a property in the class declaration. In fact, we don’t have to create the matching instance variables, either. The MKAnnotation protocol, like all protocols, only dictates method signatures. As long as the signatures match exactly, the conforming class can implement them however it wants with whatever instance variables it chooses. For example, the title method could perform some logic with information is has available to it and then return a value:
- (NSString *)title
{
if ([self isEastOfTheMississippi])
return @"Buying supplies"
return @"On the Oregon Trail, uncharted territory";
}
Therefore, we can think of a protocol as a contract, whereby the conforming class says, “I promise to give you my interpretation of this contract when asked.” The objects that speak to the conforming class through the protocol honor this contract by saying, “I promise to only ask you things in this contract.” For example, MKAnnotationView has a annotation property declared as
@property (nonatomic, retain) id <MKAnnotation> annotation;
This declaration says that the annotation can be of any type (id), as long as it conforms to the MKAnnotation protocol (<MKAnnotation>). Therefore, the MKAnnotationView will only send messages from the MKAnnotation protocol to its annotation; it won’t make any assumptions about the other messages that object might respond to.
You’ve added a lot of code, so you may want to build the application to check for syntax errors before you continue. There’s no need to run it, however, because the application’s behavior has not changed.
Now that you have your own class that conforms to MKAnnotation, you can tag locations on the map. The user will enter the location’s name in the UITextField and then tap the Done button on the keyboard. The tapping of the Done button is the signal to add an annotation. How will we know this event has occurred? Delegation, of course.
In the XIB file, you set the text field’s delegate to be the instance of WhereamiAppDelegate. This means WhereamiAppDelegate can implement methods from the UITextFieldDelegate protocol. One of these methods is textFieldShouldReturn:. When the keyboard’s return key is tapped, the UITextField sends this message to its delegate and asks if it really should return. At the same time, the delegate has the opportunity to perform tasks that should coincide with the returning of the text field.
In WhereamiAppDelegate.h, declare that WhereamiAppDelegate conforms to the UITextFieldDelegate protocol.
@interface WhereamiAppDelegate : NSObject
<UIApplicationDelegate, CLLocationManagerDelegate, MKMapViewDelegate,
UITextFieldDelegate>
{
In WhereamiAppDelegate.m, implement textFieldShouldReturn:.
- (BOOL)textFieldShouldReturn:(UITextField *)tf
{
// This method isn't implemented yet - but will be soon.
[self findLocation];
[tf resignFirstResponder];
return YES;
}
For now, ignore findLocation. You will write the implementation for that in a moment. First, let’s talk about text editing and the first responder.
UIResponder is a class in the UIKit framework. A responder is responsible for receiving and handling events that are associated with it. For example, a button is a responder that handles touch events, like a tap. In addition, one of the responders is the first responder of the window. Only one responder can be the first responder at a time. The first responder handles events that aren’t associated with another responder. For instance, a tap is sent to the responder object that was tapped, but a shake has no associated responder and is sent to the first responder instead. We’ll talk more about the first responder and event-handling in Chapter 8 and Chapter 20.
For now, let’s focus on UITextField. A UITextField is also a responder: it is a direct subclass of UIControl, which is a subclass of UIView, which is a subclass of UIResponder. When a UITextField is tapped, it handles this event by becoming the first responder.
When a UITextField becomes the first responder, a keyboard appears on the screen. To remove the keyboard from the screen, you tell the UITextField to give up its first responder status by sending it the message resignFirstResponder. Once the first responder of the window is no longer a UITextField, the keyboard will disappear.
(Everything about UITextField holds true for the class UITextView, too. The difference between UITextView and UITextField is that UITextView allows for multi-line editing: a text view’s return key enters the newline character whereas a text field’s return key dispatches the delegate method textFieldShouldReturn:.)
To finish your Whereami application, you just need to add two final methods: findLocation, which is sent in textFieldShouldReturn:, and foundLocation:, which will be sent in locationManager:didUpdateToLocation:fromLocation:. In WhereamiAppDelegate.h, declare these two methods.
@interface WhereamiAppDelegate : NSObject
<UIApplicationDelegate, CLLocationManagerDelegate, MKMapViewDelegate,
UITextFieldDelegate>
{
CLLocationManager *locationManager;
IBOutlet MKMapView *worldView;
IBOutlet UIActivityIndicatorView *activityIndicator;
IBOutlet UITextField *locationTitleField;
}
@property (nonatomic, retain) IBOutlet UIWindow *window;
- (void)findLocation;
- (void)foundLocation:(CLLocation *)loc;
@end
The findLocation method will tell the locationManager to start looking for the current location. It will also update the user interface so that the user can’t re-enter text into the text field and will start the activity indicator spinning. The foundLocation: method will create an instance of MapPoint and add it to the worldView. It will also handle the map’s zoom and reset the states of the UI elements and the locationManager.
In WhereamiAppDelegate.m, import MapPoint.h and implement the two methods.
#import "WhereamiAppDelegate.h"
#import "MapPoint.h"
@implementation WhereamiAppDelegate
- (void)findLocation
{
[locationManager startUpdatingLocation];
[activityIndicator startAnimating];
[locationTitleField setHidden:YES];
}
- (void)foundLocation:(CLLocation *)loc
{
CLLocationCoordinate2D coord = [loc coordinate];
// Create an instance of MapPoint with the current data
MapPoint *mp = [[MapPoint alloc] initWithCoordinate:coord
title:[locationTitleField text]];
// Add it to the map view
[worldView addAnnotation:mp];
// MKMapView retains its annotations, we can release
[mp release];
// Zoom the region to this location
MKCoordinateRegion region = MKCoordinateRegionMakeWithDistance(coord, 250, 250);
[worldView setRegion:region animated:YES];
[locationTitleField setText:@""];
[activityIndicator stopAnimating];
[locationTitleField setHidden:NO];
[locationManager stopUpdatingLocation];
}
Note that when importing files, you put quotation marks around header files you create and angled brackets around header files from frameworks. Angled brackets tell the compiler, “Only look in your system libraries for this file.” Quotation marks say, “Look in the directory for this project first, and if you don’t find something, then look in the system libraries.”
Finally, send the message foundLocation: when a new location is found by the CLLocationManager. Update the delegate method locationManager:didUpdateToLocation:fromLocation: in WhereamiAppDelegate.m:
- (void)locationManager:(CLLocationManager *)manager
didUpdateToLocation:(CLLocation *)newLocation
fromLocation:(CLLocation *)oldLocation
{
NSLog(@"%@", newLocation);
// How many seconds ago was this new location created?
NSTimeInterval t = [[newLocation timestamp] timeIntervalSinceNow];
// CLLocationManagers will return the last found location of the
// device first, you don't want that data in this case.
// If this location was made more than 3 minutes ago, ignore it.
if (t < -180) {
// This is cached data, you don't want it, keep looking
return;
}
[self foundLocation:newLocation];
}
Build and run the application. Enter a title into the text field, and an annotation with that title will appear on the map at your current location.