# E.S.O. - VLT project 
#
# "@(#) $Id: ErrorHandler.man3,v 1.1.1.1 2009/03/31 14:11:52 cguirao Exp $" 
#
# This file is processed by the ESO/VLT docDoManPages command to
# produce a man page in nroff, TeX and MIF formats. 
# See docDoManPages(1) for a description of the input format.
# 
# who             when       what
# --------------  ---------  ----------------------------------------
# Allan Brighton  20 Jul 95  Created

NAME
ErrorHandler - A C++ class for managing Tk Error Handlers for
                    catching X errors

SYNOPSIS
#include "ErrorHandler.h"

/* 
 * This class is used to install and remove Tk X error handlers
 * in order to catch X errors and deal with them.
 */
class ErrorHandler {
...
public:
    // constructor
    ErrorHandler(Display* display, int verbose = 1);

    // destructor
    ~ErrorHandler();

    // static version of error handler, called from Tk
    static int errorProc(ClientData clientData, XErrorEvent *errEventPtr);

    // install/remove an X error handler
    int install();
    int remove();
    
    // return 1 if errors occurred
    int errors();

    // reset the error flag
    int reset();
};

DESCRIPTION
This class is used to install and remove Tk X error handlers in order
to catch X errors and deal with them. 

Note that checking for X errors requires calling XSync(3X) to flush
the X event queue. This could have performance and other implications,
but is necessary due to the nature of the X window system client
server communication (error messages could be delayed otherwise).

To use this class, you only need to declare a (local) variable of type
ErrorHandler before doing something that might cause X errors. When
you want to check if any X errors occured, you can call the "errors()"
method.  It returns true if any X errors occured:

    {
	ErrorHandler errorHandler(display, verbose_flag);
	// ... (something that might produce X errors)
	if (errorHandler.errors()) {
		// errors occurred ... 
	}
    }

The constructor installs the error handler and the destructor removes
it - the destructor for local variables is called automatically at the
end of the block or function where it is declared, and then the error
handler is automatically removed.

Since installing the error handler causes all X errors to be ignored,
it probably only makes sense to install one before certain operations
and remove it immediately afterwards (unless you are prepared to
handle X errors at any point in the application...).

METHODS
static int errorProc(ClientData clientData, XErrorEvent *errEventPtr)
	Static version of error handler, called from Tk.

int install();
int remove();
	Install or remove the X error handler.
    
int errors()
	Return 1 if errors occurred. A call to XSync() is made here to
	avoid delays due to X buffering.

int reset();
	Reset the error flag so that the "errors()" method will return
	0.

SEE ALSO
	CrtErrHdlr

------------------------------------------------------------------------------

