Advanced Search

Log In | Not a Member?

Contact ADC

Next Page > Hide TOC

ABPicker Reference for C

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 kAB...Property constants (defined in ABPerson and ABRecord) or a custom string.

Availability

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

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

Data Types

ABAddressBookRef

A reference to an ABPicker object.

typedef struct OpaqueABPicker *ABPickerRef;

Availability

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

Declared In

ABPickerAttributes

These constants specify the selection behavior for the values of multi-value properties.

typedef OptionBits ABPickerAttributes;

Discussion

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

Availability

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

Declared In

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 Mac OS X v10.3 and later.

Declared in ABPeoplePickerC.h

Availability

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

People-Picker Event Kinds

Constants used 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 Mac OS X v10.3 and later.

Declared in ABPeoplePickerC.h

kEventABPeoplePickerNameSelectionChanged

The selection in the name list changed.

Available in Mac OS X v10.3 and later.

Declared in ABPeoplePickerC.h

kEventABPeoplePickerValueSelectionChanged

The selection in a multi-value property changed.

Available in Mac OS X v10.3 and later.

Declared in ABPeoplePickerC.h

kEventABPeoplePickerDisplayedPropertyChanged

The displayed property in the record list changed.

Available in Mac OS X v10.3 and later.

Declared in ABPeoplePickerC.h

kEventABPeoplePickerGroupDoubleClicked

A group in the group list was double-clicked.

Available in Mac OS X v10.3 and later.

Declared in ABPeoplePickerC.h

kEventABPeoplePickerNameDoubleClicked

A record in the record list was double-clicked.

Available in Mac 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 Mac 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 Mac OS X v10.3 and later.

Declared in ABPeoplePickerC.h

Availability

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

Next Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice