Chapter 11. Using a Help System With ViewKit
Prev |  | Next

## Chapter 11. Using a Help System With ViewKit

ViewKit supports several ways for a user to obtain help: context-sensitive help (both through the F1 key and a help menu), help menus, help buttons, and popup and message-line help (QuickHelp).

For the developer, the ViewKit API provides entry points to an external help library, to the SGIHelp system, or to a simple default help capability that may be sufficient for many applications. You can also combine any of these help capabilities with QuickHelp, which provides popup and message-line help, and operates independently of any other type of help.

## ViewKit Programmatic Interface to a Help Library

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.

## Using ViewKit Help

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.

## Using the SGIHelp Library

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.

## Using an External Help Library

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++`.

## ViewKit Support for Building Help

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

## ViewKit Help Menu

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”).

## Other Types of Help

### Context-Sensitive Help Procedures

ViewKit calls `SGIHelpMsg()` when the user presses the F1 key while the mouse pointer is over a widget (unless you have provided XmNhelpCallback functions for widgets in your application). The in_key character token that your application provides to `SGIHelpMsg()` is the fully qualified instance name hierarchy for the widget.

### 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 the Help button, ViewKit calls `SGIHelpMsg()`, passing the helpString as the in_key character token.

### Application Help Button Procedures

If you provide a Help button not created by the `VkDialogManager` class, your application must call `SGIHelpMsg()` directly.

## QuickHelp

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:

- If showHelp is FALSE, no QuickHelp is shown. This provides an easy way to enable or disable the entire QuickHelp system.

- If showPopupHelp is FALSE, popup help is not shown. If showPopupHelp and showHelp are both TRUE, then popup help is shown.

- If showMsgLineHelp is FALSE, no message-line help is shown. If showMsgLineHelp and showHelp are both TRUE, then message-line help is shown.

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.

helpTextWaitTime |  | The delay after entering a widget, when not in browse mode, before the QuickHelp balloon is posted.
helpTextBrowseWaitTime |  | The delay after entering a widget, when in browse mode, before the QuickHelp balloon is posted.
helpTextTimeUp |  | The length of time a QuickHelp balloon remains posted.
helpTextBrowseCancelTime |  | The length of time after leaving a widget before browse mode is cancelled.
helpTextBrowseVelocity |  | The pointer velocity below which users are considered to be browsing and above which they are considered to be in transit. A QuickHelp balloon is posted when users are browsing, but not when they are in transit.

QuickHelp also provides some miscellaneous resources:

helpTextInsensitive |  | Controls whether or not QuickHelp is given when entering insensitive widgets.
smallWidget |  | Determines where the help balloon is displayed, in relation to the widget. If either dimension of a widget is below the number of pixels specified in the resource smallWidget, then the widget is considered to be a small widget. For a small widget, if the narrow dimension is its height, the balloon is displayed below the widget (for example, a horizontal scroll bar). If the narrow dimension is its width, the balloon is displayed beside the widget (for example, a vertical scroll bar). For large widgets, the balloon is displayed near the part of the widget where the pointer first entered it.

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.

Prev | Table of Contents | Next
Chapter 10. ViewKit Cut and Paste |  | Chapter 12. The ViewKit Graph Component