9.2. Address Book UI

The Address Book UI framework provides two key user interfaces: a people "picker" navigation controller to choose contacts, and a view controller to display a single contact.

9.2.1. Person Views

The ABPersonViewController provides a simple interface to display a single contact to the user. The person view requires a CFRecordRef, which you learned about earlier in the chapter. This record is passed to the person view, which performs all the grunt work of loading and displaying the individual's contact information.

You create an ABPersonViewController in the same fashion as any other view controller:

ABPersonViewController *viewController = [ [ ABPersonViewController alloc ]
    init
];

Set the desired record to display to the displayedPerson property:

viewController.displayedPerson = myRecord;

Next, you'll create an array of properties you'd like to display to the user. Only the properties you specify will be displayed unless the contact is edited, in which case all will be displayed. The properties available are the same enumerated values you learned about earlier in this chapter. Each is added as an NSNumber object:

NSMutableArray *properties = [ [ NSMutableArray alloc ] init ];
[ properties addObject: [ NSNumber numberWithInt: kABPersonFirstNameProperty ]];
[ properties addObject: [ NSNumber numberWithInt: kABPersonLastNameProperty ]];
[ properties addObject: [ NSNumber numberWithInt: kABPersonOrganizationProperty ]];
viewController.displayedProperties = properties;

                                          

If you would like the user to be able to edit the contact, set the allowsEditing property to YES:

viewController.allowsEditing = YES;

9.2.2. People Pickers

If your application has a need to display a list of contacts to the user, the ABPeoplePickā erNavigationController class was designed with you in mind. This navigation controller displays a list of contacts and allows the user to select one. Once selected, you can choose to display the contact to the user or use a delegate method to add your own behavior once the individual has been selected.

To create a people picker, instantiate an ABPeoplePickerNavigationController object:

ABPeoplePickerNavigationController *peoplePicker = [
    [ ABPeoplePickerNavigationController alloc ] init
];

If your picker will allow the user to view an individual contact, you'll assign a set of properties you wish the user to see. The default is to show the user all available fields. The properties available are the same enumerated values you learned about earlier in this chapter. Each is added as an NSNumber object:

NSMutableArray *properties = [ [ NSMutableArray alloc ] init ];
[ properties addObject: [ NSNumber numberWithInt: kABPersonFirstNameProperty ]];
[ properties addObject: [ NSNumber numberWithInt: kABPersonLastNameProperty ]];
[ properties addObject: [ NSNumber numberWithInt: kABPersonOrganizationProperty ]];
peoplePicker.displayedProperties = properties;

                                          

To assign a delegate to receive notifications when the user selects a person, assign your delegate to the peoplePickerDelegate property of the picker:

peoplePicker.peoplePickerDelegate = self;

You can then add the navigation controller to a window or existing view:

[ window addSubview: [ peoplePicker view ] ];

9.2.2.1. Delegate methods

Three delegate methods are invoked for different people picker actions. If the user decides to cancel his selection, the peoplePickerNavigationControllerDidCancel is notified. This method should gracefully handle a failure to select a contact:

- (void)peoplePickerNavigationControllerDidCancel:
    (ABPeoplePickerNavigationController *)peoplePicker
{
    /* Additional code to handle cancel */
}

When a person is selected, the delegate is notified with the ABRecordRef of the selected user and is consulted about whether it should continue. If the delegate returns YES, the contact is displayed to the user with an internal ABPersonViewController created by the people picker. If your application will perform some other action, return NO here and transition to a different screen:

- (BOOL)peoplePickerNavigationController:
    (ABPeoplePickerNavigationController *)peoplePicker
     shouldContinueAfterSelectingPerson:(ABRecordRef)person
{
    /* Additional code to handle contact selection */
}

If the user taps a property within the contact display, a third notification is sent to the delegate containing the selected property. This also asks the user if it should continue. If your application will perform some other action when the user selects a property, return NO here and transition to a different screen:

- (BOOL)peoplePickerNavigationController:
    (ABPeoplePickerNavigationController *)peoplePicker
    shouldContinueAfterSelectingPerson:(ABRecordRef)person
    property:(ABPropertyID)property
    identifier:(ABMultiValueIdentifier)identifier
{
    /* Additional code to handle property selection */
}

9.2.3. Further Study

  • You can find additional information about the address book controller and properties inside the AddressBookUI.framework header directories. You'll find these deep within /Developer/Platforms/iPhoneOS.platform/ in your SDK headers.