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 Project Builder 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, click on the Targets tab. In the left column, your project’s targets appear.

2. Select the target for which you want to edit the Info.plist file. You should see a window such as that shown in Figure 3-2.

   

3. Under Info.plist Entries, select the Expert View item. You should see a pane similar to that shown in Figure 3-3.

   

4. Click the New Sibling button to create a new key-value pair. Type CFBundleHelpBookFolder for the new item’s key.

5. Double-click in the Value column to edit the value associated with the key. Type the name of the folder containing your application’s main help book. For example, Figure 3-4 shows entry for the SurfWriter application’ s help book folder.

   

6. Click the New Sibling button to create another key-value pair. Type CFBundleHelpBookName for the key. Enter the name of your main help book, as it appears in the title page.

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

Carbon applications and Cocoa or Java 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.