NSHelpManager Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Declared in
NSHelpManager.h
Related sample code

Overview

The NSHelpManager class provides an approach to displaying online help. An application contains one NSHelpManager object.

Tasks

Getting the Help Manager

Displaying Help

Dynamically Adding Help Books

Configuring Context-Sensitive Help

Displaying Context-Sensitive Help

Class Methods

isContextHelpModeActive

Indicates whether context-sensitive help mode is active.

+ (BOOL)isContextHelpModeActive
Return Value

YES when the application is in context-sensitive help mode, NO otherwise.

Discussion

In context-sensitive help mode, when a user clicks a user interface item, help for that item is displayed in a small window just below the cursor.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSHelpManager.h

setContextHelpModeActive:

Specifies whether context-sensitive help mode is active.

+ (void)setContextHelpModeActive:(BOOL)contextHelpActive
Parameters
contextHelpActive

YES turns on context-sensitive help, NO turns it off.

Discussion

You never send this message directly; instead, the NSApplication method activateContextHelpMode: activates context-sensitive help mode, and the first mouse click after displaying the context-sensitive help window deactivates it.

When the application enters context-sensitive help mode, the help manager posts an NSContextHelpModeDidActivateNotification to the default notification center. When the application returns to normal operation, the help manager posts an NSContextHelpModeDidDeactivateNotification.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSHelpManager.h

sharedHelpManager

Returns the shared NSHelpManager instance, creating it if it does not already exist.

+ (NSHelpManager *)sharedHelpManager
Return Value

Shared help manager.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSHelpManager.h

Instance Methods

contextHelpForObject:

Returns context-sensitive help for an object.

- (NSAttributedString *)contextHelpForObject:(id)object
Parameters
object

Object for which context-sensitive help is sought.

Return Value

Context-sensitive help content.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSHelpManager.h

findString:inBook:

Performs a search for the specified string in the specified book.

- (void)findString:(NSString *)query inBook:(NSString *)book
Parameters
query

String to search for.

book

Localized help book to search. When nil, all installed help books are searched.

Discussion

To search for a string in your bundle’s localized help book, you could use code similar to the following:

NSString *locBookName = [[NSBundle mainBundle] objectForInfoDictionaryKey: @"CFBundleHelpBookName"];
[[NSHelpManager sharedHelpManager] findString:@"Hello"  inBook:locBookName];

This is a wrapper for AHRegisterHelpBook (which is called only once to register the help book specified in the application's main bundle) and AHSearch.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSHelpManager.h

openHelpAnchor:inBook:

Finds and displays the text at the given anchor location in the given book.

- (void)openHelpAnchor:(NSString *)anchor inBook:(NSString *)book
Parameters
anchor

Location of the desired text.

book

Help book containing the anchor. When nil, all installed help books are searched.

Discussion

To open an anchor in your bundle’s localized help book, you could use code similar to the following:

NSString *locBookName = [[NSBundle mainBundle] objectForInfoDictionaryKey: @"CFBundleHelpBookName"];
[[NSHelpManager sharedHelpManager] openHelpAnchor:@"anchor1"  inBook:locBookName];

This method is a wrapper for AHRegisterHelpBook (which is called only once to register the help book specified in the application's main bundle) and AHLookupAnchor.

Availability
  • Available in OS X v10.3 and later.
Related Sample Code
Declared In
NSHelpManager.h

registerBooksInBundle:

Registers one or more help books in the given bundle.

- (BOOL)registerBooksInBundle:(NSBundle *)bundle
Parameters
bundle

The bundle for additional help books. Books in the main bundle are automatically registered.

Return Value

YES if registration is successful, NO if if the bundle doesn't contain any help books or if registration fails.

Discussion

You use registerBooksInBundle: to register help books in, for example, a plug-in bundle. The Info.plist in the bundle should contain a help book directory path, which specifies one or more folders containing help books.

The main bundle is automatically registered by openHelpAnchor:inBook: and findString:inBook: .

Availability
  • Available in OS X v10.6 and later.
Declared In
NSHelpManager.h

removeContextHelpForObject:

Removes the association between an object and its context-sensitive help.

- (void)removeContextHelpForObject:(id)object
Parameters
object

Object to disassociate from its help content.

Discussion

If object does not have context-sensitive help associated with it, this method does nothing.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSHelpManager.h

setContextHelp:forObject:

Associates help content with an object.

- (void)setContextHelp:(NSAttributedString *)help forObject:(id)object
Parameters
help

Help content to associate with object.

object

Object to associate with help.

Discussion

When the application enters context-sensitive help mode, if object is clicked, help appears in the context-sensitive help window.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSHelpManager.h

showContextHelpForObject:locationHint:

Displays the context-sensitive help for a given object at or near the point on the screen specified by a given point.

- (BOOL)showContextHelpForObject:(id)object locationHint:(NSPoint)point
Parameters
object

Object for which context-sensitive help is sought.

point

Screen location at which to display the help content; it’s usually under the cursor.

Return Value

YES when help content is successfully displayed. NO if help content is not displayed (for example, when there is no context-sensitive help associated with object).

Availability
  • Available in OS X v10.0 and later.
Declared In
NSHelpManager.h

Notifications

NSContextHelpModeDidActivateNotification

Posted when the application enters context-sensitive help mode. This typically happens when the user holds down the Help key.

The notification object is the help manager. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSHelpManager.h

NSContextHelpModeDidDeactivateNotification

Posted when the application exits context-sensitive help mode. This happens when the user clicks the mouse button while the cursor is anywhere on the screen after displaying a context-sensitive help topic.

The notification object is the help manager. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSHelpManager.h