Displaying Help Topics

When a help request is made, the application determines what help topic to display. It then creates (if necessary) and manages a help dialog, and sets the appropriate resources to display a help topic.

Most requests display help topics that are part of the application's help volume. But, the Help System's help dialogs are also capable of displaying man pages, text files, and simple text strings.

The Help System's help dialogs are based exclusively on Xt Intrinsics and OSF/Motif programming, so you change the values within a help dialog just like any other widget: by setting resources.

The DtNhelpType resource determines what type of information is displayed. It can be set to any of these values:

• DtHELP_TYPE_TOPIC for displaying normal help topics that are part of a help volume. The volume is specified by setting the DtNhelpVolume resource; the topic is specified by setting the DtNlocationId resource.

• DtHELP_TYPE_STRING for displaying a string supplied by the application. Automatic word wrap is disabled, so line breaks are observed as specified in the string. The string is specified by setting the DtNstringData resource.

• DtHELP_TYPE_DYNAMIC_STRING for displaying a string supplied by the application, using word wrap to format the text. Line breaks within the string are used to separate paragraphs. The string is specified by setting the DtNstringData resource.

• DtHELP_TYPE_FILE for displaying a text file. The name of the file to be displayed is specified by setting the DtNhelpFile resource.

• DtHELP_TYPE_MAN_PAGE for displaying a manual reference page (man page) in a help dialog. The man page to be displayed is specified by setting the DtNmanPage resource.

These values are defined in the Help.h file.

See Also

• Chapter 9, Creating and Managing Help Dialog Boxes

To Display a Help Topic

1. Create a help dialog.

2. Set the following resources for the help dialog:

   DtNhelpType

   Set to DtHELP_TYPE_TOPIC.

   DtNhelpVolume

   Set to the volume name for your application.

   DtNlocationId

   Set to the topic ID that you want to display.

   You can also set other values for the dialog, such as its size and title.

3. Manage the dialog using XtManageChild().

Example

This program segment displays a topic with the ID getting-started in the volume MyVolume.

ac = 0;

XtSetArg (al[ac], DtNhelpType,   DtHELP_TYPE_TOPIC);  ac++;
 XtSetArg (al[ac], DtNhelpVolume,  "MyVolume");         ac++;
 XtSetArg (al[ac], DtNlocationId,  "getting-started");  ac++;
 XtSetArg (al[ac], DtNcolumns,    40);                  ac++;
 XtSetArg (al[ac], DtNrows,       12);                  ac++;
 XtSetValues (helpDialog, al, ac);
 XtManageChild (helpDialog);

If the help volume MyVolume is not registered, then a complete path to the MyVolume.sdl file is required for the value of DtNhelpVolume.

To Display a String of Text

1. Create a quick help dialog.

   You can use a general help dialog to display string data, but this isn't recommended because most of its features do not apply to string data.

2. Set the following resources for the help dialog:

   DtNhelpType

   Set to DtHELP_TYPE_DYNAMIC_STRING (if you want word wrap enabled) or DtHELP_TYPE_STRING (if you want the line breaks within the string to be maintained) .

   DtNstringData

   Set to the string you want to display. A copy of the string is kept internally, so you need not maintain your copy of it.

   You can also set other values for the dialog, such as its size and title.

3. Manage the dialog using XtManageChild().

Example

This program segment displays a string stored in the variable descriptionString.

ac = 0;
 XtSetArg (al[ac], DtNhelpType,   DtHELP_TYPE_DYNAMIC_STRING); ac++;
 XtSetArg (al[ac], DtNstringData, (char *)descriptionString);   ac++;
 XtSetValues (quickHelpDialog, al, ac);
 XtManageChild (quickHelpDialog);

If the string is no longer needed within the application, the memory can be freed, because the help dialog makes its own copy of the data.

 XtFree (descriptionString);

To Display a Text File

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

   You can use a general help dialog to display a text file, but this isn't recommended because most of its features are useful only for standard help topics.

2. Set the following resources for the help dialog:

   DtNhelpType

   Set to DtHELP_TYPE_FILE..

   DtNhelpFile

   Set to the file name you want to display. If the file is not in the application's current directory, provide a path to the file.

   You can also set other values for the dialog, such as its size and title. In particular, you might want to set the width to 80 columns, which is the standard width for text files.

3. Manage the dialog using XtManageChild().

Example

The following program segment displays a file named /tmp/printer.list. It also sets the size of the dialog to better suit a text file.

ac = 0;
 XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_FILE);      ac++;
 XtSetArg (al[ac], DtNhelpFile,  "/tmp/printer.list");  ac++;
 XtSetArg (al[ac], DtNcolumns,  80);                    ac++;
 XtSetArg (al[ac], DtNrows,     20);                    ac++;
 XtSetValues (quickHelpDialog, al, ac);
 XtManageChild (quickHelpDialog);

To Display a Man Page

1. Create a quick help dialog.

   You can use a general help dialog to display a man page, but this isn't recommended because most of its features are useful only with standard help topics.

2. Set the following resources for the help dialog:

   DtNhelpType

   Set to DtHELP_TYPE_MAN_PAGE.

   DtNmanPage

   Set to the name of the man page. The value of this resource is passed directly to the system man command. So, to specify a particular section of a man page, precede the man page name by a section number, just as you would if you were typing the man command conventionally.

   You can also set other values for the dialog, such as its size and title.

3. Manage the dialog using XtManageChild().

Example

The following program segment displays the man page for the grep command. It also sets the size of the dialog to better suit a man page.

ac = 0;
 XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_MAN_PAGE);  ac++;
 XtSetArg (al[ac], DtNmanPage,   "grep");                ac++;
 XtSetArg (al[ac], DtNcolumns,  80);                     ac++;
 XtSetArg (al[ac], DtNrows,     20);                     ac++;
 XtSetValues (quickHelpDialog, al, ac);
 XtManageChild (quickHelpDialog);