NAME

       Tk_CreateErrorHandler,  Tk_DeleteErrorHandler  -  handle X
       protocol errors


SYNOPSIS

       #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_code field.
                                                If -1, then match
                                                any    error_code
                                                value.

       int               request      (in)      Match only  error
                                                events  with this
                                                value   in    the
                                                request_code
                                                field.   If   -1,
                                                then   match  any
                                                request_code
                                                value.

       int               minor        (in)      Match  only error
                                                events with  this
                                                value    in   the
                                                minor_code field.
                                                If -1, then match
                                                any    minor_code
                                                value.

       Tk_ErrorProc      *proc        (in)      Procedure      to
                                                invoke   whenever
                                                an error event is
                                                received for dis­
                                                play  and matches
                                                error,   request,
                                                and  minor.  NULL
                                                means ignore  any
                                                matching  errors.
                                                word   value   to
                                                pass to proc.

       Tk_ErrorHandler   handler      (in)      Token  for  error
                                                handler to delete
                                                (return     value
                                                from  a  previous
                                                call  to  Tk_Cre­
                                                ateErrorHandler).
_________________________________________________________________



DESCRIPTION

       Tk_CreateErrorHandler arranges for a particular  procedure
       (proc) to be called whenever certain protocol errors occur
       on a particular display (display).  Protocol errors  occur
       when  the X protocol is used incorrectly, such as attempt­
       ing to map a window that doesn't exist.  See the Xlib doc­
       umentation  for  XSetErrorHandler  for more information on
       the kinds of errors  that  can  occur.   For  proc  to  be
       invoked  to  handle  a  particular error, five things must
       occur:

       [1]    The error must pertain to display.

       [2]    Either the error argument to  Tk_CreateErrorHandler
              must have been -1, or the error argument must match
              the error_code field from the error event.

       [3]    Either the request argument  to  Tk_CreateErrorHan­
              dler  must  have  been  -1, or the request argument
              must match the request_code field  from  the  error
              event.

       [4]    Either  the minor argument to Tk_CreateErrorHandler
              must have been -1, or the minor argument must match
              the minor_code field from the error event.

       [5]    The  protocol  request  to which the error pertains
              must have been made when  the  handler  was  active
              (see below for more information).

       Proc  should have arguments and result that match the fol­
       lowing type:
              typedef int Tk_ErrorProc(
                ClientData clientData,
                XErrorEvent *errEventPtr);
       The clientData parameter to proc is a copy of the  client­
       Data  argument  given  to  Tcl_CreateErrorHandler when the
       callback was created.  Typically, clientData points  to  a
       data structure containing application-specific information
       that is needed to deal with the error.  ErrEventPtr  is  a
       proc  handled the error completely and there is no need to
       take any other action for the error.  If it  returns  non-
       zero it means proc was unable to handle the error.

       If  a  value  of  NULL is specified for proc, all matching
       errors will be ignored:  this will produce the same result
       as  if  a procedure had been specified that always returns
       0.

       If more than more than one handler  matches  a  particular
       error,  then  they are invoked in turn.  The handlers will
       be invoked in reverse order of  creation:   most  recently
       declared  handler  first.   If any handler returns 0, then
       subsequent (older) handlers will not be  invoked.   If  no
       handler returns 0, then Tk invokes X'es default error han­
       dler, which prints an error message and  aborts  the  pro­
       gram.   If  you  wish to have a default handler that deals
       with errors that no other  handler  can  deal  with,  then
       declare it first.

       The X documentation states that ``the error handler should
       not call any functions (directly  or  indirectly)  on  the
       display  that will generate protocol requests or that will
       look for input events.''  This restriction applies to han­
       dlers  declared  by  Tk_CreateErrorHandler;  disobey it at
       your own risk.

       Tk_DeleteErrorHandler may be called  to  delete  a  previ­
       ously-created error handler.  The handler argument identi­
       fies the error handler, and should be a value returned  by
       a previous call to Tk_CreateEventHandler.

       A  particular  error  handler  applies to errors resulting
       from protocol  requests  generated  between  the  call  to
       Tk_CreateErrorHandler  and  the call to Tk_DeleteErrorHan­
       dler.  However, the actual callback to proc may not  occur
       until after the Tk_DeleteErrorHandler call, due to buffer­
       ing in the client and server.  If an error event  pertains
       to  a  protocol  request made just before calling Tk_Dele­
       teErrorHandler, then the error event  may  not  have  been
       processed  before  the  Tk_DeleteErrorHandler  call.  When
       this situation arises, Tk will save information about  the
       handler and invoke the handler's proc later when the error
       event finally arrives.  If an application wishes to delete
       an  error  handler  and know for certain that all relevant
       errors have been processed, it should first call  Tk_Dele­
       teErrorHandler  and  then call XSync;  this will flush out
       any buffered requests and errors, but  will  result  in  a
       performance  penalty  because it requires communication to
       and from the X server.  After the XSync call Tk is guaran­
       teed  not  to  call  any error handlers deleted before the
       XSync call.
       is  essential  that  application  code never calls XSetEr­
       rorHandler directly; applications should use only  Tk_Cre­
       ateErrorHandler.



KEYWORDS

       callback, error, event, handler