Opening Your Help Book in Help Viewer
If you are providing contextually sensitive help, or if you have help books in addition to your primary application help book, you need to know how to access your help book using the Apple Help API.
When users choose an item from the Help menu, click a help button, or choose help from a contextual menu, your application must display the pertinent help book content in Help Viewer. To open your help book in Help Viewer, use one of the following NSHelpManager
methods:
openHelpAnchor:inBook:
opens a location in your help book identified by an anchor.findString:inBook:
searches your help book for a term or phrase.
NSHelpManager
methods are fully documented in NSHelpManager Class Reference.
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:
Calls the Core Foundation function
CFBundleGetMainBundle
to retrieve a reference to the application’s main bundle.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 theInfo.plist
file with the keyCFBundleHelpBookName
. 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.Checks that the value returned in step 2 was of type CFString.
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:
Calls
CFBundleGetMainBundle
to retrieve a reference to the application’s main bundle.Calls
CFBundleGetValueForInfoDictionaryKey
to retrieve the help book name associated with the application bundle.Calls
AHSearch
to search the help book for the string passed toMySearchHelpBook
in thetheQuery
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.
Arguments provided to AHGotoPage | Results |
---|---|
Help book name | Help Viewer opens the help book to its title page |
Help book name, relative path | Help Viewer opens the page at the given path in the help book |
Help book name, relative path, anchor name | Help Viewer opens the page at the path and scrolls to the section identified by the anchor |
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:
Calls the Core Foundation function
CFBundleGetMainBundle
to retrieve the application’s bundle.If
CFBundleGetMainBundle
cannot find the application’s main bundle, returns an error specifying that the file was not found.Calls the Core Foundation function
CFBundleGetValueForInfoDictionaryKey
to retrieve the name of the help book associated with the application’s main bundle.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 functionCFStringGetTypeID
returns the type ID of a CFString. If the type IDs do not match,MyGotoHelpPage
returns a parameter error.Calls the Apple Help function
AHGotoPage
to open the application’s help book to the page and anchor passed in as arguments to theMyGotoHelpPage
function. If thepagePath
andanchorName
arguments are bothNULL
,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); |
Copyright © 2003, 2013 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2013-01-28