11.1 General Utilities

11.1.3 Error Messages

int MsgPrint(char *title, int icon, char *msg, int flags, FILE *log, ...);
 

This is the general function for presenting the user with an error or warning message.

title is a string that is used for the title of the error dialog.

icon is the ID of an icon to be displayed next to the title; the available icons are noteIcon, noteCautionIcon, cautionIcon, extraCautionIcon, stopIcon, and bombIcon. If icon has a priority low enough, then an option may be one so that the dialog is never presented to the user; in this case, a "default" button hit is simulated.

msg is the actual message to be presented to the user. An error ID can be included at the end of the string by placing it in curly braces (e.g. "Error... {E1}" is an error strng with ID "E1").

flags determines which buttons will be available and which button is the default. It may also designate that an alternate button name is being passed in after the required parameters. flags should be the sum of one or more the following constants:

ALLOW_EXIT - Allows the Exit button to be hit.
ALLOW_EXTRA - Allows the Extra button to be hit.
ALLOW_CANCEL - Allows the Cancel button to be hit.
ALLOW_OK- Allows the OK button to be hit.

EXIT_DEFAULT - Makes Exit the default button.
EXTRA_DEFAULT - MakesExtra the default button.
CANCEL_DEFAULT - Makes Cancel the default button.
OK_DEFAULT - Makes OK the default button.

RENAME_EXIT - Rename the Exit button.*
RENAME_EXTRA - Rename the Extra button.*
RENAME_CANCEL - Rename the Cancel button.*
RENAME_OK - Rename the OK button.*

SET_SKIPPED - Set the button to be "hit" if the dialog is not displayed.*

USE_EVENT_PROC - Replace the standard event loop.*

NULLIFY_CANCEL - Don't call the standard cancel routine if Cancel is hit.

Constants marked by an asterisk (*) above require extra parameters to be passed after the log parameter. If multiple extra parameters are passed in, they should be ordered according to how the flags are ordered in the above list. The RENAME_... flags require that a string be passed in for the new button name; SET_SKIPPED requires one of the four return values of MsgPrint() (see below); USE_EVENT_PROC requires a function pointer with prototype void func(int *) which should return every time the user hits something in the dialog, placing the item ID in *hit.

log should be LogFP if the error and the user's response should be recorded in the log file, or NULL if it should not.

MsgPrint() returns MSG_EXTRA, MSG_OK, or MSG_CANCEL, depending on which button the user hit. MSG_CANCEL will only be returned if the NULLIFY_CANCEL flag is on; otherwise, the standrad cancel routine will be called, which will generally not return control to the caller of MsgPrint().

extern char err_msg[ERR_MSG_BUF_SIZE];
#define ERR_MSG_BUF_SIZE 256
 

err_msg is available for temporary use to compose error message strings.

Generated with CERN WebMaker