TkCreateErrorHandler(3) Tk Library Procedures TkCreateErrorHandler(3)

NAME
       TkCreateErrorHandler, TkDeleteErrorHandler - handle X protocol errors

SYNOPSIS
       ##iinncclluuddee <>

       TkErrorHandler
       TTkkCCrreeaatteeEErrrroorrHHaannddlleerr(display, error, request, minor, proc, clientData)

       TTkkDDeelleetteeEErrrroorrHHaannddlleerr(handler)

AARRGGUUMMEENNTTSS
       Display           *display     (in)      Display whose errors are to be
                                                handled.

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

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

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

       TkErrorProc      *proc        (in)      Procedure to  invoke  whenever
                                                an error event is received for
                                                display  and  matches   error,
                                                request,   and   minor.   NULL
                                                means  ignore   any   matching
                                                errors.

       ClientData        clientData   (in)      Arbitrary  one-word  value  to
                                                pass to proc.

       TkErrorHandler   handler      (in)      Token  for  error  handler  to
                                                delete  (return  value  from a
                                                previous call to  TTkkCCrreeaatteeEErr-
                                                rroorrHHaannddlleerr).



DESCRIPTION
       TTkkCCrreeaatteeEErrrroorrHHaannddlleerr  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 incor-
       rectly, such as attempting to map a window that doesn't exist.  See the
       Xlib  documentation  for  XXSSeettEErrrroorrHHaannddlleerr  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 TTkkCCrreeaatteeEErrrroorrHHaannddlleerr must have
              been -1, or the error argument must match the  errorcode  field
              from the error event.

       [3]    Either  the  request argument to TTkkCCrreeaatteeEErrrroorrHHaannddlleerr must have
              been -1, or the request argument  must  match  the  requestcode
              field from the error event.

       [4]    Either  the  minor  argument  to TTkkCCrreeaatteeEErrrroorrHHaannddlleerr must have
              been -1, or the minor argument must match the  minorcode  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  informa-
              tion).

       Proc should have arguments and result that match the following type:
              typedef int TkErrorProc(
                ClientData clientData,
                XErrorEvent *errEventPtr);
       The  clientData  parameter to proc is a copy of the clientData argument
       given to TTccllCCrreeaatteeEErrrroorrHHaannddlleerr when the callback was  created.   Typi-
       cally,  clientData  points  to a data structure containing application-
       specific  information  that  is  needed  to  deal   with   the   error.
       ErrEventPtr  is  a  pointer  to  the X error event.  The procedure proc
       should return an integer value.  If it returns 0  it  means  that  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 han-
       dler returns 0, then subsequent (older) handlers will not  be  invoked.
       If  no  handler  returns 0, then Tk invokes X'es default error handler,
       which prints an error message and aborts the program.  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  restric-
       tion  applies to handlers declared by TTkkCCrreeaatteeEErrrroorrHHaannddlleerr; disobey it
       at your own risk.

       TTkkDDeelleetteeEErrrroorrHHaannddlleerr may be  called  to  delete  a  previously-created
       error  handler.  The handler argument identifies the error handler, and
       should be a value returned by a previous call to TTkkCCrreeaatteeEEvveennttHHaannddlleerr.

       A  particular  error  handler applies to errors resulting from protocol
       requests generated between the call to  TTkkCCrreeaatteeEErrrroorrHHaannddlleerr  and  the
       call  to  TTkkDDeelleetteeEErrrroorrHHaannddlleerr.   However, the actual callback to proc
       may not occur  until  after  the  TTkkDDeelleetteeEErrrroorrHHaannddlleerr  call,  due  to
       buffering  in  the  client and server.  If an error event pertains to a
       protocol request made just before calling  TTkkDDeelleetteeEErrrroorrHHaannddlleerr,  then
       the  error  event  may  not have been processed before the TTkkDDeelleetteeEErr-
       rroorrHHaannddlleerr 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 pro-
       cessed, it should first call TTkkDDeelleetteeEErrrroorrHHaannddlleerr and then call XXSSyynncc;
       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 XXSSyynncc call Tk is guaranteed not to call any
       error handlers deleted before the XXSSyynncc call.

       For the Tk error handling mechanism to work properly, it  is  essential
       that  application  code never calls XXSSeettEErrrroorrHHaannddlleerr directly; applica-
       tions should use only TTkkCCrreeaatteeEErrrroorrHHaannddlleerr.


KKEEYYWWOORRDDSS
       callback, error, event, handler



Tk                                                    TkCreateErrorHandler(3)