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

Tk                                                                                        Tk_RestrictEvents(3tk)