In this tutorial, you will build a simple application that prompts the user to choose a person from his or her contacts list and then shows the chosen person’s first and last name.
In Xcode, create a new project from the View Based Application template. Save the project as QuickStart.
The next step is to add the frameworks you will need. First, go to your project window and find the target named QuickStart
in the Targets group. Open its info panel (File > Get Info) and, in the General tab, you will see a list of linked frameworks.
Add the Address Book and Address Book UI frameworks to the list of linked frameworks, by clicking the plus button and selecting them from the list.
Open the nib file named QuickStartViewController.xib
in Interface Builder.
Add a button and two text labels to the view by dragging them in from the library panel. Then arrange them as shown in Figure 1-1.
Save the nib file and return to Xcode.
You have now created an interface that users can use to interact with your application. In the next section, you will write the code that runs underneath the interface. In the last section, you will complete this nib file by making the connections between the code and the interface.
Add the following code to QuickStartViewController.h
, the header file for the view controller. This code declares the outlets for the labels and the action for the button that you just created in Interface Builder. It also declares that this view controller adopts the ABPeoplePickerNavigationControllerDelegate
protocol, which you will implement next.
#import <UIKit/UIKit.h> |
#import <AddressBook/AddressBook.h> |
#import <AddressBookUI/AddressBookUI.h> |
@interface QuickStartViewController : UIViewController <ABPeoplePickerNavigationControllerDelegate> { |
IBOutlet UILabel *firstName; |
IBOutlet UILabel *lastName; |
} |
@property (nonatomic, retain) UILabel *firstName; |
@property (nonatomic, retain) UILabel *lastName; |
- (IBAction)showPicker:(id)sender; |
@end |
You can use the header file for the application delegate just as the template made it.
Add the following code to QuickStartViewController.m
, the implementation file for the view controller. This code synthesizes the accessor methods for firstName
and lastName
and implements the showPicker:
method, which is called when the user taps the Tap Me! button. The showPicker:
method creates a new people picker, sets the view controller as its delegate, and presents the picker as a modal view controller.
#import "QuickStartViewController.h" |
@implementation QuickStartViewController |
@synthesize firstName; |
@synthesize lastName; |
- (IBAction)showPicker:(id)sender { |
ABPeoplePickerNavigationController *picker = |
[[ABPeoplePickerNavigationController alloc] init]; |
picker.peoplePickerDelegate = self; |
[self presentModalViewController:picker animated:YES]; |
[picker release]; |
} |
Continuing to add code to the same file, you will now begin implementing the delegate protocol, by adding two more methods. If the user cancels, the first method is called to dismiss the people picker. If the user selects a person, the second method is called to copy the first and last name of the person into the labels and dismiss the people picker.
Note: This function ABRecordCopyValue
is used to get any property from a person record or a group record; it is used here to show the most general case. However, in actual applications, the function ABRecordCopyCompositeName
is the recommended way to get a person’s full name to display. It puts the first and last name in the order preferred by the user, which provides a more uniform user experience.
- (void)peoplePickerNavigationControllerDidCancel: |
(ABPeoplePickerNavigationController *)peoplePicker { |
[self dismissModalViewControllerAnimated:YES]; |
} |
- (BOOL)peoplePickerNavigationController: |
(ABPeoplePickerNavigationController *)peoplePicker |
shouldContinueAfterSelectingPerson:(ABRecordRef)person { |
NSString* name = (NSString *)ABRecordCopyValue(person, |
kABPersonFirstNameProperty); |
self.firstName.text = name; |
[name release]; |
name = (NSString *)ABRecordCopyValue(person, kABPersonLastNameProperty); |
self.lastName.text = name; |
[name release]; |
[self dismissModalViewControllerAnimated:YES]; |
return NO; |
} |
To fully implement the delegate protocol, you must also add one more method. The people picker calls this method when the user taps on a property of the selected person in the picker. In this application, the people picker is always dismissed when the user selects a person, so there is no way for the user to select a property of that person. This means that the method will never be called in this particular application. However if it were left out, the implementation of the protocol would be incomplete.
- (BOOL)peoplePickerNavigationController: |
(ABPeoplePickerNavigationController *)peoplePicker |
shouldContinueAfterSelectingPerson:(ABRecordRef)person |
property:(ABPropertyID)property |
identifier:(ABMultiValueIdentifier)identifier{ |
return NO; |
} |
Finally, release allocated memory.
- (void)dealloc { |
[firstName release]; |
[lastName release]; |
[super dealloc]; |
} |
@end |
You can use the implementation file for the application delegate just as the template made it.
In “Lay Out the View,” you created an interface for your application. In “Write the Header File” and “Write the Implementation File,” you wrote the code to drive that interface. Now you will complete the application by making the connections between the interface and the code.
Open the nib file named QuickStartViewController.xib
in Interface Builder.
In the Identity inspector (Tools > Identity Inspector), verify that the class identity of File’s Owner is QuickStartViewController
—it should already be set correctly for you by the template.
Control-click (or right-click) on File’s Owner and connect the outlets for firstName
and lastName
from File’s Owner to the first name and last name labels.
Control-click on the “Tap Me!” button and connect the Touch Up Inside outlet from the button to File’s Owner, selecting showPicker
as its action.
Save the nib file.
For information about outlets and making connections between them, see "Creating and Managing Outlet and Action Connections" in Interface Builder User Guide.
When you run the application, the first thing you see is a button and two empty text labels. Tapping the button brings up the people picker. When you select a person, the people picker goes away and the first and last name of the person you selected are displayed in the labels.
In this chapter, you learned to perform a fairly simple task using the two Address Book frameworks. You used the default Xcode template, and added code to present a people picker and adopt the ABPeoplePickerNavigationControllerDelegate
protocol. The concepts used in this simple example can easily be extended for a variety of other uses by your own applications.
Last updated: 2010-07-08