ViewKit allows you to implement help in several different ways. You can use the built-in help capability, link to SGIHelp, or link to an external library. You must include <Vk/VkHelpAPI.h> if you wish to implement online help.

ViewKit applications interact with a help library through three C functions: SGIHelpInit(), SGIHelpMsg(), and SGIHelpIndexMsg(). To use an external help library with a ViewKit application, you need to implement only these three functions.

---

Note: ViewKit makes all calls to the help system. Your application should never need to call SGIHelpInit(), SGIHelpMsg(), or SGIHelpIndexMsg() directly. The only exception would be if you create a help button in your application without using the VkDialogManager class (see “Application Help Button Procedures”).

---

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() are 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() is reserved for future Silicon Graphics use. A return value of 0 indicates failure.

The ViewKit library, libvk, includes a simple help capability that allows you to provide help messages for your application by defining them in the X resource database. This may be sufficient for your needs.

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 database. They then display the retrieved help text in an Motif 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 push buttons 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.

As documented in the IRIX Interactive Desktop Integration Guide, the Silicon Graphics help library, libhelpmsg, handles communication with the help server. libhelpmsg depends on the libX11 library, so you must specify -lhelpmsg before -lX11 in the compilation or linking command.

For example, to compile a file hellohelp.c++ to produce the executable hellohelp, you would enter the following:

CC -o hellohelp hellohelp.c++ -lhelpmsg -lX11

For specific information and examples about how to implement SGIHelp, see Chapter 9, “Providing Online Help with SGIHelp,” in the IRIX Interactive Desktop Integration Guide. Keep in mind, however, that in most instances, ViewKit makes the calls to SGIHelpInit(), SGIHelpMsg(), and SGIHelpIndexMsg() for you. Your application will seldom have to call these functions directly (see “ViewKit Programmatic Interface to a Help Library”).

For general and stylistic information about using SGIHelp, see Chapter 4, “IRIX Interactive Desktop Services,” in the IRIX Interactive User Interface Guidelines. For information on writing SGIHelp, see the Iris InSight Professional Publisher User's Guide.

ViewKit allows you to link to an external help library if you so choose. In order for this to work correctly, your library must be a Dynamic Shared Object (DSO) that contains the three C functions that serve as entry points to the help system, SGIHelpInit(), SGIHelpMsg(), and SGIHelpIndexMsg(). These functions are then called instead of the ViewKit Help functions that are provided with libvk. Since ViewKit predefines SGIHelpInit(), SGIHelpIndexMsg(), and SGIHelpMsg as weak symbols, they are overridden by your library, and no conflict will ensue. For more information, see the VkHelp(3x) reference page.

If you do decide to write your own help library, you can examine ViewKit's help functions to get some ideas. The source is included in /usr/share/src/ViewKit/Utilities/VkHelpAPI.c++.

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 the help system displays the token string passed to the help system instead of the help message it would normally display

The Help menu, implemented by the VkHelpPane class, provides a simple user interface to a help system.

Implementation of the Help Menu

VkHelpPane is a subclass of VkSubMenu. VkHelpPane automatically provides five standard menu items, as shown in Figure 11-1.

Figure 11-1. ViewKit Help Menu

The first four items interface to a help system. This help system must provide help request handling and appropriate help messages for the menu item selected:

Click for Help		Provides 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 provided to SGIHelpMsg() is the fully qualified instance name hierarchy for the widget
Overview		Requests overview help. The in_key character token provided to SGIHelpMsg() is “ApplicationName.overview”.
Index		Requests an index of available help topics. The in_key character token provided to SGIHelpMsg() is “ApplicationName.index”.
Keys & Shortcuts		Requests help on keys and shortcuts. The in_key character token provided to SGIHelpMsg() is “ApplicationName.keys”.
Product Information		Displays the Product Information dialog described in “Maintaining Product and Version Information”. The Product Information dialog has no connection to the help system.

Because VkHelpPane is a subclass of VkSubMenu, you can also use the functions provided by VkSubMenu (see “Using ViewKit Menu Subclasses”) to add custom Help menu items and delete predefined Help menu items.

Adding the Help Pane to a Menu

The VkMenuBar constructor, described in “Menu Bar Constructors”, accepts a showHelpPane argument. If this argument is TRUE (the default) the VkMenuBar constructor automatically creates a VkHelpPane object and installs it in the menu bar.

You can create a VkHelpPane object and add it to another menu, for example a popup menu, but you should rarely need to do this.

X Resources Associated With the Help Pane

The following X resources affect the appearance and behavior of the VkHelpPane class:

*helpMenu.labelString		The label for the Help menu (default value “Help”).
*helpMenu.mnemonic		The Help menu mnemonic (default value “H”).
*helpMenu.helpOnContextMenuItem.labelString		The label for the context-sensitive help item (default value “Click for Help”).
*helpMenu.helpOnContextMenuItem.mnemonic		The context-sensitive help item mnemonic (default value “C”).
*helpMenu.helpOnContextMenuItem.accelerator		The context-sensitive help item accelerator (default value “Shift+F1”).
*helpMenu.helpOnContextMenuItem.acceleratorText		The context-sensitive help item accelerator label (default value “Shift+F1”).
*helpMenu.helpOverviewMenuItem.labelString		The label for the help overview item (default value “Overview”).
*helpMenu.helpOverviewMenuItem.mnemonic		The help overview item mnemonic (default value “O”).
*helpMenu.helpIndexMenuItem.labelString		The label for the help index item (default value “Index”).
*helpMenu.helpIndexMenuItem.mnemonic		The help index item mnemonic (default value “I”).
*helpMenu.helpKeysMenuItem.labelString		The label for the keys and shortcuts item (default value “Keys & Shortcuts”).
*helpMenu.helpKeysMenuItem.mnemonic		The keys and shortcuts item mnemonic (default value “K”).
*helpMenu.helpVersionMenuItem.labelString		The label for the product information item (default value “Product Information”).
*helpMenu.helpVersionMenuItem.mnemonic		The product information item mnemonic (default value “P”).

QuickHelp is a facility that displays a string when the pointer enters a widget. Help can be displayed in a message line at the bottom of the window, in a small balloon that pops up next to the pointer (“balloon help” or “popup help”), or both. Each can have its own separate help text, typically a brief phrase for popup help, and a more detailed message for the message line.

QuickHelp availability is controlled by the resources showHelp, showPopupHelp, and showMsgLineHelp:

Space is allocated for the message line only if message-line help is already enabled when the window is first created.

QuickHelp usability includes getting balloons promptly when you want them, but not getting them when you do not want them. This requires guessing what the user wants at any given time, and so has no perfect solution. In an attempt to come as close as possible, QuickHelp has several timers.

The timers control how soon and how long a balloon is displayed once the pointer enters a widget. The delay time before a balloon is displayed depends on whether the user is deemed to be in browse mode or non-browse mode. The user is considered to be in browse mode when the pointer enters two or more widgets in succession at a relatively slow speed. In this mode, all balloons after the first are displayed more quickly. If the user stops browsing for a set length of time, the application returns to non-browse mode.

Since these timings greatly affect the usability of QuickHelp, they have been carefully set to minimize both the number of unwanted balloons and the length of time users must wait to receive wanted help. If the default timings do not work for your application, you may reset them.

QuickHelp also provides some miscellaneous resources:

Two other resources are intended for developers to use in debugging but may also be useful to some end users.

dumpTree		Prints the name and class for each of the widgets in the widget tree at the time the dump is done. This can be useful as a starting point for creating the QuickHelp text for each widget. Note: A common error is to forget that this cannot dump any widget that has not yet been created at the time of the dump. For example, since ViewKit usually creates menus later in a workProc, dumpTree is likely to run before the workProc is completed. Therefore, those menus will not be included in the widget tree, because the tree will be dumped before the menus exist. For more information on creating menus, see the reference page for VkMenu(3x), useWorkProcs(Boolean).
showWidgetInfo		Causes QuickHelp to display the widget name, rather than any QuickHelp text. This can be useful when trying to figure out just what a widget is called so you can set a resource for it. For this to work, showHelp must be set to TRUE. If you want the widget name to be displayed in a popup balloon, showPopupHelp must be set to TRUE. If you want the widget name to be displayed on the message line, showMsgLineHelp must be set to TRUE.

And, finally, there are two per-widget resources that provide the actual help strings, msgLineHelpText and popupHelpText. Both of these are of resource class QuickHelpText. If one of these resources is not set for any given widget, the user is not shown that type of help message, even if showHelp, showPopupHelp, and showMsgLineHelp are all set to TRUE.