9 Creating and Managing
Help Dialog Boxes

Help Dialog Boxes

Standard Xt Paradigm

General Help Dialog

To Create a General Help Dialog

Quick Help Dialog

To Create a Quick Help Dialog

Summary of Application Program Interface

Help Dialog Boxes

• General help dialogs have a menu bar, a topic tree, and a help topic display area. The topic tree lists the help volume's topics and subtopics. Users use the topic tree to select topics to view, to browse available topics, and to locate where they are in the help volume.

• Quick help dialogs contain a topic display area and one or more dialog buttons at the bottom.

Standard Xt Paradigm

Nearly every attribute of the help windows--including the volume name and topic ID--are manipulated as widget resources. For instance, to display a new topic, you just execute an XtSetValues() call to set the DtNhelpVolume, DtNlocationId, and DtNhelpType resources. For more information, refer to "Displaying Help Topics."

General Help Dialog

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

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

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);

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

See Also

• "Providing Help on Help"
• "To Enable the Application-Configured Button"
• DtCreateHelpDialog(3)man page
• DtHelpDialog(3)man page

Quick Help Dialog

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.

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

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);

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

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

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

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

Summary of Application Program Interface

• Functions for creating and working with dialogs:

  DtHelp(5)
  DtHelpDialog(5)
  DtHelpQuickD(5)
  DtCreateHelpDialog()
  DtCreateHelpQUickDialog()
  DtHelpQuickDialogGetChild()
  
  

• Function for implementing item help mode:

  DtHelpReturnSelectedWidgetId()
  
  

• Function for specifying the message catalog for the Help library:

  DtHelpSetCatalogName()
  
  

• Applications and actions for creating and viewing a help volume:

  dthelptag(1)
  dthelpview(1)
  dthelpgen(1)
  dthelpaction(5)
  dtmanaction(5)
  
  

• Document Type Definitions:

  dthelptagdtd(4)
  dtsdldtd(4)