util/X86LINUX64/man/man3/Tk_DeleteErrorHandler.3

   1 '\"
   2 '\" Copyright (c) 1990 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH Tk_CreateErrorHandler 3 "" Tk "Tk Library Procedures"
   9 .\" The -*- nroff -*- definitions below are for supplemental macros used
  10 .\" in Tcl/Tk manual entries.
  11 .\"
  12 .\" .AP type name in/out ?indent?
  13 .\"     Start paragraph describing an argument to a library procedure.
  14 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  15 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  16 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  17 .\"     needed;  use .AS below instead)
  18 .\"
  19 .\" .AS ?type? ?name?
  20 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  21 .\"     name are examples of largest possible arguments that will be passed
  22 .\"     to .AP later.  If args are omitted, default tab stops are used.
  23 .\"
  24 .\" .BS
  25 .\"     Start box enclosure.  From here until next .BE, everything will be
  26 .\"     enclosed in one large box.
  27 .\"
  28 .\" .BE
  29 .\"     End of box enclosure.
  30 .\"
  31 .\" .CS
  32 .\"     Begin code excerpt.
  33 .\"
  34 .\" .CE
  35 .\"     End code excerpt.
  36 .\"
  37 .\" .VS ?version? ?br?
  38 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  39 .\"     of man pages.  The first argument is ignored and used for recording
  40 .\"     the version when the .VS was added, so that the sidebars can be
  41 .\"     found and removed when they reach a certain age.  If another argument
  42 .\"     is present, then a line break is forced before starting the sidebar.
  43 .\"
  44 .\" .VE
  45 .\"     End of vertical sidebar.
  46 .\"
  47 .\" .DS
  48 .\"     Begin an indented unfilled display.
  49 .\"
  50 .\" .DE
  51 .\"     End of indented unfilled display.
  52 .\"
  53 .\" .SO ?manpage?
  54 .\"     Start of list of standard options for a Tk widget. The manpage
  55 .\"     argument defines where to look up the standard options; if
  56 .\"     omitted, defaults to "options". The options follow on successive
  57 .\"     lines, in three columns separated by tabs.
  58 .\"
  59 .\" .SE
  60 .\"     End of list of standard options for a Tk widget.
  61 .\"
  62 .\" .OP cmdName dbName dbClass
  63 .\"     Start of description of a specific option.  cmdName gives the
  64 .\"     option's name as specified in the class command, dbName gives
  65 .\"     the option's name in the option database, and dbClass gives
  66 .\"     the option's class in the option database.
  67 .\"
  68 .\" .UL arg1 arg2
  69 .\"     Print arg1 underlined, then print arg2 normally.
  70 .\"
  71 .\" .QW arg1 ?arg2?
  72 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  73 .\"
  74 .\" .PQ arg1 ?arg2?
  75 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  76 .\"     (for trailing punctuation) and then a closing parenthesis.
  77 .\"
  78 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  79 .if t .wh -1.3i ^B
  80 .nr ^l \n(.l
  81 .ad b
  82 .\"     # Start an argument description
  83 .de AP
  84 .ie !"\\$4"" .TP \\$4
  85 .el \{\
  86 .   ie !"\\$2"" .TP \\n()Cu
  87 .   el          .TP 15
  88 .\}
  89 .ta \\n()Au \\n()Bu
  90 .ie !"\\$3"" \{\
  91 \&\\$1 \\fI\\$2\\fP (\\$3)
  92 .\".b
  93 .\}
  94 .el \{\
  95 .br
  96 .ie !"\\$2"" \{\
  97 \&\\$1  \\fI\\$2\\fP
  98 .\}
  99 .el \{\
 100 \&\\fI\\$1\\fP
 101 .\}
 102 .\}
 103 ..
 104 .\"     # define tabbing values for .AP
 105 .de AS
 106 .nr )A 10n
 107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 108 .nr )B \\n()Au+15n
 109 .\"
 110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 112 ..
 113 .AS Tcl_Interp Tcl_CreateInterp in/out
 114 .\"     # BS - start boxed text
 115 .\"     # ^y = starting y location
 116 .\"     # ^b = 1
 117 .de BS
 118 .br
 119 .mk ^y
 120 .nr ^b 1u
 121 .if n .nf
 122 .if n .ti 0
 123 .if n \l'\\n(.lu\(ul'
 124 .if n .fi
 125 ..
 126 .\"     # BE - end boxed text (draw box now)
 127 .de BE
 128 .nf
 129 .ti 0
 130 .mk ^t
 131 .ie n \l'\\n(^lu\(ul'
 132 .el \{\
 133 .\"     Draw four-sided box normally, but don't draw top of
 134 .\"     box if the box started on an earlier page.
 135 .ie !\\n(^b-1 \{\
 136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 137 .\}
 138 .el \}\
 139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 140 .\}
 141 .\}
 142 .fi
 143 .br
 144 .nr ^b 0
 145 ..
 146 .\"     # VS - start vertical sidebar
 147 .\"     # ^Y = starting y location
 148 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 149 .de VS
 150 .if !"\\$2"" .br
 151 .mk ^Y
 152 .ie n 'mc \s12\(br\s0
 153 .el .nr ^v 1u
 154 ..
 155 .\"     # VE - end of vertical sidebar
 156 .de VE
 157 .ie n 'mc
 158 .el \{\
 159 .ev 2
 160 .nf
 161 .ti 0
 162 .mk ^t
 163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 164 .sp -1
 165 .fi
 166 .ev
 167 .\}
 168 .nr ^v 0
 169 ..
 170 .\"     # Special macro to handle page bottom:  finish off current
 171 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 172 .\"     # page bottom macro.
 173 .de ^B
 174 .ev 2
 175 'ti 0
 176 'nf
 177 .mk ^t
 178 .if \\n(^b \{\
 179 .\"     Draw three-sided box if this is the box's first page,
 180 .\"     draw two sides but no top otherwise.
 181 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 183 .\}
 184 .if \\n(^v \{\
 185 .nr ^x \\n(^tu+1v-\\n(^Yu
 186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 187 .\}
 188 .bp
 189 'fi
 190 .ev
 191 .if \\n(^b \{\
 192 .mk ^y
 193 .nr ^b 2
 194 .\}
 195 .if \\n(^v \{\
 196 .mk ^Y
 197 .\}
 198 ..
 199 .\"     # DS - begin display
 200 .de DS
 201 .RS
 202 .nf
 203 .sp
 204 ..
 205 .\"     # DE - end display
 206 .de DE
 207 .fi
 208 .RE
 209 .sp
 210 ..
 211 .\"     # SO - start of list of standard options
 212 .de SO
 213 'ie '\\$1'' .ds So \\fBoptions\\fR
 214 'el .ds So \\fB\\$1\\fR
 215 .SH "STANDARD OPTIONS"
 216 .LP
 217 .nf
 218 .ta 5.5c 11c
 219 .ft B
 220 ..
 221 .\"     # SE - end of list of standard options
 222 .de SE
 223 .fi
 224 .ft R
 225 .LP
 226 See the \\*(So manual entry for details on the standard options.
 227 ..
 228 .\"     # OP - start of full description for a single option
 229 .de OP
 230 .LP
 231 .nf
 232 .ta 4c
 233 Command-Line Name:      \\fB\\$1\\fR
 234 Database Name:  \\fB\\$2\\fR
 235 Database Class: \\fB\\$3\\fR
 236 .fi
 237 .IP
 238 ..
 239 .\"     # CS - begin code excerpt
 240 .de CS
 241 .RS
 242 .nf
 243 .ta .25i .5i .75i 1i
 244 ..
 245 .\"     # CE - end code excerpt
 246 .de CE
 247 .fi
 248 .RE
 249 ..
 250 .\"     # UL - underline word
 251 .de UL
 252 \\$1\l'|0\(ul'\\$2
 253 ..
 254 .\"     # QW - apply quotation marks to word
 255 .de QW
 256 .ie '\\*(lq'"' ``\\$1''\\$2
 257 .\"" fix emacs highlighting
 258 .el \\*(lq\\$1\\*(rq\\$2
 259 ..
 260 .\"     # PQ - apply parens and quotation marks to word
 261 .de PQ
 262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 263 .\"" fix emacs highlighting
 264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 265 ..
 266 .\"     # QR - quoted range
 267 .de QR
 268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 269 .\"" fix emacs highlighting
 270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 271 ..
 272 .\"     # MT - "empty" string
 273 .de MT
 274 .QW ""
 275 ..
 276 .BS
 277 .SH NAME
 278 Tk_CreateErrorHandler, Tk_DeleteErrorHandler \- handle X protocol errors
 279 .SH SYNOPSIS
 280 .nf
 281 \fB#include <tk.h>\fR
 282 .sp
 283 Tk_ErrorHandler
 284 \fBTk_CreateErrorHandler\fR(\fIdisplay, error, request, minor, proc, clientData\fR)
 285 .sp
 286 \fBTk_DeleteErrorHandler\fR(\fIhandler\fR)
 287 .SH ARGUMENTS
 288 .AS "Tk_ErrorHandler" clientData
 289 .AP Display *display in
 290 Display whose errors are to be handled.
 291 .AP int error in
 292 Match only error events with this value in the \fIerror_code\fR
 293 field.  If \-1, then match any \fIerror_code\fR value.
 294 .AP int request in
 295 Match only error events with this value in the \fIrequest_code\fR
 296 field.  If \-1, then match any \fIrequest_code\fR value.
 297 .AP int minor in
 298 Match only error events with this value in the \fIminor_code\fR
 299 field.  If \-1, then match any \fIminor_code\fR value.
 300 .AP Tk_ErrorProc *proc in
 301 Procedure to invoke whenever an error event is received for
 302 \fIdisplay\fR and matches \fIerror\fR, \fIrequest\fR, and \fIminor\fR.
 303 NULL means ignore any matching errors.
 304 .AP ClientData clientData in
 305 Arbitrary one-word value to pass to \fIproc\fR.
 306 .AP Tk_ErrorHandler handler in
 307 Token for error handler to delete (return value from a previous
 308 call to \fBTk_CreateErrorHandler\fR).
 309 .BE
 310 .SH DESCRIPTION
 311 .PP
 312 \fBTk_CreateErrorHandler\fR arranges for a particular procedure
 313 (\fIproc\fR) to be called whenever certain protocol errors occur on a
 314 particular display (\fIdisplay\fR).  Protocol errors occur when
 315 the X protocol is used incorrectly, such as attempting to map a window
 316 that does not exist.  See the Xlib documentation for \fBXSetErrorHandler\fR
 317 for more information on the kinds of errors that can occur.
 318 For \fIproc\fR to be invoked
 319 to handle a particular error, five things must occur:
 320 .IP [1]
 321 The error must pertain to \fIdisplay\fR.
 322 .IP [2]
 323 Either the \fIerror\fR argument to \fBTk_CreateErrorHandler\fR
 324 must have been \-1, or the \fIerror\fR argument must match
 325 the \fIerror_code\fR field from the error event.
 326 .IP [3]
 327 Either the \fIrequest\fR argument to \fBTk_CreateErrorHandler\fR
 328 must have been \-1, or the \fIrequest\fR argument must match
 329 the \fIrequest_code\fR field from the error event.
 330 .IP [4]
 331 Either the \fIminor\fR argument to \fBTk_CreateErrorHandler\fR
 332 must have been \-1, or the \fIminor\fR argument must match
 333 the \fIminor_code\fR field from the error event.
 334 .IP [5]
 335 The protocol request to which the error pertains must have been
 336 made when the handler was active (see below for more information).
 337 .PP
 338 \fIProc\fR should have arguments and result that match the
 339 following type:
 340 .CS
 341 typedef int \fBTk_ErrorProc\fR(
 342         ClientData \fIclientData\fR,
 343         XErrorEvent *\fIerrEventPtr\fR);
 344 .CE
 345 The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
 346 argument given to \fBTcl_CreateErrorHandler\fR when the callback
 347 was created.  Typically, \fIclientData\fR points to a data
 348 structure containing application-specific information that is
 349 needed to deal with the error.  \fIErrEventPtr\fR is
 350 a pointer to the X error event.
 351 The procedure \fIproc\fR should return an integer value.  If it
 352 returns 0 it means that \fIproc\fR handled the error completely and there
 353 is no need to take any other action for the error.  If it returns
 354 non-zero it means \fIproc\fR was unable to handle the error.
 355 .PP
 356 If a value of NULL is specified for \fIproc\fR, all matching errors
 357 will be ignored:  this will produce the same result as if a procedure
 358 had been specified that always returns 0.
 359 .PP
 360 If more than more than one handler matches a particular error, then
 361 they are invoked in turn.  The handlers will be invoked in reverse
 362 order of creation:  most recently declared handler first.
 363 If any handler returns 0, then subsequent (older) handlers will
 364 not be invoked.  If no handler returns 0, then Tk invokes X's
 365 default error handler, which prints an error message and aborts the
 366 program.  If you wish to have a default handler that deals with errors
 367 that no other handler can deal with, then declare it first.
 368 .PP
 369 The X documentation states that
 370 .QW "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."
 371 This restriction applies to handlers declared by \fBTk_CreateErrorHandler\fR;
 372 disobey it at your own risk.
 373 .PP
 374 \fBTk_DeleteErrorHandler\fR may be called to delete a
 375 previously-created error handler.  The \fIhandler\fR argument
 376 identifies the error handler, and should be a value returned by
 377 a previous call to \fBTk_CreateEventHandler\fR.
 378 .PP
 379 A particular error handler applies to errors resulting
 380 from protocol requests generated between
 381 the call to \fBTk_CreateErrorHandler\fR and the call to
 382 \fBTk_DeleteErrorHandler\fR.  However, the actual callback
 383 to \fIproc\fR may not occur until after the \fBTk_DeleteErrorHandler\fR
 384 call, due to buffering in the client and server.
 385 If an error event pertains to
 386 a protocol request made just before calling \fBTk_DeleteErrorHandler\fR,
 387 then the error event may not have been processed
 388 before the \fBTk_DeleteErrorHandler\fR
 389 call.  When this situation arises, Tk will save information about
 390 the handler and
 391 invoke the handler's \fIproc\fR later when the error event
 392 finally arrives.
 393 If an application wishes to delete an error handler and know
 394 for certain that all relevant errors have been processed,
 395 it should first call \fBTk_DeleteErrorHandler\fR and then
 396 call \fBXSync\fR;  this will flush out any buffered requests and errors,
 397 but will result in a performance penalty because
 398 it requires communication to and from the X server.  After the
 399 \fBXSync\fR call Tk is guaranteed not to call any error
 400 handlers deleted before the \fBXSync\fR call.
 401 .PP
 402 For the Tk error handling mechanism to work properly, it is essential
 403 that application code never calls \fBXSetErrorHandler\fR directly;
 404 applications should use only \fBTk_CreateErrorHandler\fR.
 405 .SH KEYWORDS
 406 callback, error, event, handler