Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

Tk_CreateErrorHandler(3)                    Tk Library Procedures                   Tk_CreateErrorHandler(3)



____________________________________________________________________________________________________________

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
                                                display  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  pre-vious previous
                                                vious call to Tk_CreateErrorHandler).
____________________________________________________________________________________________________________

DESCRIPTION
       Tk_CreateErrorHandler arranges for a particular procedure (proc) to be called whenever certain proto-col protocol
       col errors occur on a particular display (display).  Protocol errors occur when  the  X  protocol  is
       used incorrectly, such as attempting to map a window that does not exist.  See the Xlib documentation
       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_CreateErrorHandler must have been -1, or the  request  argu-ment argument
              ment 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 following type:
              typedef int Tk_ErrorProc(
                  ClientData clientData,
                  XErrorEvent *errEventPtr);
       The clientData parameter to proc is a copy of the clientData argument given to Tcl_CreateErrorHandler
       when the callback was created.  Typically, clientData points to a data structure containing  applica-tion-specific application-specific
       tion-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
       handler  returns  0,  then subsequent (older) handlers will not be invoked.  If no handler returns 0,
       then Tk invokes X's 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  indi-rectly) indirectly)
       rectly)  on  the  display  that  will generate 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 a previously-created error handler.  The handler argu-ment argument
       ment identifies the error handler, and should be a value returned  by  a  previous  call  to  Tk_Cre-ateEventHandler. Tk_CreateEventHandler.
       ateEventHandler.

       A  particular  error handler applies to errors resulting from protocol requests generated between the
       call to Tk_CreateErrorHandler and the call to Tk_DeleteErrorHandler.  However, the actual callback to
       proc  may  not  occur  until after the Tk_DeleteErrorHandler call, due to buffering in the client and
       server.  If an error event pertains to a protocol request made just before calling Tk_DeleteErrorHan-dler, Tk_DeleteErrorHandler,
       dler,  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_DeleteErrorHandler
       and then call XSync;  this will flush out any buffered requests and errors, but will result in a per-formance performance
       formance penalty because it requires communication to and from the X server.  After the XSync call Tk
       is guaranteed not to call any error handlers deleted before the XSync call.

       For  the  Tk  error  handling mechanism to work properly, it is essential that application code never
       calls XSetErrorHandler directly; applications should use only Tk_CreateErrorHandler.


KEYWORDS
       callback, error, event, handler



Tk                                                                                  Tk_CreateErrorHandler(3)