Common Desktop Environment: Programmer's Guide

# 3 Displaying Errors from
Your Application

Contents of Chapter:

How to Present Error Messages

Information to Present in Error Dialogs

Linking Message Dialogs to Online Help

Recovery Routines

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

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

Generated with CERN WebMaker