Quick Start Tutorial

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.

Create the Project

1. In Xcode, create a new project from the View Based Application template. Save the project as QuickStart.

2. 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.

3. 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.

   Important: The project will fail to build (with a linker error) if the Address Book and Address Book UI frameworks are not in this list of frameworks to link against.

Lay Out the View

1. Open the nib file named QuickStartViewController.xib in Interface Builder.

2. 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.

3. Save the nib file and return to Xcode.

Figure 1-1  Laying out the view in Interface Builder

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.

Write the Header File

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.

Write the Implementation File

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.

- (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.

Make Connections in Interface Builder

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.

1. Open the nib file named QuickStartViewController.xib in Interface Builder.

2. 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.

3. 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.

4. 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.

5. 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.

Build and Run the Application

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.