Mac Developer Library

Developer

Carbon Framework Reference Apple Help Reference

Options
Deployment Target:

On This Page
Language:

Apple Help Reference

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 OS X.

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

Functions

  • Registers a help book.

    Declaration

    Swift

    func AHRegisterHelpBook(_ appBundleRef: UnsafePointer<FSRef>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func AHSearch(_ bookname: CFString!, _ query: CFString!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Tells the Help Viewer to load the specified main table-of-contents page.

    Deprecation Statement

    Use AHGotoPage to jump to different books or anchors.

    Declaration

    Objective-C

    OSStatus AHGotoMainTOC ( AHTOCType toctype );

    Parameters

    toctype

    A value specifying which Help Center page should be loaded. If you pass the kAHTOCTypeUser constant, for example, the Help Viewer loads the Help Center 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 Help Center page.

    Import Statement

    Objective-C

    @import Carbon;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.4.

  • Tells the Help Viewer to load the specified HTML page.

    Declaration

    Swift

    func AHGotoPage(_ bookname: CFString!, _ path: CFString!, _ anchor: CFString!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func AHLookupAnchor(_ bookname: CFString!, _ anchor: CFString!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.0 and later.

Constants

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

    Declaration

    Swift

    typealias AHTOCType = Int16

    Objective-C

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

    Constants

    • kAHTOCTypeUser

      kAHTOCTypeUser

      Opens the Help Center.

      Available in OS X v10.0 and later.

    • kAHTOCTypeDeveloper

      kAHTOCTypeDeveloper

      Opens the Developer Help Center.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import Carbon;

    Swift

    import Carbon

    Availability

    Available in OS X v10.0 and later.

Result Codes

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

  • The requested operation could not be completed.

    Value

    -10790

    Description

    The requested operation could not be completed.

    Available in OS X v10.0 and later.

  • There was an error while attempting to read Internet Config settings.

    Value

    -10791

    Description

    There was an error while attempting to read Internet Config settings.

    Available in OS X v10.0 and later.