Displaying Errors from Your Application

Users running your application expect messages to be displayed in message footers, error dialogs, or warning dialogs, with further explanations available in online help when appropriate. Applications in the Common Desktop Environment follow a common model for presenting error messages and warnings.

• How to Present Error Messages

• Information to Present in Error Dialogs

• Linking Message Dialogs to Online Help

• Recovery Routines

How to Present Error Messages

Because of the way message text is handled, users may not see messages from your application unless you display them in a dialog, footer, or elsewhere in the user interface.

In CDE, such messages are directed to log files that a casual user may not routinely examine. Use the following rules when deciding where to tell users about warnings, messages, and error conditions:

• If the message is informational, display the text in the message footer of the application; for example, "MyDoc file copied."

• If the message is about an error or serious warning--a problem where an operation important to the user has failed--display an error dialog or warning dialog.

Information to Present in Error Dialogs

A good error dialog or warning dialog gives the user the following information:

• What happened (from the user's point of view)

• Why it happened, in simple language that the user can relate to the current task and environment

• How to fix the problem

If the information cannot be presented in four or five lines of the error dialog, consider adding a help button to the dialog and link it to a topic in the help volume for your application.

For more information on writing messages, see the Common Desktop Environment: Internationalization 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:

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

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

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

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

Recovery Routines

If a recovery routine exists for an error condition, consider adding a Retry button to the dialog. For example, if a file could not be copied because the system had insufficient disk space, you might offer a Recopy option in the dialog that users could choose once they have corrected a disk space or permissions problem.