Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java

Table of Contents

NSHelpManager


Inherits from:
NSObject
Package:
com.apple.yellow.application


Class Description


NSHelpManager provides an approach to displaying on-line help. An application contains one instance of NSHelpManager. Your application's code rarely needs to access NSHelpManager directly. Instead, you use Interface Builder and Project Builder to set up on-line help for your application.


Context Help


Context-sensitive help (also referred to as context help) gives the user a small amount of information when they help-click an interface item. For example, if the user help-clicks a menu item called "Copy," they should get context help that says something like "Copies the currently selected text to the pasteboard." This text appears in a small window near where the user help-clicked, and the window disappears when the user clicks anywhere else in the application.

Help-clicking is performed in any one of several ways, depending on the hardware used. Help-clicking is performed when the user holds down the Help key, the F1 key, or the Alternate and Control keys while pressing the mouse button.

To provide context-sensitive help for your application, follow these steps:

  1. For each interface item that needs context help, create an RTF or RTFD file containing the text and any images you want to appear when the user help-clicks that interface item. Try to keep the text as brief as possible and the images as small as possible.The text you write will appear in a small window just under the cursor when the user help-clicks an interface item. If the user help-clicks near the edge of the screen, text may appear off-screen. (This is especially prevalent when the user help-clicks a menu item.) Use hard returns in your text so the window will be as narrow as possible.
  2. If you don't need to localize your context help files, in Project Builder simply add these files to your project under Context Help.If you do need to localize your context help files, first copy the files into the appropriate .lproj directory of your project, then add them to the project.
  3. In Interface Builder, connect each interface item to its context help file by doing the following:
    1. Bring up the Interface Builder inspector and choose the Help display. The Help display lists all the context help files associated with your application. (You may have to quit and restart Interface Builder to get this to occur.)
    2. Select an interface item.
    3. In the Inspector, choose the appropriate help file.

When you build your application, /usr/bin/compileHelp packages your help files into a property list named Help.plist. NSHelpManager knows how to extract context help from a Help.plist file.


Comprehensive Help


Most applications provide some form of on-line help that is more comprehensive and detailed than context-sensitive help, such as conceptual or task help. NSHelpManager allows you to provide this sort of comprehensive help in any way you choose. Some help authors prefer to provide comprehensive help in HTML using a World-Wide Web browser; others use tools such as Digital Librarian or Concurrence.

When the user chooses the Help menu item, the NSApplication method showHelp is invoked. This method simply asks NSWorkspace to open the help file you have specified for your application. That file should be the starting point of your help, and should allow users to access whatever information they might need.

To specify a help file for your application, do one of the following:

It's possible for applications to have more than one command under the Help menu and to have each command open a different help file. To implement this, connect each of the Help menu commands to a different action method. The action methods should send openFile to the shared NSWorkspace object to open the appropriate help file.




Method Types


Constructors
NSHelpManager
Creating an NSHelpManager instance
sharedHelpManager
Getting and setting context help mode
setContextHelpModeActive
isContextHelpModeActive
Returning context-sensitive help
contextHelpForObject
showContextHelpForObject
Setting up context-sensitive help
setContextHelp
removeContextHelpForObject


Constructors



NSHelpManager

public NSHelpManager()

Description forthcoming.


Static Methods



isContextHelpModeActive

public static boolean isContextHelpModeActive()

Returns true if the application is currently in context-sensitive help mode, false otherwise. 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.

See Also: setContextHelpModeActive



setContextHelpModeActive

public static void setContextHelpModeActive(boolean flag)

Controls context-sensitive help mode. If flag is true, the application enters context-sensitive help mode. If flag is false, the application returns to normal operation.

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, NSHelpManager posts a ContextHelpModeDidActivateNotification to the default notification center. When the application returns to normal operation, NSHelpManager posts a ContextHelpModeDidDeactivateNotification.

See Also: isContextHelpModeActive



sharedHelpManager

public static NSHelpManager sharedHelpManager()

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


Instance Methods



contextHelpForObject

public NSAttributedString contextHelpForObject(Object object)

Returns context-sensitive help for object.

See Also: setContextHelp, showContextHelpForObject



removeContextHelpForObject

public void removeContextHelpForObject(Object object)

Removes the association between object and its context-sensitive help. If object does not have context-sensitive help associated with it, this method does nothing. Typically, you use Interface Builder to remove context-sensitive help from an item.

See Also: setContextHelp



setContextHelp

public void setContextHelpForObject( NSAttributedString help, Object object)

Associates help with object. When the application enters context-sensitive help mode, if object is clicked, help will appear in the context-sensitive help window. Typically, you use Interface Builder to associate context-sensitive help with an object.

See Also: removeContextHelpForObject



showContextHelpForObject

public boolean showContextHelpForObject( Object object, NSPoint point)

Displays the context-sensitive help for object at or near the point on the screen specified by point. This point is usually just under the cursor. Returns true if it successfully displays context-sensitive help for the object, false if it cannot (for example, if there is no context-sensitive help associated with this object).

See Also: contextHelpForObject




Notifications


ContextHelpModeDidActivateNotification

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

This notification contains a notification object but no userInfo dictionary. The notification object is the NSHelpManager object.

ContextHelpModeDidDeactivateNotification

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

This notification contains a notification object but no userInfo dictionary. The notification object is the NSHelpManager object.



Table of Contents