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

Quick Help Dialog

The quick help dialog box is designed to help you meet the first objective of online help: Get the user back on task as quickly and successfully as possible. This simple user interface helps keep the user focused on the information. The information should be useful enough that the user dismisses the dialog after reading it and continues working.

Figure 9-2 Quick help dialog with four standard buttons


The quick help dialog has five buttons, four of which are managed. The remaining dialog button is configurable, so this button can be used for anything. However, its intended purpose is to provide a path to more help in one of these two ways:

The Developer's toolkit includes a convenience function, DtHelpQuickDialogGetChild(), for determining the widget ID for any of the quick help dialog buttons.

To Create a Quick Help Dialog

  1. Include the appropriate header files:

    #include <Help.h>
     #include <HelpQuickD.h>
  2. Create an instance of the quick help dialog widget:

    • Use the DtCreateHelpQuickDialog() 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 OK button.

  5. Configure the dialog buttons that you want to use:

    • If you intend to use the application-configured button, manage it and add an activate callback.

    • If you want to disallow printing, unmanage the Print button.

    • Manage the Help button and add a help callback to the dialog to allow the user to get help on help.


The following code segment creates a quick 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. In this example, the application-configured button is enabled and used to request more help.

Widget   quickHelpDialog, 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++;

 quickHelpDialog =
   DtCreateHelpQuickDialog (parent,  "quickHelpDialog", 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 (quickHelpDialog, DtNhyperLinkCallback,
				HyperlinkCB, (XtPointer)NULL);
XtAddCallback (quickHelpDialog, DtNcloseCallback,
                CloseHelpCB, (XtPointer)NULL);

Here, the application-configured button is managed and assigned an activate callback that invokes the application's MoreHelpCB() function.

moreButton = DtHelpQuickDialogGetChild (quickHelpDialog,
 XtManageChild (moreButton);
XtAddCallback (moreButton, XmNactivateCallback,
                MoreHelpCB, (XtPointer)NULL);

To provide "help on help," the dialog's Help button is managed and a help callback is added to the dialog.

helpButton = DtHelpQuickDialogGetChild (quickHelpDialog,
 XtManageChild (helpButton);
XtAddCallback (quickHelpDialog,DtNhelpCallback,
                HelpRequestCB, USING_HELP);

Like other OSF/Motif dialogs, when you add a help callback to a quick help dialog, it is used by both the F1 key and the Help button.

See Also