Отображение расположения привязки

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

Если имя привязки появляется несколько раз в Вашей книге справки, Средство просмотра Справки выводит на экран все содержание, связанное с той привязкой в Вашей книге справки в таблице результатов поиска. Использовать AHLookupAnchor или openHelpAnchor:inBook:, необходимо индексировать книгу справки с включенной индексацией привязки.

Перечисление 4-1 показывает использующую функцию AHLookupAnchor найти и вывести на экран текст связались с привязкой к книге справки.

Перечисление 4-1  , Выводящее на экран расположение привязки

OSStatus MyGotoHelpAnchor( CFStringRef anchorName)

{

    CFBundleRef myApplicationBundle = NULL;

    CFTypeRef myBookName = NULL;

    OSStatus err = noErr;

    myApplicationBundle = CFBundleGetMainBundle();// 1

    if (myApplicationBundle == NULL) {err = fnfErr; goto bail;}

    myBookName = CFBundleGetValueForInfoDictionaryKey(// 2

                    myApplicationBundle,

                    CFSTR("CFBundleHelpBookName"));

    if (myBookName == NULL) {err = fnfErr; goto bail;}

    if (CFGetTypeID(myBookName) != CFStringGetTypeID()) {// 3

        err = paramErr;

    }

    if (err == noErr) err = AHLookupAnchor (myBookName, anchorName);// 4

    return err;

Bail:

    return err;

}

Вот то, что делает функция в Перечислении 4-1:

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

2. Вызывает Базовую функцию Основы CFBundleGetValueForInfoDictionaryKey найти имя книги справки приложения. При регистрации книги справки Вы храните свое имя книги справки в Info.plist файл с ключом CFBundleHelpBookName. Вместо твердого кода Ваше название книги справки — который может измениться, поскольку содержание книги справки обновляется — в Вашем приложении, используйте Базовые функции Основы для получения названия книги справки от файла списка свойств.

3. Чеки, которые значение возвратило на шаге 2, имели тип CFString.

4. Вызывает функцию Справки Apple AHLookupAnchor искать привязку в книге справки приложения.

Вот пример того, как Вы могли вызвать MyGotoHelpAnchor функция описана в Перечислении 4-1:

err = MyGotoHelpAnchor(CFSTR("surfing"));

Поиск книги справки

Справка Apple также предлагает способ для Вас отправить Средству просмотра Справки поисковый запрос для выполнения на книге справки. Используя AHSearch функционируйте или findString:inBook: метод, можно искать книгу справки срок или фразу. Например, если Вы реализуете контекстуально чувствительную справку для элемента пользовательского интерфейса, на который ссылаются в многочисленных страницах справки, можно вызвать findString:inBook: найти и вывести на экран те страницы в таблице результатов поиска. Перечисление 4-2 показывает функцию, ищущую Вашу книгу справки критерий поиска или запрос с помощью AHSearch функция.

Перечисление 4-2  функция, ищущая Вашу книгу справки

OSStatus MySearchHelpBook(CFStringRef theQuery)

{

    CFBundleRef myApplicationBundle = NULL;

    CFStringRef myBookName = NULL;

    OSStatus err = noErr;

    myApplicationBundle = CFBundleGetMainBundle();// 1

    if (myApplicationBundle != NULL) {

        myBookName = CFBundleGetValueForInfoDictionaryKey(// 2

                        myApplicationBundle,

                        CFSTR("CFBundleHelpBookName"));

    } else err = fnfErr;

    if (myBookName != NULL) {

            err = AHSearch(myBookName, theQuery);// 3

    } else err = fnfErr;

    return err;

}

Вот то, что делает функция в Перечислении 4-2:

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

2. Вызовы CFBundleGetValueForInfoDictionaryKey получать название книги справки связалось с комплектом приложений.

3. Вызовы AHSearch искать книгу справки строку передало MySearchHelpBook в theQuery параметр.

Вот пример того, как Вы могли вызвать функцию, которая, как показывают в Перечислении 4-2, искала Вашу книгу справки информацию о печати. Можно использовать фразу для запроса, такого как “печать документ”, или можно искать срок, такой как «печать».

err = SearchHelpBook(CFSTR("print a document"));

err = SearchHelpBook(CFSTR("print"));

Загрузка страницы книги справки

Функция Справки Apple AHGotoPage позволяет Вам открывать страницу книги справки в известном расположении и отображать его в Средстве просмотра Справки. Если Вы знаете путь к информации, Вы хотите вывести на экран, или если Вы просто хотите открыть свою книгу справки для ее титульного листа, можно использовать AHGotoPage.

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

Таблица 4-1 показывает параметры, которым можно передать AHGotoPage и что Средство просмотра Справки выводит на экран в ответ.

Функция, показанная в Перечислении 4-3, берет путь и имя привязки как параметры и вызовы AHGotoPage для открытия справки бронируют страницу в Средстве просмотра Справки.

Перечисление 4-3  функция, загружающая страницу книги справки

OSStatus MyGotoHelpPage (CFStringRef pagePath, CFStringRef anchorName)

{

    CFBundleRef myApplicationBundle = NULL;

    CFStringRef myBookName = NULL;

    OSStatus err = noErr;

    myApplicationBundle = CFBundleGetMainBundle();// 1

    if (myApplicationBundle == NULL) {err = fnfErr; goto bail;}// 2

    myBookName = CFBundleGetValueForInfoDictionaryKey(// 3

                    myApplicationBundle,

                    CFSTR("CFBundleHelpBookName"));

    if (myBookName == NULL) {err = fnfErr; goto bail;}

    if (CFGetTypeID(myBookName) != CFStringGetTypeID()) {// 4

        err = paramErr;

    }

    if (err == noErr) err = AHGotoPage (myBookName, pagePath, anchorName);// 5

    return err;

}

Вот то, что делает код:

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

2. Если CFBundleGetMainBundle не может найти основной пакет приложения, возвращает ошибку при указании, что не был найден файл.

3. Вызывает Базовую функцию Основы CFBundleGetValueForInfoDictionaryKey получать имя книги справки связалось с основным пакетом приложения.

4. Чеки, которые значение возвратило на шаге 3, имеют тип CFString. Базовая функция Основы CFGetTypeID возвращается идентификатор типа значения возвратился на шаге 3; функция CFStringGetTypeID возвращает идентификатор типа CFString. Если идентификаторы типов не соответствуют, MyGotoHelpPage возвращает ошибку параметра.

5. Вызывает функцию Справки Apple AHGotoPage открыть книгу справки приложения для страницы и привязки передало в как параметры MyGotoHelpPage функция. Если pagePath и anchorName параметры - оба NULL, AHGotoPage открывает книгу справки приложения для ее титульного листа.

Вот три примера того, как Вы могли вызвать MyGotoHelpPage функция описана в Перечислении 4-3:

err = MyGotoHelpPage(CFSTR("pages/howto.html"), CFSTR("surfing"));

err = MyGotoHelpPage(CFSTR("pages/howto.html"), NULL);

err = MyGotoHelpPage(NULL, NULL);