NAME
Tk_CreateErrorHandler, Tk_DeleteErrorHandler - handle X protocol errorsSYNOPSIS
#include <tk.h>Tk_ErrorHandler
Tk_CreateErrorHandler(display, error, request, minor, proc, clientData)
Tk_DeleteErrorHandler(handler)
ARGUMENTS
- Display *display (in)
- Display whose errors are to be handled.
- int error (in)
- Match only error events with this value in the error_codefield. If -1, then match any error_code value.
- int request (in)
- Match only error events with this value in the request_codefield. If -1, then match any request_code value.
- int minor (in)
- Match only error events with this value in the minor_codefield. If -1, then match any minor_code value.
- Tk_ErrorProc *proc (in)
- Procedure to invoke whenever an error event is received fordisplay and matches error, request, and minor.NULL means ignore any matching errors.
- ClientData clientData (in)
- Arbitrary one-word value to pass to proc.
- Tk_ErrorHandler handler (in)
- Token for error handler to delete (return value from a previouscall to Tk_CreateErrorHandler).
DESCRIPTION
Tk_CreateErrorHandler arranges for a particular procedure(proc) to be called whenever certain protocol errors occur on aparticular display (display). Protocol errors occur whenthe X protocol is used incorrectly, such as attempting to map a windowthat doesn't exist. See the Xlib documentation for XSetErrorHandlerfor more information on the kinds of errors that can occur.For proc to be invokedto handle a particular error, five things must occur:- [1]
- The error must pertain to display.
- [2]
- Either the error argument to Tk_CreateErrorHandlermust have been -1, or the error argument must matchthe error_code field from the error event.
- [3]
- Either the request argument to Tk_CreateErrorHandlermust have been -1, or the request argument must matchthe request_code field from the error event.
- [4]
- Either the minor argument to Tk_CreateErrorHandlermust have been -1, or the minor argument must matchthe minor_code field from the error event.
- [5]
- The protocol request to which the error pertains must have beenmade when the handler was active (see below for more information).
Proc should have arguments and result that match thefollowing type:
typedef int Tk_ErrorProc(ClientData clientData,XErrorEvent *errEventPtr);The clientData parameter to proc is a copy of the clientDataargument given to Tcl_CreateErrorHandler when the callbackwas created. Typically, clientData points to a datastructure containing application-specific information that isneeded to deal with the error. ErrEventPtr isa pointer to the X error event.The procedure proc should return an integer value. If itreturns 0 it means that proc handled the error completely and thereis no need to take any other action for the error. If it returnsnon-zero it means proc was unable to handle the error.
If a value of NULL is specified for proc, all matching errorswill be ignored: this will produce the same result as if a procedurehad been specified that always returns 0.
If more than more than one handler matches a particular error, thenthey are invoked in turn. The handlers will be invoked in reverseorder of creation: most recently declared handler first.If any handler returns 0, then subsequent (older) handlers willnot be invoked. If no handler returns 0, then Tk invokes X'esdefault error handler, which prints an error message and aborts theprogram. If you wish to have a default handler that deals with errorsthat no other handler can deal with, then declare it first.
The X documentation states that ``the error handler should not callany functions (directly or indirectly) on the display that willgenerate protocol requests or that will look for input events.''This restriction applies to handlers declared by Tk_CreateErrorHandler;disobey it at your own risk.
Tk_DeleteErrorHandler may be called to delete apreviously-created error handler. The handler argumentidentifies the error handler, and should be a value returned bya previous call to Tk_CreateEventHandler.
A particular error handler applies to errors resultingfrom protocol requests generated betweenthe call to Tk_CreateErrorHandler and the call toTk_DeleteErrorHandler. However, the actual callbackto proc may not occur until after the Tk_DeleteErrorHandlercall, due to buffering in the client and server.If an error event pertains toa protocol request made just before calling Tk_DeleteErrorHandler,then the error event may not have been processedbefore the Tk_DeleteErrorHandlercall. When this situation arises, Tk will save information aboutthe handler andinvoke the handler's proc later when the error eventfinally arrives.If an application wishes to delete an error handler and knowfor certain that all relevant errors have been processed,it should first call Tk_DeleteErrorHandler and thencall XSync; this will flush out any buffered requests and errors,but will result in a performance penalty becauseit requires communication to and from the X server. After theXSync call Tk is guaranteed not to call any errorhandlers deleted before the XSync call.
For the Tk error handling mechanism to work properly, it is essentialthat application code never calls XSetErrorHandler directly;applications should use only Tk_CreateErrorHandler.
KEYWORDS
callback, error, event, handlerCopyright © 1990 The Regents of the University of California.Copyright © 1994-1996 Sun Microsystems, Inc.Copyright © 1995-1997 Roger E. Critchlow Jr.
