Introduction to the Error Manager
In order to provide a standard error processing mechanism that can accept errors from inside and outside of the YAAF libraries, the Error Manager defines a new error handling class which provides the mechanism for throwing errors and for indicating to the user that an error occured.
Error objects defined by the Error Manager have a value which indicates the type of error that occured, and a virtual method used to display the error message to the user. This allows the YAAF libraries to catch the error and process it without intervention from the application which threw the error.
The Error Manager also defines several routines which are used to help facilitate throwing errors, as well as presenting caution and warning alerts. And the Error Manager has several built-in dialogs so that errors can be presented with minimal application support.
The routines and classes which make up the error manager are all defined in <XError.h>.
Using The Error Manager
When an error is displayed by the error manager, it displays an error window with a short error message an a long error message (or explanation). Errors are internally stored in an error resource which is automatically built by the error compiler CompileMessages. Internally errors are refered to by a 4-byte error code; the top 2 bytes give the resource ID of the error resource, and the lower two bytes is the index into that error resource.
Defining Error Messages
The errors for YAAF are stored in a resource, 'EMsg' #128. Application error messages may be stored in any other error message resource number. Error message resources are built by creating a text file with the messages, with the following format:
/* errors.m * * Error messages for my application */ 129 "Test Application" { { "Generic Error", "A generic error has occured in the application. " "Please contact the developer." } { "Unable to open file", "Unable to open file #1S; perhaps it's already open " "by another application?" } }
This defines an error resource with two error messages. The format of the above is as follows:
ErrorResource = ErrorResourceID ErrorName '{' ErrorList '}'
ErrorResourceID = <integer> ; The resource ID of the resource to generate
ErrorName = <string> ; The error strings
ErrorList = Error ErrorList
Error = '{' <string> ',' <string> <string> ... '}'(For long message strings, you can add multiple strings without a trailing comma. The strings are concatenated.)
To compile these messages into an error message resource, you would run CompileMessages. (Please note that the CompileMessages utility is currently only available on the Macintosh, though the source kit is provided with the YAAF distribution. Future versions will contain Windows and Unix versions of the CompileMessages utily. Our long term plan is to provide a "constructor" which contains a GUI-based editor.)
To run CompileMessages:
1. Double-click CompileMessages icon.
2. On the command line, enter the name of the error message file, along with any option switches. For example, to compile for all target environments, type:-muvw errors.m
This will generate files for all target platforms. For the Macintosh, this will generate a file 'errors.r' which contains the rez declaration of the 'EMsg' resource. For Windows, this will generate an 'errors.rc' file containing the RC resource declaration. For X, this generates a file 'errors.rdata' which is later compiled into a '.cpp' file containing all of the 'resources' for the application.
Both the title and description error strings are passed through yformat, described on the Data Utilities page, to insert the optional arguments.
Throwing Errors
Once errors have been defined and compiled into a resource, you may refer to a particular error message using the MAKEDWORD macro, with the high order word refering to the resource number given above, and the low order word the 0-based index of the error message.
To throw an error, you can use the XGPostError class. The constructor of this class takes the error message, and optional parameters. Thus, to throw an 'open file' error as defined in the error messages above, you would write:
throw XGPostError(MAKEDWORD(129,1),"myfile.txt");
Other methods and mechanisms exist for throwing error messages, for displaying error messages, and for aborting operations.
Catching Errors
Once an error is thrown, it is eventually caught, either by your own code or by the YAAF library. Exceptions are caught at the bottom of an event loop, or at the end of a thread (in the thread classes). In no circumstance should the YAAF library allow an exception to propagate back through the host operating system.
If you are catching errors, you can handle them by displaying the specified error message by calling the XGError::DisplayError() method. This takes whatever error message was passed to the error handler code and puts up a dialog box showing the error. For example:
try { ... some operation ... } catch (XGError &e) { e.DisplayError(); // displays alert for this error ... // other processing }
Error Manager Classes
The error manager defines the following classes in <XError.h>:
Root abstract class for all error management within the YAAF library.
The 'abort' class which has an empty DisplayError method. This is used for aborting an operation through the error processing mechanism without raising an alert.
This is the standard error handler class used for throwing exceptions.
This class is used for throwing MacOS errors. Only defined on the Macintosh, this takes an OSErr value.
This class is used for throwing errors from the Windows API. Only defined on Microsoft Windows version of the API.
This class is used for throwing errors in Unix. Only defined in the X version of the YAAF library.
Error Manager Routines
The following routines are defined in <XError.h>:
void Error(unsigned long msgID,...)
Error manager routines; this displays the error alert specified immediately rather than throwing an exception, and is useful for routines which handle the error immediately.
bool Caution(unsigned long msgID,...)
This puts up a caution dialog with an 'OK' and 'Cancel' button; returns 'true' if 'Cancel' is pressed.
void Warning(unsigned long msgID,...)
Warning message; this puts up a warning dialog and returns immediately.
void Message(const char *title, const char *smsg, const char *lmsg,...)
This displays a message box with the specified title, short message string, long message string formatted with the optional arguments specified.
Assertion Macros
The following macros are defined in <XError.h>:
If the 'condition' is false, this throws an error message which displays the condition, and the file and line where the assertion failure took place.