NAME

       Tk_CreateGenericHandler, Tk_DeleteGenericHandler - associ­
       ate procedure callback with all X events


SYNOPSIS

       #include <tk.h>

       Tk_CreateGenericHandler(proc, clientData)

       Tk_DeleteGenericHandler(proc, clientData)


ARGUMENTS

       Tk_GenericProc   *proc        (in)      Procedure       to
                                               invoke    whenever
                                               any X event occurs
                                               on any display.

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



DESCRIPTION

       Tk_CreateGenericHandler arranges for proc to be invoked in
       the future whenever any X event occurs.  This mechanism is
       not  intended  for dispatching X events on windows managed
       by Tk (you should use Tk_CreateEventHandler for this  pur­
       pose).  Tk_CreateGenericHandler is intended for other pur­
       poses, such as tracing X events, monitoring events on win­
       dows  not  owned by Tk, accessing X-related libraries that
       were not originally designed for use with Tk, and so on.

       The callback to proc will be made by Tk_HandleEvent;  this
       mechanism  only  works  in  programs  that dispatch events
       through Tk_HandleEvent (or  through  other  Tk  procedures
       that   call   Tk_HandleEvent,  such  as  Tk_DoOneEvent  or
       Tk_MainLoop).

       Proc should have arguments and result that match the  type
       Tk_GenericProc:
              typedef int Tk_GenericProc(
                ClientData clientData,
                XEvent *eventPtr);
       The  clientData parameter to proc is a copy of the client­
       Data argument given to  Tk_CreateGenericHandler  when  the
       callback  was  created.  Typically, clientData points to a
       data structure containing application-specific information
       about  how to handle events.  EventPtr is a pointer to the
       X event.

       non-zero return value indicates that the event is  not  to
       be  handled further; that is, proc has done all processing
       that is to be allowed for the event.

       If there are multiple generic event handlers, each one  is
       called  for  each  event,  in the order in which they were
       established.

       Tk_DeleteGenericHandler may be called to delete  a  previ­
       ously-created generic event handler:  it deletes each han­
       dler it finds that matches the proc and  clientData  argu­
       ments.   If  no  such handler exists, then Tk_DeleteGener­
       icHandler returns without  doing  anything.   Although  Tk
       supports  it,  it's  probably a bad idea to have more than
       one callback with the same proc and clientData  arguments.

       Establishing  a  generic  event  handler  does  nothing to
       ensure that the process will actually receive the X events
       that the handler wants to process.  For example, it is the
       caller's responsibility to invoke XSelectInput  to  select
       the desired events, if that is necessary.


KEYWORDS

       bind, callback, event, handler