1Tk_CreateErrorHandler(3)     Tk Library Procedures    Tk_CreateErrorHandler(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tk_CreateErrorHandler, Tk_DeleteErrorHandler - handle X protocol errors
9

SYNOPSIS

11       #include <tk.h>
12
13       Tk_ErrorHandler
14       Tk_CreateErrorHandler(display, error, request, minor, proc, clientData)
15
16       Tk_DeleteErrorHandler(handler)
17

ARGUMENTS

19       Display *display (in)                    Display whose errors are to be
20                                                handled.
21
22       int error (in)                           Match only error  events  with
23                                                this  value  in the error_code
24                                                field.  If -1, then match  any
25                                                error_code value.
26
27       int request (in)                         Match  only  error events with
28                                                this value in the request_code
29                                                field.   If -1, then match any
30                                                request_code value.
31
32       int minor (in)                           Match only error  events  with
33                                                this  value  in the minor_code
34                                                field.  If -1, then match  any
35                                                minor_code value.
36
37       Tk_ErrorProc *proc (in)                  Procedure  to  invoke whenever
38                                                an error event is received for
39                                                display   and  matches  error,
40                                                request,  and   minor.    NULL
41                                                means   ignore   any  matching
42                                                errors.
43
44       ClientData clientData (in)               Arbitrary  one-word  value  to
45                                                pass to proc.
46
47       Tk_ErrorHandler handler (in)             Token  for  error  handler  to
48                                                delete (return  value  from  a
49                                                previous  call to Tk_CreateEr‐
50                                                rorHandler).
51______________________________________________________________________________
52

DESCRIPTION

54       Tk_CreateErrorHandler arranges for a particular procedure (proc) to  be
55       called  whenever  certain protocol errors occur on a particular display
56       (display).  Protocol errors occur when the X protocol  is  used  incor‐
57       rectly,  such  as  attempting to map a window that does not exist.  See
58       the Xlib documentation for XSetErrorHandler for more information on the
59       kinds  of  errors  that  can occur.  For proc to be invoked to handle a
60       particular error, five things must occur:
61
62       [1]    The error must pertain to display.
63
64       [2]    Either the error argument  to  Tk_CreateErrorHandler  must  have
65              been  -1,  or the error argument must match the error_code field
66              from the error event.
67
68       [3]    Either the request argument to Tk_CreateErrorHandler  must  have
69              been  -1,  or  the  request argument must match the request_code
70              field from the error event.
71
72       [4]    Either the minor argument  to  Tk_CreateErrorHandler  must  have
73              been  -1,  or the minor argument must match the minor_code field
74              from the error event.
75
76       [5]    The protocol request to which the error pertains must have  been
77              made  when  the  handler was active (see below for more informa‐
78              tion).
79
80       Proc should have arguments and result that match the following type:
81              typedef int Tk_ErrorProc(
82                      ClientData clientData,
83                      XErrorEvent *errEventPtr);
84       The clientData parameter to proc is a copy of the  clientData  argument
85       given  to  Tcl_CreateErrorHandler when the callback was created.  Typi‐
86       cally, clientData points to a data  structure  containing  application-
87       specific   information   that   is  needed  to  deal  with  the  error.
88       ErrEventPtr is a pointer to the X  error  event.   The  procedure  proc
89       should  return  an  integer  value.  If it returns 0 it means that proc
90       handled the error completely and there is no need  to  take  any  other
91       action  for the error.  If it returns non-zero it means proc was unable
92       to handle the error.
93
94       If a value of NULL is specified for proc, all matching errors  will  be
95       ignored:   this will produce the same result as if a procedure had been
96       specified that always returns 0.
97
98       If more than more than one handler matches  a  particular  error,  then
99       they  are  invoked  in  turn.   The handlers will be invoked in reverse
100       order of creation:  most recently declared handler first.  If any  han‐
101       dler  returns  0, then subsequent (older) handlers will not be invoked.
102       If no handler returns 0, then Tk invokes  X's  default  error  handler,
103       which  prints  an error message and aborts the program.  If you wish to
104       have a default handler that deals with errors that no other handler can
105       deal with, then declare it first.
106
107       The  X documentation states that “the error handler should not call any
108       functions (directly or indirectly) on the display  that  will  generate
109       protocol  requests  or that will look for input events.”  This restric‐
110       tion applies to handlers declared by Tk_CreateErrorHandler; disobey  it
111       at your own risk.
112
113       Tk_DeleteErrorHandler  may  be  called  to  delete a previously-created
114       error handler.  The handler argument identifies the error handler,  and
115       should be a value returned by a previous call to Tk_CreateEventHandler.
116
117       A  particular  error  handler applies to errors resulting from protocol
118       requests generated between the call to  Tk_CreateErrorHandler  and  the
119       call  to  Tk_DeleteErrorHandler.   However, the actual callback to proc
120       may not occur  until  after  the  Tk_DeleteErrorHandler  call,  due  to
121       buffering  in  the  client and server.  If an error event pertains to a
122       protocol request made just before calling  Tk_DeleteErrorHandler,  then
123       the  error  event  may  not have been processed before the Tk_DeleteEr‐
124       rorHandler call.  When this situation arises, Tk will save  information
125       about  the  handler  and invoke the handler's proc later when the error
126       event finally arrives.  If an application wishes  to  delete  an  error
127       handler  and  know  for certain that all relevant errors have been pro‐
128       cessed, it should first call Tk_DeleteErrorHandler and then call XSync;
129       this  will  flush out any buffered requests and errors, but will result
130       in a performance penalty because it requires communication to and  from
131       the  X  server.   After the XSync call Tk is guaranteed not to call any
132       error handlers deleted before the XSync call.
133
134       For the Tk error handling mechanism to work properly, it  is  essential
135       that  application  code never calls XSetErrorHandler directly; applica‐
136       tions should use only Tk_CreateErrorHandler.
137

KEYWORDS

139       callback, error, event, handler
140
141
142
143Tk                                                    Tk_CreateErrorHandler(3)
Impressum