---

Apple Help Reference

Overview

Apple Help is an update and enhancement to previous versions of the Mac OS help system. It is available in Mac OS 8.6 and later, including Mac OS X.

This reference describes the application programming interface (API) for registering help books and calling the Help Viewer application.

Functions

AHGotoPage

Tells the Help Viewer to load the specified HTML page.

OSStatus AHGotoPage (
   CFStringRef bookname,
   CFStringRef path,
   CFStringRef anchor
);

Parameters

bookname

A string specifying the name of the help book that contains the page to be loaded. If the name of the help book (as specified by the AppleTitle meta tag) is SurfWriter Help, for example, you pass a string containing the value SurfWriter Help. You may pass NULL in this parameter.

path

A string specifying a path for the page to be loaded. Specify the path relative to the help book given in the bookname parameter. If you pass NULL in this parameter, the Help Viewer opens to your help book’s title page. If you pass NULL in the bookname parameter, you must specify the value passed in the path parameter as a full URL in the form file://.

anchor

An optional string specifying an anchor to which the Help Viewer scrolls after loading the specified page. If you do not specify an anchor, the Help Viewer scrolls to the top of the page.

Return Value

A result code. See “Apple Help Result Codes.”

Discussion

This function is synchronous. Calling this function opens the Help Viewer application, if required, and loads the specified HTML page.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

AppleHelp.h

AHLookupAnchor

Tells the Help Viewer to search for a specified anchor and load it.

OSStatus AHLookupAnchor (
   CFStringRef bookname,
   CFStringRef anchor
);

Parameters

bookname

A string specifying the name of the help book to search for the desired anchor. If the name of the help book (as specified by the AppleTitle meta tag) is SurfWriter Help, for example, you pass a string containing the value SurfWriter Help. If you do not specify a value in this parameter, the Help Viewer searches all available help books for the specified anchor.

anchor

A string specifying an anchor to load. You should ensure that each anchor name in your help book is unique. If you specify an anchor name that is not unique, the Help Viewer displays a list of links to all the anchors with that name.

Return Value

A result code. See “Apple Help Result Codes.”

Discussion

This function is synchronous. Calling this function opens the Help Viewer application, if required, and loads the specified anchor or the list of links to multiple anchors, as appropriate. You must specify anchor indexing when you index your help book to perform anchor lookup.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

AppleHelp.h

AHRegisterHelpBook

Registers a help book.

OSStatus AHRegisterHelpBook (
   const FSRef *appBundleRef
);

Parameters

appBundleRef

A file system reference for the bundle containing the help book you wish to register.

Return Value

A result code. See “Apple Help Result Codes.”

Discussion

Carbon applications must call this function in order to register a help book. If your Cocoa application provides appropriate key/value pairs specifying a single help book in your application’s property list, as described in Providing User Assistance with Apple Help, you only need to call AHRegisterHelpBook if you wish to call the Apple Help functions to access your help content yourself. If you install an additional help book that is not described in your property list, you must call the AHRegisterHelpBook function in order to have the new book appear in the Help Center. If you call this function and specify a help book that is already registered, the AHRegisterHelpBook function returns a result of noErr.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

AppleHelp.h

AHSearch

Tells the Help Viewer to search for a specified string in a given help book.

OSStatus AHSearch (
   CFStringRef bookname,
   CFStringRef query
);

Parameters

bookname

A string specifying the name of the help book to be searched. If the name of the help book (as specified by the AppleTitle meta tag) is SurfWriter Help, for example, you pass a string containing the value SurfWriter Help. If you pass NULL in this parameter, the Help Viewer searches all available help books.

query

A string containing the text to search for.

Return Value

A result code. See “Apple Help Result Codes.”

Discussion

This function is synchronous. Calling this function opens the Help Viewer application, if required, and displays the results of the search.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

AppleHelp.h

Constants

TOC Specification Constants

Passed to the AHGotoMainTOC function to identify the table of contents page to open.

typedef SInt16 AHTOCType;
enum {
   kAHTOCTypeUser = 0,
   kAHTOCTypeDeveloper = 1
};

Constants

kAHTOCTypeUser

Opens the Help Center.

Available in Mac OS X v10.0 and later.

Declared in AppleHelp.h.

kAHTOCTypeDeveloper

Opens the Developer Help Center.

Available in Mac OS X v10.0 and later.

Declared in AppleHelp.h.

Result Codes

The most common result codes returned by Apple Help are listed below.

---