Next Page > Hide TOC

NSHelpManager Class Reference

Overview

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

Tasks

Getting the Help Manager

• + sharedHelpManager

Displaying Help

• – findString:inBook:
• – openHelpAnchor:inBook:

Configuring Context-Sensitive Help

• + isContextHelpModeActive
• + setContextHelpModeActive:
• – setContextHelp:forObject:
• – removeContextHelpForObject:

Displaying Context-Sensitive Help

• – contextHelpForObject:
• – showContextHelpForObject:locationHint:

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 Mac OS X v10.0 and later.

See Also

• + setContextHelpModeActive:

Declared In

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 Mac OS X v10.0 and later.

See Also

• + isContextHelpModeActive

Declared In

sharedHelpManager

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

+ (NSHelpManager *)sharedHelpManager

Return Value

Shared help manager.

Availability

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

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setContextHelp:forObject:
• – showContextHelpForObject:locationHint:

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setContextHelp:forObject:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – removeContextHelpForObject:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – contextHelpForObject:

Declared In

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

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

Declared In

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

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

Declared In

Next Page > Hide TOC