Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

CentOS 7.0 - man page for tk_deleteerrorhandler (centos section 3)

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 previous call to Tk_CreateErrorHandler).
_________________________________________________________________

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 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 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 han-
	      dler 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_Cre-
       ateErrorHandler	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 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  indirectly)	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 argument identifies the error handler, and should be a value returned by a  previ-
       ous 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_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_DeleteErrorHandler, 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  performance  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_CreateEr-
       rorHandler.

KEYWORDS
       callback, error, event, handler

Tk									 Tk_CreateErrorHandler(3)


All times are GMT -4. The time now is 01:25 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password