The Address Book UI framework provides three view controllers and one navigation controller for common tasks related to working with the Address Book database and contact information. By using these controllers rather than creating your own, you reduce the amount of work you have to do and provide your users with a more consistent experience.
The Address Book UI framework provides four controllers:
ABPeoplePickerNavigationController
prompts the user to select a person record from their address book.
ABPersonViewController
displays a person record to the user and optionally allows editing.
ABNewPersonViewController
prompts the user create a new person record.
ABUnknownPersonViewController
prompts the user to complete a partial person record, optionally allows them to add it to the address book.
To use these controllers, you must set a delegate for them which implements the appropriate delegate protocol. You should not need to subclass these controllers; the expected way to modify their behavior is by your implementation of their delegate. In this chapter, you will learn more about these controllers and how to use them.
For more information about delegation, see "Delegates and Data Sources" in Cocoa Fundamentals Guide. For more information about protocols, see Protocols in The Objective-C Programming Language.
This chapter includes some short code listings you can use as a starting point. For a fully worked example, see QuickContacts.
The ABPeoplePickerNavigationController
class (see Figure 3-1) allows users to browse their list of contacts and select a person and, at your option, one of that person’s properties.
To use a people picker, do the following:
Create and initialize an instance of the class.
Set the delegate, which must adopt the ABPeoplePickerNavigationControllerDelegate
protocol.
Optionally, set displayedProperties
to the array of properties you want displayed. The relevant constants are defined as integers; wrap them in an NSNumber
object using the numberWithInt:
method to get an object that can be put in an array.
Present the people picker as a modal view controller using the presentModalViewController:animated:
method. It is recommended that you present it using animation.
The following code listing shows how a view controller which implements the ABPeoplePickerNavigationControllerDelegate
protocol can present a people picker:
ABPeoplePickerNavigationController *picker = |
[[ABPeoplePickerNavigationController alloc] init]; |
picker.peoplePickerDelegate = self; |
[self presentModalViewController:picker animated:YES]; |
[picker release]; |
The people picker calls one of its delegate’s methods depending on the user’s action:
If the user cancels, the people picker calls the method peoplePickerNavigationControllerDidCancel:
of the delegate, which should dismiss the people picker.
If the user selects a person, the people picker calls the method peoplePickerNavigationController:shouldContinueAfterSelectingPerson:
of the delegate to determine if the people picker should continue. To prompt the user to choose a specific property of the selected person, return YES
. Otherwise return NO
and dismiss the picker.
If the user selects a property, the people picker calls the method peoplePickerNavigationController:shouldContinueAfterSelectingPerson:property:identifier:
of the delegate to determine if it should continue. To perform the default action (dialing a phone number, starting a new email, etc.) for the selected property, return YES
. Otherwise return NO
and dismiss the picker using the dismissModalViewControllerAnimated:
method. It is recommended that you dismiss it using animation..
The ABPersonViewController
class (see Figure 3-2) displays a record to the user.
To use this controller, do the following:
Create and initialize an instance of the class.
Set the delegate, which must adopt the ABPersonViewControllerDelegate
protocol. To allow the user to edit the record, set allowsEditing
to YES
.
Set the displayedPerson
property to the person record you want to display.
Optionally, set displayedProperties
to the array of properties you want displayed. The relevant constants are defined as integers; wrap them in an NSNumber
object using the numberWithInt:
method to get an object that can be put in an array.
Display the person view controller using the pushViewController:animated:
method of the current navigation controller. It is recommended that you present it using animation.
Important: Person view controllers must be used with a navigation controller in order to function properly.
The following code listing shows how a navigation controller can present a person view controller:
ABPersonViewController *view = [[ABPersonViewController alloc] init]; |
view.personViewDelegate = self; |
view.displayedPerson = person; // Assume person is already defined. |
[self.navigationController pushViewController:view animated:YES]; |
[personViewController release]; |
If the user taps on a property in the view, the person view controller calls the personViewController:shouldPerformDefaultActionForPerson:property:identifier:
method of the delegate to determine if the default action for that property should be taken. To perform the default action for the selected property, such as dialing a phone number or composing a new email, return YES
; otherwise return NO
.
The ABNewPersonViewController
class (see Figure 3-3) allows users to create a new person.
To use it, do the following:
Create and initialize an instance of the class.
Set the delegate, which must adopt the ABNewPersonViewControllerDelegate
protocol. To populate fields, set the value of displayedPerson
. To put the new person in a particular group, set parentGroup
.
Create and initialize a new navigation controller, and set its root view controller to the new-person view controller
Present the navigation controller as a modal view controller using the presentModalViewController:animated:
method. It is recommended that you present it using animation.
Important: New-person view controllers must be used with a navigation controller in order to function properly. It is recommended that you present a new-person view controller modally.
The following code listing shows how a navigation controller can present a new person view controller:
ABNewPersonViewController *view = [[ABNewPersonViewController alloc] init]; |
view.newPersonViewDelegate = self; |
UINavigationController *newNavigationController = [UINavigationController alloc]; |
[newNavigationController initWithRootViewController:view]; |
[self presentModalViewController:newNavigationController |
animated:YES]; |
[view release]; |
[newNavigationController release]; |
When the user taps the Save or Cancel button, the new-person view controller calls the method newPersonViewController:didCompleteWithNewPerson:
of the delegate, with the resulting person record. If the user saved, the new record is first added to the address book. If the user cancelled, the value of person
is NULL
. The delegate must dismiss the new-person view controller using the navigation controller’s dismissModalViewControllerAnimated:
method. It is recommended that you dismiss it using animation.
The ABUnknownPersonViewController
class (see Figure 3-4) allows the user to add data to an existing person record or to create a new person record for the data.
To use it, do the following:
Create and initialize an instance of the class.
Create a new person record and populate the properties to be displayed.
Set displayedPerson
to the new person record you created in the previous step.
Set the delegate, which must adopt the ABUnknownPersonViewControllerDelegate
protocol.
To allow the user to add the information displayed by the unknown-person view controller to an existing contact or to create a new contact with them, set allowsAddingToAddressBook
to YES
.
Display the unknown-person view controller using the pushViewController:animated:
method of the navigation controller. It is recommended that you present it using animation.
Important: Unknown-person view controllers must be used with a navigation controller in order to function properly.
The following code listing shows how you can present an unknown-person view controller:
ABPersonViewController *view = [[ABUnknownPersonViewController alloc] init]; |
view.unknownPersonViewDelegate = self; |
view.displayedPerson = person; // Assume person is already defined. |
view.allowsAddingToAddressBook = YES; |
[self.navigationController pushViewController:view animated:YES]; |
[personViewController release]; |
When the user finishes creating a new contact or adding the properties to an existing contact, the unknown-person view controller calls the method unknownPersonViewController:didResolveToPerson:
of the delegate with the resulting person record. If the user cancelled, the value of person
is NULL
.
Last updated: 2010-07-08