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:

• Let the user ask for more detailed information. In this case, the default button label (More) is appropriate. This is called progressive disclosure.

• Let the user open a general help dialog for general browsing of the application's help volume. In this case, Browse... is the most appropriate button label.

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.

Example

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,
										DT_HELP_QUICK_MORE_BUTTON);
 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,
										DT_HELP_QUICK_HELP_BUTTON);
 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

• "To Enable the Application-Configured Button"

• Chapter 12, Providing Help on Help

• DtCreateHelpQuickDialog(3) man page

• DtHelpQuickDialog(3) man page

• DtHelpQuickDialogGetChild(3)man page