Solaris Common Desktop Environment: Programmer's Guide

Linking Message Dialogs to Online Help

In cases where additional background information is required, or where it takes more than four or five lines of a dialog to explain an error fully, you should add a button that links the user to online help.

Adding online help for a dialog is a straightforward task. Once you have decided that a particular dialog is a candidate for online help, do the following:

Choose a unique ID for the error help.

This ID provides the link to the online help text. IDs should be 64 characters or less; for example, DiskSpaceError.

Create the dialog and add a help callback.

Use the XmCreateErrorDialog() convenience function for error messages and XmCreateWarningDialog() for warnings, adding the help callback as follows:
```
XtAddCallback(dialog, XmNhelpCallback,
	helpfn, "ID");
```
In this example, helpfn is a help function you have created to manage the help dialog, and the string "ID" is the ID you chose for the error message (for example, DiskSpaceError). In your help function, set the XmNlocationId resource to the value of ID. The /usr/dt/examples/dthelp directory contains examples of how to set up such a help function.

For detailed information about creating and managing help dialog widgets, see the Common Desktop Environment: Help System Author's and Programmer's Guide.

Write a corresponding help section for the error message.

Document the message in the "messages" chapter of your help volume. In the help source document, you should have a separate section for each message, and the ID= attribute at the beginning of the section should match the ID you chose in your code for the error.

For example, in the s1 section heading, the ID is DiskSpaceError.

When the user's system has insufficient disk space, the error message the user sees from the following heading is "Could Not Save File."
```
 <s1 ID=DiskSpaceError>Could Not Save File <\s1>
```
Note that by convention, the text of the section heading should correspond closely to the text in the error dialog.

Rebuild the help file.

The new help section for the error message becomes active as soon as you rebuild the help file (using the dthelptag program) and recompile your application.

For information about writing and building online help, see the Common Desktop Environment: Help System Author's and Programmer's Guide.