Используя списки свойств

И группы и люди хранят свои данные в списках свойств. Это позволяет Вашему приложению добавить свойства к записям Адресной книги, которые проигнорируют другие приложения. Посмотрите Добавляющие Свойства к Записям Адресной книги.

• Получить данные от записи, такой как описание группы или имя лица, использование valueForProperty: метод или функция C ABRecordCopyValue. Например, для получения имени для aPerson, использование:

  [aPerson valueForProperty:kABFirstNameProperty];

• Для установки данных используйте setValue:forProperty: метод. Например, для определения имени aGroup, использование:

  [aGroup setValue:@"Book Club" forProperty:kABGroupNameProperty];

• Для нахождения имен свойств по умолчанию обратитесь к Таблице 1.

Используя списки мультизначения

Много свойств могут иметь многократные значения. Например, у лица может быть несколько адресов, включая работу, домой, летний дом и почтовые адреса. Эти свойства сохранены, поскольку мультизначение перечисляет типа ABMultiValue. Каждый элемент в списке мультизначения имеет числовой индекс, уникальный идентификатор, строковая метка (такой как Домой или Работа), и значение. Каждое значение в списке мультизначения должно иметь тот же тип. Метка не должна быть уникальной; в конце концов, кто-то мог иметь больше чем один домашний или работать адрес.

• Для добавления элемента к списку мультизначения используйте addValue:withLabel: или insertValue:withLabel:atIndex: метод.

• Для получения элемента используйте valueAtIndex: или labelAtIndex: метод.

• Для удаления записи в списке мультизначения используйте removeValueAndLabelAtIndex: метод.

• Для замены значений и меток используйте replaceLabelAtIndex:withLabel: или replaceValueAtIndex:withValue: методы.

Вы используете числовой индекс для доступа к элементам в списке мультизначения, но эти индексы могут измениться, как пользователь добавляет и удаляет значения. Если Вы хотите сохранить ссылку на определенное значение, используйте уникальный идентификатор, который, как гарантируют, не изменится. Можно преобразовать назад и вперед между индексами и уникальными идентификаторами:

• Для получения уникального идентификатора для значения в определенном индексе используйте identifierAtIndex: метод.

• Для получения индекса для идентификатора используйте indexForIdentifier: метод.

Каждый список мультизначения также имеет основное значение, которое является элементом, который пользователь наиболее строго связывает с тем лицом. Например, друзья могут иметь и домой и работать адреса, но домашний адрес является их основным адресом. И коллеги могут иметь и домой и числа рабочего телефона, но число работы является их основным числом.

• Для получения идентификатора для основного значения списка мультизначения используйте primaryIdentifier метод.

• Для установки основного значения списка мультизначения используйте setPrimaryIdentifier: метод.

Изображение, связанное с лицом

У лица могут также быть связанное изображение или изображение. Изображение не фактически сохранено в базе данных Address Book (список свойств) — это сохранено в отдельном файле изображений. Это означает, что необходимо использовать различные методы для доступа к данным изображения. Можно установить изображение лица с помощью setImageData: метод, или получают изображение с помощью imageData метод. Используйте NSImage initWithData: метод для преобразования NSData объект, возвращенный imageData метод к NSImage объект.

Платформа Адресной книги определяет местоположение изображений через определенную поисковую иерархию в этом порядке:

1. Проверьте на изображение, установленное в частности пользователем.

2. Проверьте Службы каталогов на изображение входа в систему локального пользователя.

3. Проверьте на изображение в /Network/Library/Images/People/электронная почта, где электронная почта является основным адресом электронной почты пользователя.

4. Проверьте на изображение из учетной записи MobileMe пользователя, сначала против кэша в ~/Library/Caches/com.apple.AddressBook/электронная почта и затем против серверов MobileMe.

Файлы образа могут быть локальными или удаленными. Локальные изображения являются любыми изображениями в .../Library/Images/People и любые изображения пользователь установили использование приложения Адресной книги. Удаленные изображения являются изображениями, сохраненными в сети. Удаленные изображения занимают время для загрузки, таким образом, предоставлен асинхронный API для выборки удаленных изображений.

Используйте beginLoadingImageDataForClient: метод, если файл образа не локален и Вы хотите выполнить асинхронную выборку. Вы передаете объект клиента, реализующий ABImageClient протокол как параметр этому методу. beginLoadingImageDataForClient: метод возвращает номер для отслеживания изображения. A consumeImageData:forTag: когда выборка сделана, сообщение отправляется в Ваш объект клиента. Реализуйте этот метод для обработки нового выбранного изображения. Используйте cancelLoadingImageDataForTag: метод класса, если Вы хотите отменить асинхронную выборку.

Используйте beginLoadingImageDataForClient: метод, если файл образа не локален и Вы хотите выполнить асинхронную выборку:

1. Передайте объект клиента, реализующий ABImageClient протокол как параметр этому методу.

2. beginLoadingImageDataForClient: метод возвращает номер для отслеживания изображения.

3. A consumeImageData:forTag: когда выборка сделана, сообщение отправляется в Ваш объект клиента. Реализуйте этот метод для обработки нового выбранного изображения.

4. Используйте cancelLoadingImageDataForTag: метод класса, если Вы хотите отменить асинхронную выборку.

Будучи локализованным имена для свойств и меток

Можно найти локализованное имя для любого из имен свойства по умолчанию и меток, перечисленных в Ссылке Констант Objective C Адресной книги. Функции ABLocalizedPropertyOrLabel и ABCopyLocalizedPropertyOrLabel возвращенный имя, локализующееся для выбранного языка пользователя.

Необходимо обработать локализацию имен для свойств и меток, которые Вы создаете; платформа Адресной книги не предоставляет определенной поддержки для этого.

Пример

Перечисление 1 является примером кода Objective C, получающим страну для основного адреса зарегистрированного пользователя. Если страна является пустой строкой, она устанавливает страну в США.

Перечисление 1  , Изменяющее адрес лица

ABPerson *aPerson = [[ABAddressBook sharedAddressBook] me];

ABMutableMultiValue *anAddressList =

    [[aPerson valueForProperty:kABAddressProperty] mutableCopy];

NSUInteger primaryIndex =

    [anAddressList indexForIdentifier:[anAddressList primaryIdentifier]];

NSMutableDictionary *anAddress =

    [[anAddressList valueAtIndex:primaryIndex] mutableCopy];

NSString *country =

    (NSString*) [anAddress objectForKey:kABAddressCountryKey];

if ([country isEqualToString:@""]) {

    [anAddress setObject:@"USA" forKey:kABAddressCountryKey];

    [anAddressList replaceValueAtIndex:primaryIndex withValue:anAddress];

    [aPerson setValue:anAddressList forProperty:kABAddressProperty];

    [[ABAddressBook sharedAddressBook] save];

}

Используя людей средство выбора

Средство выбора людей является представлением, обеспечивающим доступ к содержанию адресной книги пользователя из любого приложения. Это предлагает доступный для поиска, выбираемый список людей и групп, которые могут быть настроены для Вашего приложения.

Для использования людей средство выбора в приложении Какао перетащите его от палитры библиотеки в окно. Если Вы должны, можно создать экземпляр ABPeoplePickerView программно вместо этого. Существует два способа установить поведение людей представление средства выбора — от Интерфейсного Разработчика и программно.

Для установки поведения от Интерфейсного Разработчика откройте панель Get Info. Атрибуты, которые можно установить, включают, какие столбцы выведены на экран представлением, позволяются ли множественные выборы, позволяются ли выборы группы, и имя автосохранения для представления. Эти изменения сразу отражаются в Интерфейсном Разработчике. Используя функцию Test Interface Интерфейсного Разработчика, люди представление средства выбора выведет на экран адресную книгу зарегистрированного пользователя.

Для установки поведения программно создайте выход типа ABPeoplePickerView от Вашего контроллера и подключения это людям представление средства выбора. Тогда используйте надлежащие методы экземпляра изменить атрибуты средства выбора.

Для приложений Какао люди средство выбора также обеспечивает методы для использования данных автосохранения, так, чтобы это могло сохранить выборы фильтра и позиции столбцов. Используйте ABPeoplePickerView методы autosaveName и autosaveName.

Используя API C, люди средство выбора доступно только в форме окна и не может использоваться в качестве пользовательского представления. Это должно быть создано с ABPickerCreate и сделанный видимым с ABPickerSetVisibility, следующим образом:

ABPickerRef peoplePicker = ABPickerCreate();

ABPickerSetVisibility(peoplePicker, true);

Люди пример средства выбора

Код от этого примера должен быть помещен в контроллер окна для людей средство выбора. Разработчики, использующие API C, должны послать к ABPicker C Ссылку создать аналог для их приложений; большинство функций называют так же. Вместо того, чтобы использовать уведомления, необходимо будет зарегистрировать обработчики событий для обработки изменений в окне.

Следующее перечисление показывает, как можно установить атрибуты люди средство выбора программно. Этот код обычно является частью awakeFromNib метод. Все эти настройки также доступны в инспекторе атрибутов в Интерфейсном Разработчике.

    // Disallow multiple selections in the name list.

    [peoplePicker setAllowsMultipleSelection:NO];

    // Add the e-mail and telephone properties to the view.

    // By default, the people picker displays only the

    // Name column.

    [peoplePicker addProperty:kABEmailProperty];

    [peoplePicker addProperty:kABPhoneProperty];

Следующее перечисление показывает, как зарегистрироваться для уведомления, когда пользователь выбирает запись лица у людей средство выбора. Этот код обычно является частью awakeFromNib метод.

    NSNotificationCenter* center;

    center = [NSNotificationCenter defaultCenter];

    // Set up a responder for one of the four available notifications,

    // in this case to tell us when the selection in the people picker

    // has changed.

    [center addObserver:self

            selector:@selector(recordChanged:)

            name:ABPeoplePickerNameSelectionDidChangeNotification

            object:peoplePicker];

Следующее перечисление показывает пример того, как реагировать на пользователя, выбирающего запись лица у людей средство выбора:

- (void)recordChanged:(NSNotification*)notification {

    NSArray *array;

    NSImage *personImage;

    NSString *personFirstName;

    NSString *personLastName;

    array = [peoplePicker selectedRecords];

    NSAssert([array count] == 1,

             @"Picker returned multiple selected records");

    ABPerson *person = [array objectAtIndex:0];

    personImage = [[NSImage alloc] initWithData:[person imageData]];

    personFirstName = [person valueForProperty:kABFirstNameProperty],

    personLastName = [person valueForProperty:kABLastNameProperty];