This appendix describes how to use a help system with ViewKit applications. It covers:
the user interfaces through which a user can obtain help
ViewKit's programmatic interface (API) to external help libraries and instructions for creating ViewKit-compatible help libraries
ViewKit's own simple help capability
Additional support provided by ViewKit for creating help information for your applications
ViewKit also provides message line and popup QuickHelp. See “QuickHelp” for more information.
In a ViewKit application, the user can invoke the help system three different ways: 1) by pressing the <F1> key while the mouse pointer is over a widget, 2) by clicking the Help button in a dialog, or 3) by choosing an item from the Help menu.
The <F1> key is a standard IRIS IM method of invoking help. ViewKit applications provide an additional layer of interpretation to allow you to integrate this method of invoking help with the other methods provided by ViewKit. Rather than installing XmNhelpCallback functions on widgets, use ViewKit's programmatic interface to the help libraries as described in “ViewKit's Programmatic Interface to a Help Library”.
ViewKit dialogs also allow you to include a Help button as described in “Posting Dialogs”. The Help menu, implemented by the VkHelpPane class, also allows the user to invoke the help system. “ViewKit's Programmatic Interface to a Help Library” describes how to link these interfaces to a help system.
ViewKit applications interact with a help library through three C functions: SGIHelpInit(), SGIHelpMsg(), and SGIHelpIndexMsg(). To interface a ViewKit application to a help system, you need to implement only these three functions. ViewKit also provides a rudimentary help capability if you do not want to implement your own. “ViewKit Help” describes this capability.
SGIHelpInit() initializes the help system:
int SGIHelpInit(Display *display, char *appClass, char *) |
VkApp calls SGIHelpInit() from its constructor. display is the application's Display structure, and appClass is the application's class name. The third argument to SGIHelpInit() is reserved for future Silicon Graphics use. A return value of 0 indicates failure.
A ViewKit application calls SGIHelpMsg() when it needs to request help:
int SGIHelpMsg(char *in_key, char *, char *) |
in_key is a character token that SGIHelpMsg() uses to look up help material. The value of in_key depends on how the user requested help. The subsections that follow describe how the value is determined. The other arguments to SGIHelpMsg() is reserved for future Silicon Graphics use. A return value of 0 indicates failure.
A ViewKit application calls SGIHelpIndexMsg() to display an index of help available:
int SGIHelpIndexMsg(char *in_key, char *) |
in_key is a character token that SGIHelpIndexMsg() uses to look up a help index. The value of in_key depends on how the user requested help. The subsections that follow describe how the value is determined. The other argument to SGIHelpIndexMsg() are reserved for future Silicon Graphics use. A return value of 0 indicates failure.
When you post a dialog as described in “Posting Dialogs”, you have the option of providing a helpString argument. If you provide a helpString argument, the dialog posted displays a Help button.
When the user clicks the Help button, your application calls SGIHelpMsg(), passing the helpString as the in_key character token.
When the user presses the <F1> key while the mouse pointer is over a widget, as long as you have not provided XmNhelpCallback functions for widgets in your application, your application calls SGIHelpMsg(). The in_key character token that your application provides to SGIHelpMsg() is the fully qualified instance name hierarchy for the widget.
As noted in “The ViewKit Help Menu”, the Help menu implemented by the VkHelpPane class contains five selectable items: “Click for Help,” “Overview,” “Index,” “Keys & Shortcuts,” and “Product Information”
“Click for Help” provides another method of obtaining context-sensitive help. When the user chooses this item, the cursor changes into a question mark. The user can then click any widget in the application, which calls SGIHelpMsg(). The in_key character token that your application provides to SGIHelpMsg() is the fully qualified instance name hierarchy for the widget.
“Overview” calls SGIHelpMsg() to request overview help. If the VkHelpPane object is a descendant of a shell widget, the in_key character token that your application provides to SGIHelpMsg() is “shellName.overview” where shellName is the name of the shell widget. In most cases, the VkHelpPane object is a pane in a window's menu bar, so the shellName is the name of the window. If the VkHelpPane object is not a descendant of a shell widget, the in_key character token that your application provides to SGIHelpMsg() is simply “overview.”
“Index” calls SGIHelpIndexMsg() to request an index of available help topics. If the VkHelpPane object is a descendant of a shell widget, the in_key character token that your application provides to SGIHelpIndexMsg() is “shellName.index” where shellName is the name of the shell widget. In most cases, the VkHelpPane object is a pane in a window's menu bar, so the shellName is the name of the window. If the VkHelpPane object is not a descendant of a shell widget, the in_key character token that your application provides to SGIHelpIndexMsg() is simply “index.”
“Keys & Shortcuts” calls SGIHelpMsg() to request help on keys and shortcuts. If the VkHelpPane object is a descendant of a shell widget, the in_key character token that your application provides to SGIHelpMsg() is “shellName.keys” where shellName is the name of the shell widget. In most cases, the VkHelpPane object is a pane in a window's menu bar, so the shellName is the name of the window. If the VkHelpPane object is not a descendant of a shell widget, the in_key character token that your application provides to SGIHelpMsg() is simply “keys.”
“Product Information” displays the Product Information dialog described in “Maintaining Product and Version Information”. The Product Information dialog has no connection to any help library.
The ViewKit library, libvk, includes a simple help capability that allows you to include help messages for your application by defining them in the X resource database. This may be sufficient for your needs.
ViewKit help is simple enough not to require any initialization, so SGIHelpInit() is defined to simply return the value 1.
Both SGIHelpMsg() and SGIHelpIndexMsg() are defined to accept the in_key character token argument and look up the resource “in_key.helpText” in the X resource library. They then display the help text retrieved from the resource database in an IRIS IM information dialog. If these functions cannot find an appropriate resource value, they display the message Sorry, no help available on this topic in the dialog.
The following lines show how you create the help message specifications for an application:
*helpText: Application default help message *row1*helpText: Help message for the row1 widgets and its descendants *row2*helpText: Help message for the row2 widgets and its descendants *row2*start*helpText: Special help message for start, a child widget of row2 *overview*helpText: Overview help message |
In this example, the “*helpText” resource specification provides a default help message for the entire application. If a widget does not have a more specific help message resource specification, the application displays this default help message.
The “*row1*helpText” and “*row2*helpText” resource specifications provide help messages for these widgets and their descendants. For example, you could use a specification like this to provide a help message for a group of toggles or pushbuttons in a RowColumn widget.
The “*row2*start*helpText” specification provides a help message for a “start” widget, a descendant of the “row2” widget. It overrides the “*row2*helpText” message.
“*overview*helpText” provides a message that the application displays when the user chooses “Overview” from the Help menu. You can also implement your own help library. Since ViewKit predefines SGIHelpInit(), SGIHelpIndexMsg(), and SGIHelpMsg as weak symbols, they are overridden by your library, and no conflict ensues.
If you decide to write your own help library, you can examine the source
for ViewKit's help functions to get some ideas. The source is included in /usr/share/src/ViewKit/Utilities/VkHelpAPI.c++. You can examine this source to get
ideas for implementing your own help library.
The default ViewKit help capability also provides support for determining the token strings passed to the help system. To use this feature, you must not link with any other help library. After you determine all of the token strings you need, you can then link with your chosen help library to provide the final help system for your application.
To determine the token strings, set the “*helpAuthorMode” resource for your application to TRUE. Then, when you run your application, whenever the help system would normally display a help message, it instead displays the token string passed to the help system.