ViewKit's Programmatic Interface to a Help Library

ViewKit ObjectPak applications interact with a help library through three C functions. To interface an ObjectPak application to a help system, you need only to implement these three functions. ObjectPak also provides a rudimentary help library that you can use if you do not want to implement your own. "ViewKit ObjectPak Help Library" describes this library.

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 use. A return value of 0 indicates failure.

An ObjectPak 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 argument to SGIHelpMsg() is reserved for future use. A return value of 0 indicates failure.

An ObjectPak application calls SGIHelpIndexMsg() when it needs 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 arguments to SGIHelpIndexMsg() are reserved for future use. A return value of 0 indicates failure.

Dialog Help Procedures

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 on the Help button, your application calls SGIHelpMsg(), passing the helpString as the in_key character token.

Context-Sensitive Help Procedures

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 applications calls SGIHelpMsg(). The in_key character token that your application provides to SGIHelpMsg() is the fully-qualified instance name hierarchy for the widget.

Help Menu Procedures

As noted in "ViewKit Help Menu" , the Help menu implemented by the VkHelpPane class contains five selectable items: "Click for Help," "Overview," "Index," "Keys & Shortcuts," and "Product Info."

"Click for Help" provides another method of obtaining context-sensitive help. When the user selects this item, the cursor changes into a question mark. The user can then click on any widget in the application. When the user clicks on a widget, the application 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 descendent 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. The in_key character token that your application provides to SGIHelpIndexMsg() is the application's class name as it is returned by VkApp::applicationClassName().

"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 descendent of a shell widget, the in_key character token that your application provides to SGIHelpMsg() is simply "keys".

"Product Info" displays the Product Information dialog described in "Maintaining Product and Version Information" . The Product Information dialog has no connection to the help library.