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

12 Providing Help on Help


Contents of Chapter:
Providing Help on Help
For Application Help
For Standalone Help
How Help on Help Is Found
Accessing Help on Help in an Application
To Set the helpOnHelpVolume Resource
To Provide a Using Help Command
To Display Help on Help
Writing Your Own Help on Help Volume
Required Entry Points
To Copy the Help4Help Source Files
This chapter explains how to incorporate a help volume into your application that describes the features of the Help System and how to use them. This help volume provides help on using the Help dialog boxes.


Providing Help on Help

Help on help tells users how to use the Help System. Specifically, it describes such tasks as using hyperlinks, navigating topics, using the index, and printing help topics. Normally, help on help is supplied as an individual help volume named Help4Help.

The Help4Help volume and its source files are included in the Developer's Toolkit. You can use the default volume "as is," or modify it for your application's design.

For Application Help

If you are writing application-specific help, there are two ways to ensure that your application has help on help for its own help dialogs:

For Standalone Help

If you are writing standalone help, you are probably relying on the Helpview program already being installed and ready to use. If this is the case, you don't have to worry about help on help because Helpview accesses the standard Help4Help volume by default.

How Help on Help Is Found

Each application that uses the Help System (including Helpview) has a helpOnHelpVolume resource that identifies a help volume to be accessed for help on help topics. For Helpview, this resource is set as follows:

DtHelpview*helpOnHelpVolume:  Help4Help

If you provide your own help on help volume, be sure to give it a unique name so it doesn't conflict with another help on help volume that may be installed on the system.


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.

Examples

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


Writing Your Own Help on Help Volume

If you need to provide your own help on help volume, you should start with the existing Help4Help volume and then make the necessary changes. All the source files used to write the Help4Help volume are provided in the /usr/dt/dthelp/help4help/C directory.

To prevent installation conflicts, name your help on help volume something other than Help4Help. Consider picking a name that is specific to your product. For example, if your application's help volume is Newapp, your help for help volume could be NewappH4H.

Required Entry Points

To ensure that context-sensitive help within a help dialog operates correctly, you must provide the following entry points (IDs) within your help on help volume. (These are already included in the Help4Help source files.)

ID
Topic Description

_hometopic
Displays an introduction to using the help system. This topic is displayed when you choose Using Help from the general help dialog's Help menu, or when you press F1 in a quick help dialog. (The ID _hometopic is created automatically by the <hometopic> element.)

_copyright
Displays the copyright and version information for the help on help volume. This topic is displayed when you choose Version from the general help dialog's Help menu. (The ID _copyright is created automatically by the <copyright> element.)

history
Displays a topic that describes how to use the History dialog. This topic is displayed when you choose Help or press F1 within the History dialog.

printing
Displays a topic describing how to use the Print dialog. This topic is displayed when you choose Help or press F1 within the Print dialog.

index-search
Displays a topic describing how to use the Index Search dialog. This topic is displayed when you choose Help or press F1 within the Index Search dialog.

volume-select
Displays a topic describing how to use the Search Volume Selection Dialog. This topic is displayed when you choose Help or press F1 within the Search Volume Selection Dialog.

To Copy the Help4Help Source Files

  1. Copy the entire /usr/dt/dthelp/help4help/C directory to a new working directory (new-dir) using a command like this:

     cp -r /usr/dt/dthelp/help4help/C new-dir 

    This creates new-dir and copies all the files and directories into it.

  2. To permit editing the files (which are copied as read only), change the permissions using a command like this:

     chmod -R u+w new-dir 

The Help4Help volume uses these HelpTag source files:

Also included is a control directory, where you run HelpTag to create the run-time help file. Graphics are stored in the control/graphics subdirectory.

Be sure to rename the Help4Help.htg file before running HelpTag. Your help on help volume should have a unique name to prevent conflicts with other help on help volumes.

Example

The following commands create a copy of the help on help volume and make its files writable. (Presumably the projects subdirectory already exists.)

cp -r /usr/dt/dthelp/help4help/C /users/dex/projects/NewHelp4Help 
chmod -R u+w /users/dex/projects/NewHelp4Help

To build a new version of the run-time help files, first ensure that the directory /usr/dt/bin is in your search path. Then, change to the new directory, rename the Help4Help.htg file, and run HelpTag:

cd /users/dex/projects/NewHelp4Help

mv Help4Help.htg NewH4H.htg dthelptag NewH4H

When the HelpTag software is done, you can display the new help on help volume using this command:

dthelpview -helpVolume NewH4H



Generated with CERN WebMaker