Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

How to Register Your Help Book

For Cocoa and Java applications, you can take advantage of automatic help book registration by adding the help book name and location to your information property list (Info.plist) file. For Carbon applications, you must take the additional step of calling the Apple Help registration function, AHRegisterHelpBook.

You must register your help book to get the automatic help book support provided by the system. When you register your help book, the system creates a Help menu for your application, populates it with an application help item, and opens your help book when a user chooses this item. In addition, your help book must be registered for it to appear in the Library menu.

Cocoa and Java applications that use the Apple Help API to access their help book content must also call the AHRegisterHelpBook function before making any calls to other Apple Help functions.

In this section:

Editing the Information Property List File
Using the Apple Help Registration Function

Editing the Information Property List File

To register a help book, you need to include the CFBundleHelpBookFolder and CFBundleHelpBookName keys in your Info.plist file. The CFBundleHelpBookFolder key identifies the help book folder; the value associated with this key should be a string specifying the folder name. For example, here is how you would enter the name of the SurfWriter help book folder:

<key>CFBundleHelpBookFolder</key>

<string>SurfWriter Help</string>

The CFBundleHelpBookName key identifies the help book. The value associated with this key should be a string specifying the help book title, as defined by the AppleTitle tag in the title page of the book. For example, here is how you would enter the title of the SurfWriter Help book:

<key>CFBundleHelpBookName</key>

<string>SurfWriter Help</string>

If you are using Xcode to develop your software product, you can add these keys to your Info.plist file with the following steps:

1. From the main project window, select the name of the project in the Groups & Files pane.

2. Select the Info.plist file in the right pane

3. Add the help book folder and help book name keys to the Info.plist file, as shown in Figure 3-4.

   
   

   Figure 3-4  Editing the info.plist file in Xcode

   

If you have more than one help book, you can set the value of each of the CFBundleHelpBookName and CFBundleHelpBookFolder keys to an array of strings. However, if you use an array for the value of these two keys, you do not get automatic support for your application help item in the Help menu.

Note that your Info.plist file must also contain a valid CFBundleIdentifier entry. For more information on application packaging and property lists, see Bundle Programming Guide.

Using the Apple Help Registration Function

Applications that call Apple Help functions must first call the Apple Help function AHRegisterHelpBook to register their help book. You would typically do this during application initialization. Once your application has called AHRegisterHelpBook, your help content is accessible through the use of the Apple Help functions.

Listing 3-1 shows an example of how to register a help book using AHRegisterHelpBook.

Listing 3-1  Registering a help book with AHRegisterHelpBook

OSStatus RegisterMyHelpBook(void)

{

    CFBundleRef myApplicationBundle;

    CFURLRef myBundleURL;

    FSRef myBundleRef;

    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 (!CFURLGetFSRef(myBundleURL, &myBundleRef)) err = fnfErr;// 3

    if (err == noErr) err = AHRegisterHelpBook(&myBundleRef);// 4

    return err;

}

Here is what the code in Listing 3-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 CFBundleCopyBundleURL to get the path to the application bundle.

3. Calls the Core Foundation function CFURLGetFSRef to convert the path obtained in Step 2 into a file system reference (an FSRef structure).

4. Calls AHRegisterHelpBook, passing the file system reference obtained in the last step. Apple Help finds the help book located in the bundle and caches the name and location of the help book. Apple Help chooses which localized version of the help book to use based upon the current language of the system.

< Previous PageNext Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice