- app:sender willShowHelpPanel:panel{char path[MAXPATHLEN + 1];
Copyright ©1995 by NeXT Computer, Inc. All Rights Reserved.
| NXHelpPanel |
| Inherits From: | Panel : Window : Responder : Object | |
| Declared In: | appkit/NXHelpPanel.h |
| Class Description |
| The NXHelpPanel class is the central component of the NEXTSTEP help system. It provides the Help panel that displays the text and illustrations that constitute your application's help information, and it stores associations of user-interface objects with specific passages of that 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. Adding the standard help system facilities to your application is easy. The Add Help Directory command in Project Builder supplies your application with a help directory and populates it with simple table-of-contents and index files. Interface Builder's Menu palette offers a Info submenu containing a preconfigured Help command. With this command and the two files, your application can display the generic help text that's available to all NEXTSTEP applications (for example, "Using the mouse" and "Sending a fax"). You can then add help information (as well as table-of-contents and index entries) that are specific to your application, and override any of the generic information your application inherits.
The Help Text An NXHelpPanel object looks in a language-specific directory within the application's file package for the text that it will display. 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 text--in 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. The Text class provides the functionality for help links and markers, so this feature is available outside the Help panel. You use Edit to create and modify help documents. Edit's Help menu (accessible through the Format command) lets you insert links and markers and make the normally invisible help markers visible. Also in Edit, you can inspect and modify an existing help link or marker by holding down the Command key while clicking it.
Table-of-Contents and Index Files The table-of-contents and index files are specially designed documents in Rich Text Format (RTF). An NXHelpPanel 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 a Matrix, it's actually displayed by a modified Text 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 The Help directory that Project Builder provides for a new application contains only table-of-contents and index files; no other help files are present. However, if you run the application, you'll find that its Help panel can display numerous help subjects, each of a general nature. This is because NEXTSTEP applications have access to the generic help information contained in /usr/lib/NextStep/Resources/language.lproj/Help.store (a compressed help directory). When a help link is being resolved, the NXHelpPanel 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 in /usr/lib/NeXTSTEP/Resources/language.lproj/ Help.store. This search path is used for all links, whether they are in the table of contents, index, or body text. (Be forewarned: Edit doesn't apply this search path to help links, so if you open the table-of-contents or index files in Edit and click a help link, Edit will complain that the file can't be found, unless it exists within the application's file package.) 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, NXHelpPanel will display it rather than the generic file. See "Structure of the Generic Help Directory" below for the names and directory locations of the generic help files. If you want to modify the generic file, use Interface Builder's Help Builder panel to display the file, and then select the entire text and copy and paste it into a new document. Save the document in your application's Help directory using the same name as shown in the Help Builder panel. Be sure to resize the window to the same width as the original so that the text will wrap to the same margins.
Associating Help Text with Objects The NXHelpPanel class stores associations between user-interface objects and help text. When the user presses the Help modifier key (or, on older keyboards, simultaneously presses the Control and Alternate keys), a question mark cursor appears. If the user clicks an object using this cursor, the Help panel displays the associated help text. The easiest way to create these associations is with Interface Builder's Help Builder panel. If your application has a Help directory containing the files TableOfContents.rtf and Index.rtfd, the Help Builder panel will let you use them to display the application's help files. By selecting an object in your application, displaying the appropriate help file in the Help Builder panel, and clicking the Attach File to Selection button, you establish the association. You can also attach a help file to a user-interface object programmatically, by sending an attachHelpFile:markerName:to: message to the NXHelpPanel 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 NXHelpPanel searches both the application's file package and the appropriate file in /usr/lib/NeXTSTEP/Resources/language.lproj 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. For example, Mail's Help panel contains a single entry, "Commands, buttons, and panels," that's highlighted no matter which user-interface object has been queried for its associated help information. 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. In Mail, this entry is entitled "Commands, buttons, and panels." Conversely, when the user selects such an 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 for the "Commands, buttons, and panels" entry informs users that they can get help on any command, panel, or button by Help-clicking that object. The table of contents supplied by Project Builder contains the entry "Commands" that corresponds to a directory of hidden files. Conceptually, these files exist in /usr/lib/NeXTSTEP/Resources/language.lproj/Help/Objects (in fact, they are contained in a compressed file derived from this original directory structure). In your application, you can add to (or override) these hidden files by creating an Objects subdirectory within your application's Help directory and placing the new files there. 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 your table of contents has a link to the Objects subdirectory (in other words, has the "Commands" entry, as provided by Project Builder), the hidden files will be searched too. 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.
Context-Sensitive Help Your application can provide context-sensitive help; that is, the particular text displayed when the Help menu command is chosen or when the user Help-clicks an object can depend on the state of the application. Context-sensitive help requires the intervention of the Application object's delegate. If the Application object's delegate responds to the app:willShowHelpPanel: message, it receives such a message just before the Help panel is displayed. Within the implementation of the app:willShowHelpPanel: method, the delegate can specify which file will appear in the panel: |
- app:sender willShowHelpPanel:panel
{
char path[MAXPATHLEN + 1];
sprintf (path, "%s/%s", [panel helpDirectory],
"Tasks/AddressingMail/CreatingAddressBook.rtfd");
[panel showFile:path atMarker:NULL];
return self;
}
| The delegate must specify a fully qualified path since the NXHelpPanel object assumes that a partial path is relative to the currently displayed help file.
Indexing Help Text The Help panel's Find button makes use of Indexing Kit facilities to quickly locate files containing the search string. (Note that the index discussed here is a binary file produced by the Indexing Kit, not the Index.rtfd file that contains the textual index). To create an index for your help files, in a Terminal window switch to the Help directory you want indexed and then enter: |
ixbuild -v
| with no other arguments. The ixbuild program builds an index (named .index.store) for the Help directory and its subdirectories.
If your application contains a directory of "hidden" help files, you must first make an index of that directory before creating an index of the entire Help directory.
Help Supplements Since in NEXTSTEP some applications have the ability to load executable modules dynamically (for example, a drawing program could allow the user to load a new drawing tool), an NXHelpPanel object provides the ability to load supplemental help information. When the application loads the module, it sends the NXHelpPanel object an addSupplement:inPath: message to inform the object of the location of the new help supplement. The NXHelpPanel 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: |
| --PatternTool Supplement-- |
| Pattern Options
Brick 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 the main index.
Structure of the Generic Help Directory As mentioned earlier, the generic help text provided in NEXTSTEP is contained in the file /usr/lib/NeXTSTEP/Resources/language.lproj/Help.store. This compressed file was derived from a directory of help files. To override a generic help file, you'll need its name and location in the original directory structure. The following listing provides that information: |
| HelpIndex.rtfdObjectsMenusMainServicesMenu.rtfdWindowsMenu.rtfdServicesOtherService.rtfdWindowsArrangeInFront.rtfdCloseWindow.rtfdMiniaturizeWindow.rtfdWindowName.rtfdPanelsColorsPanel.rtfdFaxPanel.rtfdFontPanel.rtfdLinkInspectorPanel.rtfdOpenPanel.rtfdPageLayoutPanel.rtfdPrintPanel.rtfdSavePanel.rtfdSpellingPanel.rtfdProlog.rtfdTableOfContents.rtfTasksGettingStartedAdjustBriteVolume.rtfdButtonsSlidersFields.rtfdChooseCommands.rtfdClickingHelp.rtfdDetachSubmenu.rtfdFindingHelp.rtfdGettingHelpTopic.rtfdScrolling.rtfdUsingMouse.rtfdWorkingWindows.rtfdReferenceCursor.rtfd |
| Instance Variables |
| None declared in this class. |
| Method Types |
| Initializing and freeing | + new |
+ newForDirectory: addSupplement:inPath: free |
| Attaching Help to objects | + attachHelpFile:markerName:to: |
| + detachHelpFrom: |
| Setting click-for-help | + isClickForHelpEnabled |
| + setClickForHelpEnabled: |
| Printing | print: |
| printPanel: |
| Querying | helpDirectory |
| helpFile |
| Showing help | showFile:atMarker: |
| showHelpAttachedTo: |
| Class Methods |
| attachHelpFile:markerName:to: |
| + attachHelpFile:(const char *)filename |
| markerName:(const char *)markerName to:anObject |
| Associates filename and markerName with anObject. filename should be a path relative to the Help directory. markerName is the name of a marker within the file specified by filename. Returns self.
When anObject is Help-clicked, the Help panel displays the specified file, and the text is scrolled so that the point marked by markerName is visible. (If markerName is NULL, the file isn't scrolled.) See also: |
| detachHelpFrom: |
| + detachHelpFrom:anObject |
| Removes any help information associated with anObject. Returns self.
See also: |
| isClickForHelpEnabled |
| + (BOOL)isClickForHelpEnabled |
| Returns whether Help-clicking is enabled.
See also: + setClickForHelpEnabled: |
| new |
| + new |
| Creates, if necessary, and returns the NXHelpPanel object. This method invokes the newForDirectory: method, using "Help" as the single argument.
See also: + newForDirectory: |
| newForDirectory: |
| + newForDirectory:(const char *)helpDirectory |
| Creates, if necessary, and returns the Help panel. 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.
See also: + new |
| setClickForHelpEnabled: |
| + setClickForHelpEnabled:(BOOL)enabled |
| Sets whether Help-clicking is enabled. Normally most applications will leave this feature enabled. However on keyboards without a Help key, the user must hold the Control and Alternate modifiers while Help-clicking. Because some applications may depend upon the simultaneous use of these modifiers, they may need a way to disable the click-for-help feature. In this case, it is recommended that the application have a menu command to allow the user to toggle whether click-for-help is enabled or whether these modifiers are passed through for the application's use. The menu title should be "Disable Click for Help" and should toggle with "Enable Click for Help". Returns self.
See also: + isClickForHelpEnabled |
| Instance Methods |
| addSupplement:inPath: |
| addSupplement:(const char *)helpDirectory inPath:(const char *)supplementPath |
| Adds supplemental help by appending the supplement's TableOfContents.rtf file to the existing table of contents. This method is designed to be used when an application dynamically loads a resource that has its own help information. Returns self. |
| free |
| free |
| Frees the NXHelpPanel and its storage. |
| helpDirectory |
| (NXAtom)helpDirectory |
| Returns the absolute path of the currently loaded help directory.
See also: |
| helpFile |
| (NXAtom)helpFile |
| Returns the path of the currently loaded help file relative to the current help directory.
See also: |
| print: |
| print:sender |
| Prints the currently displayed help text and returns self. |
| printPanel: |
| printPanel:sender |
| This is the same as the print: method. |
| showFile:atMarker: |
| showFile:(const char *)filename atMarker:(const char *)markerName |
| Causes the Help panel to display the help contained in filename. If markerName is non-NULL, then the marker is sought in the file. If found, it's scrolled into view and the text from the marker to the end of the line is highlighted. If the file is not a full path, then it's assumed to be relative to the currently displayed help file. Returns self. |
| showHelpAttachedTo: |
| (BOOL)showHelpAttachedTo:anObject |
| Causes the Help panel to display the help attached to anObject. Returns YES if the object has help attached to it, NO if not. |