Accessing Help on Help in an Application

Your application should do the following to support help on help:

• Set the helpOnHelpVolume resource to identify the help volume you want to access.

• Add a Using Help command to the application's Help menu.

To Set the helpOnHelpVolume Resource

Add a line to your application's application-defaults file like this:

 
App-class*helpOnHelpVolume:  volume

Where App-class is the application's class name and volume is the name of the help on help volume you want to access.

Or, within your application, set the helpOnHelpVolume resource for each help dialog you create.

Examples

• This line in dthelpview's application-defaults file (DtHelpview) specifies the help on help volume:

  DtHelpview*helpOnHelpVolume:  Help4Help

• To specify the help on help volume when creating a help dialog, add it to the argument list passed to the create function as shown here:

  ac = 0;
   XtSetArg (al[ac], XmNtitle, "My Application - Help"); ac++;
   XtSetArg (al[ac], DtNhelpOnHelpVolume, "Help4Help");  ac++;
   helpDialog = DtCreateHelpDialog (parent, "helpDialog", al, ac);

To Provide a Using Help Command

1. Add to your Help menu a button labeled Using Help. Also add the necessary activate callback to call your HelpRequestCB() function.

2. Add support to your HelpRequestCB() function to display help on help. Specifically:

   • Create a quick help dialog.

   • Set the dialog's title to Help On Help.

   • Display the home topic of the help on help volume.

   • Manage the quick help dialog.

Example

The following lines create a menu button labeled Using Help... that calls the HelpRequestCB() function.

/* Create the ` Using Help ...' button. */

labelStr = XmStringCreateLtoR ("Using Help ...",           XmSTRING_DEFAULT_CHARSET);
 ac = 0;
 XtSetArg (al[ac], XmNlabelString, labelStr);     ac++;
 button = XmCreatePushButtonGadget (parent, "usingHelpButton", al,  ac);
    XtManageChild (button);
    XmStringFree (labelStr);
    /* Add a callback to the button. */
   XtAddCallback (button,XmNactivateCallback,HelpRequestCB,
    USING_HELP);

USING_HELP is the client data passed to the HelpRequestCB() function when the menu button is chosen by the user. Presumably it has been defined somewhere in the application (perhaps in a Help.h file) as a unique integer:

#define USING_HELP  47

To see how the HelpRequestCB() function handles the USING_HELP case, see the example in the next section, "To Display Help on Help."

To Display Help on Help

1. Create a quick help dialog (or retrieve one from your cache).

2. Display in the dialog the home topic of your help on help volume.

   Help on help can be displayed in a general help window. However, a quick help dialog is recommended because its user interface is simpler, which is less intimidating to new users who commonly need help on help.

Example

The following program segment is part of a HelpRequestCB() function. Presumably, the USING_HELP constant is passed to the function because the user chose Using Help from the application's Help menu or chose the Help button in a quick help dialog.

This example assumes that the application never creates more than one Help On Help dialog and maintains its widget ID in a variable called onHelpDialog.

case USING_HELP:
   if (onHelpDialog == (Widget)NULL)
      {
         /* Get a quick help dialog for use as the ` help on help' dialog. */
         onHelpDialog = FetchHelpDialog (True);
 
        if (onHelpDialog == (Widget)NULL)
           /* We didn't get a dialog! Add your error handling code here. */
      }
 
   /* Set the proper volume and ID to display the home topic of
       the help on help volume. Also, set the dialog's title.   */
    ac = 0;   XtSetArg (al[ac], XmNtitle,  "Help On Help");     ac++;
    XtSetArg (al[ac], XmNhelpType,   DT_HELP_TYPE_TOPIC); ac++;
    XtSetArg (al[ac], XmNhelpVolume, "Help4Help");        ac++;
    XtSetArg (al[ac], XmNlocationId, "_hometopic");       ac++;
    XtSetValues (onHelpDialog, al, ac);
 
   /*  If the ` help on help' dialog is already managed, it might
        be in another workspace, so unmanage it.  */
    if (XtIsManaged (onHelpDialog))
      XtUnmanageChild (onHelpDialog);
 
   /* Manage the ` help on help' dialog. */
    XtManageChild (onHelpDialog);
 
   break;

To see how the rest of the HelpRequestCB() function might be structured, refer to the example in "To Add a Help Callback".

See Also

• "To Create a Quick Help Dialog"

• "To Display a Help Topic"