NSHelpPanel

Inherits From: NSPanel : NSWindow : NSResponder : NSObject

Conforms To: NSCoding (NSResponder) NSObject (NSObject)

Declared In: AppKit/NSHelpPanel.h

Class Description

The NSHelpPanel class is the central component of the OpenStep help system. It provides the Help panel that displays the text and illustrations that constitute your application's help information. The NSHelpPanel class object itself stores the table of associations between an application's user-interface objects and specific passages of the help text.

Users can display the Help panel by choosing the Help command from an application's Info menu. The panel employs the metaphor of a book: It displays a table of contents, body text, and an index. Users can browse through the text by clicking entries in the table of contents or index. The panel also supports hypertext-like help links, which appear as diamond-shaped images within the text and allow the user to easily follow cross references. By using the help cursor and clicking user-interface objects, the user can query the Help panel for information associated with those objects.

The Help Text

An NSHelpPanel object looks in a language-specific directory within the application's file package for the text that it will display. (Some implementations may employ more efficient means of storage than files and directories.) For example, if the user's language preference is English, the panel searches for a directory named Help within the English.lproj directory of the application's file package. It searches for two files: TableOfContents.rtf and Index.rtfd. There may also be one or more files containing the body text that the Help panel will display. The table-of-contents, index, and body files are interconnected by a system of help links and help markers.

A help marker is a named position holder in the stream of textin most cases, it's invisible to users. A help link is a diamond-shaped button embedded in the text. Help links store a file name and, optionally, a help marker name. When a user clicks a help link, the Help panel displays the named file. If the help link also stores a marker name, the displayed file is scrolled to the position of the marker, and the text is selected from the marker's position to the end of the line.

Table-of-Contents and Index Files

The table-of-contents and index files are specially designed documents in Rich Text Format (RTF). An NSHelpPanel object identifies these files by name (TableOfContents.rtf and Index.rtfd) and processes them differently than it does other help files.

The table-of-contents file should contain one entry for each help text file in the help directory. Each entry begins with a help link that stores the name of the destination file for that entry. Following the link is the text of the entry, which may wrap and span several lines. Although the table of contents in the Help panel looks like it's displayed by an NSMatrix, it's actually displayed by a modified NSText object. Thus, you can use the full generality of RTF to format your table of contents.

The index file is structured similarly although there is no enforced one-to-one mapping. Generally, the help link that begins an index entry stores both a file name and a marker name, since an index entry usually points to a specific word or phrase within a file.

Generic Help Files

An application's Help directory can contain only table-of-contents and index files, and yet the application may be able to display numerous help subjects, each of a general nature. This is because OpenStep applications have access to generic help files contained in a directory found in a system-specific location.

When a help link is being resolved, the NSHelpPanel first looks for the specified file within the appropriate language.lproj/Help directory of the application's file package. If the file isn't found, it then searches the directory of generic help files. This search path is used for all links, whether they are in the table of contents, index, or body text.

If one of these generic help files is inappropriate for your application, you have two remedies: You can remove the table-of-contents and index entries that refer to it, or you can override the file with one that's more appropriate. By placing a file of the same name and relative location within your application's Help directory, NSHelpPanel will display it rather than the generic file.

Associating Help Text with Objects

The NSHelpPanel class stores associations between user-interface objects and help text. When the user presses the Help modifier key (which varies depending on the hardware running the application), a question mark cursor appears. If the user clicks an object using this cursor, the Help panel displays the associated help text.

You can attach a help file to a user-interface object programmatically, by sending an attachHelpFile:markerName:to: message to the NSHelpPanel class object. This method takes a file name, a marker name, and an object id as its arguments. The detachHelpFrom: message removes such an association.

Just as with help links, an NSHelpPanel searches both the application's file package and the generic help files in attempting to find the file associated with a particular user-interface object.

Hidden Files

Although in general there's a one-to-one relationship between table-of-contents entries and files in the Help directory, you can force a single table-of-contents entry to represent multiple hidden files. This can be useful in reducing the overall length of the table of contents.

Hidden files can't be accessed from the table of contents; rather, the user must find them by Help-clicking an object in the application's user interface, by using the Help Panel's Find command, by using the index, or by following a help link from some other file. However, when a hidden file is displayed, the Help panel must select some entry in the table of contents.

Conversely, when the user selects such a table-of-contents entry, the Help panel must display one of the files in the directory of hidden files; by convention, this file must be named Prolog.rtfd. The prolog file typically informs users that they can get help on a particular user-interface object by Help-clicking that object.

The Help panel's Find button searches through all the files that are connected to table-of-contents entries, first looking in the application's Help directory and then in the generic help material. If you don't want some hidden file in the generic help material to appear in your application's Help panel as the result of a Find operation, override the file with an empty file of the same name. Since the file is empty, no search string will ever be found in it, and it will effectively block the generic file of the same name from being searched.

Searching the Help Text

By clicking the Help panel's Find button, users can search the help text for strings. NSHelpPanel uses two approaches to locate text containing a specific string. First, it attempts to find the string in the currently displayed help text by sending the object that displays the text (an instance of NSCStringText) a findText:ignoreCase:backwards:wrap: message. If the search is unsuccessful, or if the search is continued past the last occurrence of the string in the current file, the NSHelpPanel object scans for the string in other help files, both within the application's help files and within the generic help files. Some implementations of NSHelpPanel may make use of a previously built index of all the help text to speed this search.

Help Supplements

Since in OpenStep an application may load executable modules dynamically (for example, a drawing program could allow the user to load a new drawing tool), an NSHelpPanel object provides the ability to load supplemental help information. When the application loads the module, it sends the NSHelpPanel object an addSupplement:inPath: message to inform the object of the location of the new help supplement. The NSHelpPanel object appends the contents of the supplement's TableOfContents.rtf to the existing table of contents, so the supplement should have a title that clearly sets it off from the main part of the table of contents, for example:

Pattern Tool Supplement

Pattern Options

Brick

Stucco

Wood

Tile

Custom

Resizing and Rotating

Blending Patterns

Index to Supplement

The supplement's index is only accessible from the table of contents; the Help panel's Index button displays only the main index.

Accessing the Help Panel

• + (NSHelpPanel *)sharedHelpPanel Creates, if necessary, and returns the NSHelpPanel object.
• + (NSHelpPanel *)sharedHelpPanelWithDirectory:(NSString *)helpDirectory Creates, if necessary, and returns the NSHelpPanel object. If the panel is created, it loads the help directory specified by helpDirectory. The help directory must reside in the main bundle. If a Help panel already exists but has loaded a help directory other than helpDirectory, a second panel will be created.

• + (void)setHelpDirectory:(NSString *)helpDirectory Initializes the panel to display the help text found in helpDirectory. By default, the receiver looks for a directory named Help.
• - (void)addSupplement:(NSString *)helpDirectory Append additional help entries to the Help panel's table of inPath:(NSString *)supplementPath contents.
• - (NSString *)helpDirectory Returns the absolute path of the help directory.
• - (NSString *)helpFile Returns the path of the currently loaded help file.

• + (void)attachHelpFile:(NSString *)filename Associates the help file filename and markerName with markerName:(NSString *)markerName anObject. to:(id)anObject
• + (void)detachHelpFrom:(id)anObject Removes any help information associated with anObject.

• - (void)showFile:(NSString *)filename Causes the panel to display the help contained in filename atMarker:(NSString *)markerName at markerName.
• - (BOOL)showHelpAttachedTo:(id)anObject Causes the panel to display help attached to anObject.

• - (void)print:(id)sender Prints the currently displayed help text.