NAME

       Tk_RestrictEvents - filter and selectively delay X events

SYNOPSIS

       #include <tk.h>

       Tk_RestrictProc *
       Tk_RestrictEvents(proc, clientData, prevClientDataPtr)

ARGUMENTS

       Tk_RestrictProc *proc (in)                        Predicate  procedure  to  call to filter
                                                         incoming X events.  NULL  means  do  not
                                                         restrict events at all.

       ClientData clientData (in)                        Arbitrary argument to pass to proc.

       ClientData *prevClientDataPtr (out)               Pointer  to  place  to  save argument to
                                                         previous restrict procedure.
_________________________________________________________________

DESCRIPTION

       This procedure is useful in certain situations where applications  are  only  prepared  to
       receive  certain  X  events.   After Tk_RestrictEvents is called, Tk_DoOneEvent (and hence
       Tk_MainLoop) will filter X input events through proc.   Proc  indicates  whether  a  given
       event  is to be processed immediately, deferred until some later time (e.g. when the event
       restriction is lifted), or discarded.  Proc is a procedure with arguments and result  that
       match the type Tk_RestrictProc:
              typedef Tk_RestrictAction Tk_RestrictProc(
                  ClientData clientData,
                  XEvent *eventPtr);
       The clientData argument is a copy of the clientData passed to Tk_RestrictEvents; it may be
       used to provide proc with information it needs to filter events.  The eventPtr  points  to
       an   event   under  consideration.   Proc  returns  a  restrict  action  (enumerated  type
       Tk_RestrictAction) that indicates what Tk_DoOneEvent should do with  the  event.   If  the
       return  value  is  TK_PROCESS_EVENT,  then  the event will be handled immediately.  If the
       return value is TK_DEFER_EVENT, then the event will be left on the event queue  for  later
       processing.   If the return value is TK_DISCARD_EVENT, then the event will be removed from
       the event queue and discarded without being processed.

       Tk_RestrictEvents uses its return value and prevClientDataPtr to return information  about
       the  current event restriction procedure (a NULL return value means there are currently no
       restrictions).  These values may be used to restore the previous  restriction  state  when
       there is no longer any need for the current restriction.

       There  are very few places where Tk_RestrictEvents is needed.  In most cases, the best way
       to restrict events is by changing the bindings with the bind Tcl  command  or  by  calling
       Tk_CreateEventHandler   and   Tk_DeleteEventHandler   from   C.    The  main  place  where
       Tk_RestrictEvents must be used is when performing synchronous actions (for example, if you
       need to wait for a particular event to occur on a particular window but you do not want to
       invoke any handlers for any other events).  The “obvious” solution in these situations  is
       to  call  XNextEvent or XWindowEvent, but these procedures cannot be used because Tk keeps
       its  own  event  queue  that  is  separate  from  the  X  event  queue.    Instead,   call
       Tk_RestrictEvents  to  set  up  a  filter, then call Tk_DoOneEvent to retrieve the desired
       event(s).

KEYWORDS

       delay, event, filter, restriction