ABPicker C Reference

Derived from
Framework
AddressBook/ABAddressBookC.h
Companion guide
Declared in
ABPeoplePickerC.h

Overview

The ABPicker opaque type allows you create and manipulate people-picker windows in an application’s user interface.

Use ABPickerCreate to create a people-picker window and ABPickerSetVisibility to make it visible. Use ABPickerAddProperty to add properties to the record list. Users can specify which property to display by clicking the property column in the record list and choosing the desired property.

Functions

ABPickerAddProperty

Adds a property to the group of properties available in the record list. Use ABPickerRemoveProperty to remove a property from the list and ABPickerCopyProperties to obtain the list of properties available in the list.

void ABPickerAddProperty (
   ABPickerRef inPicker,
   CFStringRef inProperty
);
Parameters
inPicker

The people-picker window to manipulate.

inProperty

The property to add, specified using one of the constants defined in ABPerson and ABRecord or a custom string.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerChangeAttributes

Specifies the selection behaviors for a people-picker window. Use ABPickerGetAttributes to obtain the selection behaviors specified for the window.

void ABPickerChangeAttributes (
   ABPickerRef inPicker,
   ABPickerAttributes inAttributesToSet,
   ABPickerAttributes inAttributesToClear
);
Parameters
inPicker

The people-picker window to manipulate.

inAttributesToSet

The attributes to set for the window. The possible selection behaviors are described in ABPickerAttributes.

inAttributesToClear

The attributes to unset for the window. The possible selection behaviors are described in ABPickerAttributes.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerClearSearchField

Clears the search field and resets the list of displayed records.

void ABPickerClearSearchField (
   ABPickerRef inPicker
);
Parameters
inPicker

The people-picker window to manipulate.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerCopyColumnTitle

Obtains the title of a custom property.

CFStringRef ABPickerCopyColumnTitle (
   ABPickerRef inPicker,
   CFStringRef inProperty
);
Parameters
inPicker

The people-picker window in question.

Return Value

The title of the column that displays the custom property in the record list.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerCopyDisplayedProperty

Returns the name of the property currently displayed in the record list.

CFStringRef ABPickerCopyDisplayedProperty (
   ABPickerRef inPicker
);
Parameters
inPicker

The people-picker window in question.

Return Value

The name of the property displayed.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerCopyProperties

Obtains the list of properties available in the record list. Use ABPickerAddProperty to add a property to the record list and ABPickerRemoveProperty to remove a property from the list.

CFArrayRef ABPickerCopyProperties (
   ABPickerRef inPicker
);
Parameters
inPicker

The people-picker window in question.

Return Value

An array with the list of properties available in the record list.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerCopySelectedGroups

Returns the groups selected in the group list as an array of ABGroup objects.

CFArrayRef ABPickerCopySelectedGroups (
   ABPickerRef inPicker
);
Parameters
inPicker

The people-picker window in question.

Return Value

An array with the groups selected in the group list.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerCopySelectedIdentifiers

Returns the identifiers of the selected values in a multi-value property or an empty array if the property displayed is a single-value property.

CFArrayRef ABPickerCopySelectedIdentifiers (
   ABPickerRef inPicker,
   ABPersonRef inPerson
);
Parameters
inPicker

The people-picker window in question.

inPerson

The ABPerson that contains the multi-value property in question.

Return Value

An array of CFString objects representing the selected identifiers.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerCopySelectedRecords

Returns the selection in the record list as an array of ABGroup or ABPerson objects.

CFArrayRef ABPickerCopySelectedRecords (
   ABPickerRef inPicker
);
Parameters
inPicker

The people-picker window in question.

Return Value

An array with the groups or records selected in the record list.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerCopySelectedValues

Returns the selected values in a multi-value property or an empty array if no values are selected or the property displayed is a single-value property.

CFArrayRef ABPickerCopySelectedValues (
   ABPickerRef inPicker
);
Parameters
inPicker

The people-picker window in question.

Return Value

An array of the values selected.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerCreate

Creates an ABPickerRef. The corresponding window is hidden. Invoke ABPickerSetVisibility to show it. Release with CFRelease.

ABPickerRef ABPickerCreate (
   void
);
Return Value

The object that represents the people-picker window.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerEditInAddressBook

Launches Address Book to edit the item selected in the people-picker window.

void ABPickerEditInAddressBook (
   ABPickerRef inPicker
);
Parameters
inPicker

The people-picker window in question.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerDeselectAll

Deselects all selected groups, records, and values in multi-value properties.

void ABPickerDeselectAll (
   ABPickerRef inPicker
);
Parameters
inPicker

The people-picker window to manipulate.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerDeselectGroup

Deselects a group in the group list.

void ABPickerDeselectGroup (
   ABPickerRef inPicker,
   ABGroupRef inGroup
);
Parameters
inPicker

The people-picker window to manipulate.

inGroup

The group to deselect in the list.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerDeselectIdentifier

Deselects a value in multi-value property currently displayed in the record list.

void ABPickerDeselectIdentifier (
   ABPickerRef inPicker,
   ABPersonRef inPerson,
   CFStringRef inIdentifier
);
Parameters
inPicker

The people-picker window to manipulate.

inPerson

The ABPerson that contains the multi-value property in question.

inIdentifier

The identifier of the value to deselect in the multi-value property.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerDeselectRecord

Deselects a group in the record list.

void ABPickerDeselectRecord (
   ABPickerRef inPicker,
   ABRecordRef inRecord
);
Parameters
inPicker

The people-picker window to manipulate.

inRecord

The record to deselect in the list.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerGetAttributes

Indicates the selection behaviors selected a people-picker window. Use ABPickerChangeAttributes to specify selection behaviors for the window.

ABPickerAttributes ABPickerGetAttributes (
   ABPickerRef inPicker
);
Parameters
inPicker

The people-picker window in question.

Return Value

An OptionBits object with the selection behaviors selected for the window. The possible selection behaviors are described in ABPickerAttributes.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerGetDelegate

Obtains the delegate for a people-picker window.

EventTargetRef ABPickerGetDelegate (
   ABPickerRef inPicker
);
Parameters
inPicker

The people-picker window in question.

Return Value

The window’s delegate.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerGetFrame

Returns the position and size of the people-picker window.

void ABPickerGetFrame (
   ABPickerRef inPicker,
   HIRect *outFrame
);
Parameters
inPicker

The people-picker window in question.

outFrame

On output, the position and size of the window in screen coordinates.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerIsVisible

Indicates whether the people-picker window is visible.

bool ABPickerIsVisible (
   ABPickerRef inPicker
);
Parameters
inPicker

The people-picker window in question.

Return Value

true when the window is visible, false otherwise.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerRemoveProperty

Removes a property from the group of properties whose values are shown in the record list. Use ABPickerAddProperty to add a property to the record list and ABPickerCopyProperties to obtain the list of properties shown in the record list.

void ABPickerRemoveProperty (
   ABPickerRef inPicker,
   CFStringRef inProperty
);
Parameters
inPicker

The people-picker window to manipulate.

inProperty

The property to remove, specified using one of the kAB...Property constants or a custom string.

Return Value
Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerSelectGroup

Selects a group or a set of groups in the group list.

void ABPickerSelectGroup (
   ABPickerRef inPicker,
   ABGroupRef inGroup,
   bool inExtendSelection
);
Parameters
inPicker

The people-picker window to manipulate.

inGroup

The group to select.

inExtendSelection

true if you want to add inGroup to the list of selected groups in the group list; false if you want inGroup to be the only group selected in the list.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerSelectIdentifier

Selects a value or a set of values in a multi-value property.

void ABPickerSelectIdentifier (
   ABPickerRef inPicker,
   ABPersonRef inPerson,
   CFStringRef inIdentifier,
   bool inExtendSelection
);
Parameters
inPicker

The people-picker window to manipulate.

inPerson

The person with the multi-value property with the value to select.

inIdentifier

The identifier of the value to select in the multi-value property.

inExtendSelection

true if you want to add the value to the list of selected values in the multi-value property of the desired person; false if you want the value to be the only value selected in the list.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerSelectInAddressBook

Launches Address Book and selects the item selected in the people-picker window.

void ABPickerSelectInAddressBook (
   ABPickerRef inPicker
);
Parameters
inPicker

The people-picker window in question.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerSelectRecord

Selects a record or a set of records in the record list.

void ABPickerSelectRecord (
   ABPickerRef inPicker,
   ABRecordRef inRecord,
   bool inExtendSelection
);
Parameters
inPicker

The people-picker window to manipulate.

inRecord

The record to select.

inExtendSelection

true if you want to add inRecord to the list of selected records in the record list; false if you want inRecord to be the only record selected in the list.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerSetColumnTitle

Sets the title for a custom property.

void ABPickerSetColumnTitle (
   ABPickerRef inPicker,
   CFStringRef inTitle,
   CFStringRef inProperty
);
Parameters
inPicker

The people-picker window to manipulate.

inTitle

The new column title.

inProperty

The property whose column’s title to set.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerSetDelegate

Sets the event handler for people-picker events.

void ABPickerSetDelegate (
   ABPickerRef inPicker,
   EventTargetRef inDelegate
);
Parameters
inPicker

The people-picker window in question.

inDelegate

The delegate for the window.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerSetDisplayedProperty

Displays one of the properties whose values are shown in the record list.

void ABPickerSetDisplayedProperty (
   ABPickerRef inPicker,
   CFStringRef inProperty
);
Parameters
inPicker

The people-picker window to manipulate.

inProperty

The property to display.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerSetFrame

Specifies the position and size of the people-picker window.

void ABPickerSetFrame (
   ABPickerRef inPicker,
   const HIRect *inFrame
);
Parameters
inPicker

The people-picker window to manipulate.

inFrame

The size and position of the window in screen coordinates.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerSetVisibility

Shows or hides a people-picker window.

void ABPickerSetVisibility (
   ABPickerRef inPicker,
   bool visible
);
Parameters
inPicker

The people-picker window to manipulate.

visible

true to show the window and false to hide it.

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

Data Types

ABPickerRef

A reference to an ABPicker object.

typedef struct OpaqueABPicker *ABPickerRef;
Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

ABPickerAttributes

A bitfield used to specify the selection behavior for the values of multi-value properties.

typedef OptionBits ABPickerAttributes;
Discussion

Use the constants listed in “People-Picker Selection Behavior.”

When multiple behaviors are selected, the most restrictive behavior is used. The default behavior is single-value selection (kABPickerSingleValueSelection).

Availability
  • Available in OS X v10.3 and later.
Declared In
ABPeoplePickerC.h

Constants

People-Picker Event Class

This is the People Picker event class.

enum {
   kEventClassABPeoplePicker = 'abpp'
};
Constants
kEventClassABPeoplePicker

The class of people-picker events.

Available in OS X v10.3 and later.

Declared in ABPeoplePickerC.h.

Availability
  • Available in OS X v10.3 and later.

People-Picker Event Kinds

Constants used by ABPickerAttributes to specify People Picker event types.

enum {
   kEventABPeoplePickerGroupSelectionChanged = 1,
   kEventABPeoplePickerNameSelectionChanged = 2,
   kEventABPeoplePickerValueSelectionChanged = 3,
   kEventABPeoplePickerDisplayedPropertyChanged = 4,
   kEventABPeoplePickerGroupDoubleClicked = 5,
   kEventABPeoplePickerNameDoubleClicked = 6,
};
Constants
kEventABPeoplePickerGroupSelectionChanged

The selection in the group list changed.

Available in OS X v10.3 and later.

Declared in ABPeoplePickerC.h.

kEventABPeoplePickerNameSelectionChanged

The selection in the name list changed.

Available in OS X v10.3 and later.

Declared in ABPeoplePickerC.h.

kEventABPeoplePickerValueSelectionChanged

The selection in a multi-value property changed.

Available in OS X v10.3 and later.

Declared in ABPeoplePickerC.h.

kEventABPeoplePickerDisplayedPropertyChanged

The displayed property in the record list changed.

Available in OS X v10.3 and later.

Declared in ABPeoplePickerC.h.

kEventABPeoplePickerGroupDoubleClicked

A group in the group list was double-clicked.

Available in OS X v10.3 and later.

Declared in ABPeoplePickerC.h.

kEventABPeoplePickerNameDoubleClicked

A record in the record list was double-clicked.

Available in OS X v10.3 and later.

Declared in ABPeoplePickerC.h.

Discussion

A people-picker window delegate is notified when the events defined earlier occur. People Picker events contain an event parameter, which contains the ABPicker object. Use the following code to obtain the ABPicker object:

GetEventParameter ( inEvent, kEventParamABPickerRef,
                    typeCFTypeRef, NULL, sizeof(ABPickerRef),
                    NULL, &outPickerRef );
Availability
  • Available in OS X v10.3 and later.

People-Picker Event Parameter Name

Use this constant to obtain the ABPicker object from a People Picker event.

enum {
   kEventParamABPickerRef = 'abpp'
};
Constants
kEventParamABPickerRef

The parameter name of people-picker events.

Available in OS X v10.3 and later.

Declared in ABPeoplePickerC.h.

Availability
  • Available in OS X v10.3 and later.

People-Picker Selection Behavior

Constants to specify the selection behavior for the values of multi-value properties.

enum
{
   kABPickerSingleValueSelection = 1 << 0,
   kABPickerMultipleValueSelection = 1 << 1,
   kABPickerAllowGroupSelection = 1 << 2,
   kABPickerAllowMultipleSelection = 1 << 3
};
Constants
kABPickerSingleValueSelection

Allows the user to select a single value. This is the default behavior.

Available in OS X v10.3 and later.

Declared in ABPeoplePickerC.h.

kABPickerMultipleValueSelection

Allows the user to select multiple values.

Available in OS X v10.3 and later.

Declared in ABPeoplePickerC.h.

kABPickerAllowGroupSelection

Allows the user to select entire groups in the groups list. Otherwise at least one record in the group is selected when the user selects a group. The default is not to allow group selection.

Available in OS X v10.3 and later.

Declared in ABPeoplePickerC.h.

kABPickerAllowMultipleSelection

Allows the user to select more than one group or record at a time. The default is to allow multiple selection.

Available in OS X v10.3 and later.

Declared in ABPeoplePickerC.h.