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

Accessing Help on Help in an Application

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

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.


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.


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 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.


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.

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

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

See Also