test

Common Desktop Environment: Help System Author's and Programmer's Guide

General Help Dialog

A general help dialog has two display areas: the topic tree and topic display area. The topic tree provides a scrollable list of help topics. The home topic title is always the first item. When a user chooses a title, an arrow (=>) marks the title and its help information is displayed in the topic display area. Figure 9-1 shows the topic tree and topic display area of a general help window. The current topic, "To select a palette", is displayed.

The general help dialog includes three dialog buttons: Backtrack, History, and Index. These commands are also available in the Help menus. For an overview of the Help dialogs and the graphical user interface, refer to the section, "Help User Interface".

Figure 9-1 General help dialog

Graphic

To Create a General Help Dialog

  1. Include the appropriate header files: 

    #include <Help.h>
 #include <HelpDialog.h>

  2. Create an instance of the general help dialog widget:

    • Use the DtCreateHelpDialog() convenience function.

      Or, use the XtCreateManagedWidget() function.

  3. Add a callback for handling hyperlink events that occur within the dialog. (For more information, see "Responding to Hyperlink Events".)

  4. Add a close callback for handling the Close command.

Example

The following code segment creates a general help dialog (as a child of parent) using the convenience function. The dialog is left unmanaged--presumably it is managed elsewhere in the application when a help request is made. 

Widget   mainHelpDialog, moreButton, helpButton;
 ac = 0;
 XtSetArg (al[ac], XmNtitle,  "My Application - Help");  ac++;
 XtSetArg (al[ac], DtNhelpVolume,  "My Help Volume");  ac++;
 XtSetArg (al[ac], DtNlocationId,  "Getting Started");  ac++;
 XtSetArg (al[ac], DtNhelpType,  "DtHELP_TYPE_TOPIC");  ac++;

 mainHelpDialog =
   DtCreateHelpDialog (parent,  "mainHelpDialog", al, ac);

The following two calls add the hyperlink and close callbacks to the dialog. Presumably, the functions HyperlinkCB() and CloseHelpCB() are declared elsewhere in the application. 

XtAddCallback (mainHelpDialog, DtNhyperLinkCallback,
 				HyperlinkCB, (XtPointer)NULL);
 XtAddCallback (mainHelpDialog, DtNcloseCallback,
                CloseHelpCB, (XtPointer)NULL);

See Also