NAME

       Tk_RestrictEvents - filter and selectively delay X events

SYNOPSIS

       #include <tk.h>

       Tk_RestrictProc *
       Tk_RestrictEvents(proc, arg, prevArgPtr)

ARGUMENTS

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

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

       ClientData *prevArgPtr (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 arg,
                      XEvent *eventPtr);
       The  arg  argument  is a copy of the arg 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 prevArgPtr 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