Регистрация книги справки

В этой главе описываются, как удостовериться, что Ваша завершенная книга справки регистрируется так, чтобы пользователи — и Ваше приложение — могли получить доступ к нему. Когда книга справки была зарегистрирована, это становится доступным из меню Library и из приложения Меню справки. Если книга справки перечислена в приложении Info.plist когда пользователь выбирает справку приложения из Меню справки или из кнопки справки, файл, это регистрируется автоматически. Можно также зарегистрировать книгу справки путем вызова AHRegisterHelpBook функция во время запуска приложения. При создании инструмента или приложения для OS X необходимо считать эту главу, чтобы изучить, как добавить книгу справки к программному продукту.

Куда поместить Вашу папку книги справки

Начиная с OS X v10.6, книги справки помещаются непосредственно в Ресурсах приложения / папка (см. Организацию Пакета Книги Справки).

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

Можно использовать следующую процедуру для установки папки справки в Resources папка с помощью XCode:

  1. В основном окне проекта выберите Resources в области Groups & Files.

  2. Из Меню действий выберите Add> Existing files (Figure 3-1).

    Рисунок 3-1  , Добавляющий файлы справки в XCode
    Adding help files in Xcode

  3. Выберите пакет справки в Добавить диалоговом окне Файлов и нажмите Add.

  4. Установите переключатель «Create Folder References for any added folders» и нажмите Add (Figure 3-2).

      Ссылки папки Create рисунка 3-2 в XCode
    Creating folder references in Xcode

Как зарегистрировать Вашу книгу справки

Для Какао и JAVA-приложений, можно использовать в своих интересах автоматическую регистрацию книги справки путем добавления названия книги справки и расположения к информационному списку свойств (Info.plist) файл. Для приложений Углерода необходимо предпринять дополнительный шаг вызывания регистрационной функции Справки Apple, AHRegisterHelpBook.

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

Какао и JAVA-приложения, использующие Справку Apple API для доступа к их содержанию книги справки, должны также вызвать AHRegisterHelpBook функция прежде, чем сделать любые звонки к другим функциям Справки Apple.

Редактирование информационного файла списка свойств

Для регистрации книги справки необходимо включать CFBundleHelpBookFolder и CFBundleHelpBookName ключи в Вашем Info.plist файл. CFBundleHelpBookFolder ключ идентифицирует папку книги справки; значение, связанное с этим ключом, должно быть строкой, указывающей имя папки. Например, вот то, как Вы ввели бы имя папки книги справки SurfWriter:

<key>CFBundleHelpBookFolder</key>
<string>SurfWriter.Help</string>

CFBundleHelpBookName ключ идентифицирует книгу справки. Значение, связанное с этим ключом, должно быть строкой, указывающей заголовок книги справки, как определено AppleTitle тег в титульном листе книги. Например, вот то, как Вы ввели бы заголовок книги SurfWriter Help:

<key>CFBundleHelpBookName</key>
<string>com.mycompany.surfwriter.help</string>

При использовании XCode для разработки программного продукта, можно добавить эти ключи к Вашему Info.plist файл со следующими шагами:

  1. Из основного окна проекта выберите имя проекта в области Groups & Files.

  2. Выберите Info.plist файл в правильной области

  3. Добавьте папку книги справки и помогите ключам названия книги к Info.plist файл, как показано на рисунке 3-3.

    Рисунок 3-3  Редактируя info.plist файл в XCode
    The Expert settings in the Targets pane of Project Builder

Для OS X v10.6 и позже, оба CFBundleHelpBookName и CFBundleHelpBookFolder значениями должен быть Нсстрингс. Начиная с OS X v10.6, Name ключ не должен быть локализован.

Обратите внимание на то, что Ваш Info.plist файл должен также содержать допустимое CFBundleIdentifier запись. Для получения дополнительной информации об упаковке приложения и списках свойств, см. Руководство по программированию Пакета.

Используя регистрационную функцию справки Apple

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

Перечисление 3-1 показывает пример того, как зарегистрировать использование книги справки AHRegisterHelpBookWithURL.

Перечисление 3-1  , Регистрирующее справку, бронирует с AHRegisterHelpBookWithURL

OSStatus RegisterMyHelpBook(void)
{
    CFBundleRef myApplicationBundle;
    CFURLRef myBundleURL;
    OSStatus err = noErr;
 
    myApplicationBundle = NULL;
    myBundleURL = NULL;
 
    myApplicationBundle = CFBundleGetMainBundle();// 1
    if (myApplicationBundle == NULL) {err = fnfErr; goto bail;}
 
    myBundleURL = CFBundleCopyBundleURL(myApplicationBundle);// 2
    if (myBundleURL == NULL) {err = fnfErr; goto bail;}
 
    if (err == noErr) err = AHRegisterHelpBookWithURL(myBundleURL);// 3
    return err;
 
}

Вот то, что делает код в Перечислении 3-1:

  1. Вызывает Базовую функцию Основы CFBundleGetMainBundle получать ссылку на основной пакет приложения.

  2. Вызывает Базовую функцию Основы CFBundleCopyBundleURL получить путь к комплекту приложений.

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