Displaying an Anchor Location

If you specify anchor locations in your help book, as described in Indexing Your Help Book, you can use the Apple Help function AHLookupAnchor or the NSHelpManager method openHelpAnchor:inBook: to find and display help content by anchor name. AHLookupAnchor and openHelpAnchor:inBook: allow you to search for a particular help topic without knowing the path to the page that it is on. If you are implementing contextually sensitive help, you can load it by anchor, without having to track the path to every help page you may access.

If an anchor name appears more than once in your help book, Help Viewer displays all of the content associated with that anchor in your help book in a search results table. To use AHLookupAnchor or openHelpAnchor:inBook:, you must index your help book with anchor indexing turned on.

Listing 4-1 shows a function that uses AHLookupAnchor to find and display the text associated with a help book anchor.

Listing 4-1  Displaying an anchor location

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;

}

Here is what the function in Listing 4-1 does:

1. Calls the Core Foundation function CFBundleGetMainBundle to retrieve a reference to the application’s main bundle.

2. Calls the Core Foundation function CFBundleGetValueForInfoDictionaryKey to find the name of the application’s help book. When you register your help book, you store your help book’s name in the Info.plist file with the key CFBundleHelpBookName. Rather than hard code your help book name—which can change as the help book content is updated—in your application, use Core Foundation functions to retrieve the help book name from the property list file.

3. Checks that the value returned in step 2 was of type CFString.

4. Calls the Apple Help function AHLookupAnchor to look up the anchor in the application’s help book.

Here is an example of how you could call the MyGotoHelpAnchor function described in Listing 4-1:

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

Searching Your Help Book

Apple Help also offers a way for you to send Help Viewer a search query to execute on your help book. Using the AHSearch function or the findString:inBook: method, you can search your help book for a term or phrase. For example, if you are implementing contextually sensitive help for a user interface element that is referenced in numerous help pages, you can call findString:inBook: to find and display those pages in a search results table. Listing 4-2 shows a function that searches your help book for a search term or query using the AHSearch function.

Listing 4-2  A function that searches your help book

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;

}

Here is what the function in Listing 4-2 does:

1. Calls CFBundleGetMainBundle to retrieve a reference to the application’s main bundle.

2. Calls CFBundleGetValueForInfoDictionaryKey to retrieve the help book name associated with the application bundle.

3. Calls AHSearch to search the help book for the string passed to MySearchHelpBook in the theQuery parameter.

Here is an example of how you could call the function shown in Listing 4-2 to search your help book for information on printing. You can use a phrase for your query, such as “print a document” or you can search for a term, such as “print”.

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

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

Loading a Help Book Page

The Apple Help function AHGotoPage allows you to open a help book page at a known location and display it in Help Viewer. If you know the path to the information you want to display, or if you simply wish to open your help book to its title page, you can use AHGotoPage.

You specify the location of the page using a combination of a relative path and the help book name. Relative paths should be specified relative to the help book’s folder. In addition, you can specify an anchor within the given help page; when you specify an anchor, Help Viewer scrolls directly to the location of that anchor on the help page before displaying the page.

Table 4-1 shows the arguments you can pass to AHGotoPage and what Help Viewer displays in response.

The function shown in Listing 4-3 takes a path and an anchor name as arguments and calls AHGotoPage to open a help book page in Help Viewer.

Listing 4-3  A function that loads a help book page

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;

}

Here is what the code does:

1. Calls the Core Foundation function CFBundleGetMainBundle to retrieve the application’s bundle.

2. If CFBundleGetMainBundle cannot find the application’s main bundle, returns an error specifying that the file was not found.

3. Calls the Core Foundation function CFBundleGetValueForInfoDictionaryKey to retrieve the name of the help book associated with the application’s main bundle.

4. Checks that the value returned in step 3 is of type CFString. The Core Foundation function CFGetTypeID returns the type ID of the value returned in step 3; the function CFStringGetTypeID returns the type ID of a CFString. If the type IDs do not match, MyGotoHelpPage returns a parameter error.

5. Calls the Apple Help function AHGotoPage to open the application’s help book to the page and anchor passed in as arguments to the MyGotoHelpPage function. If the pagePath and anchorName arguments are both NULL, AHGotoPage opens the application’s help book to its title page.

Here are three examples of how you could call the MyGotoHelpPage function described in Listing 4-3:

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

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

err = MyGotoHelpPage(NULL, NULL);