restrictev(3Tk)

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.

     char              *arg           (in)      Arbitrary argument to pass to
                                                proc.

     char              **prevArgPtr   (in/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 or deferred until some later time (e.g. when the event
     restriction is lifted).  Proc is a standard X predicate procedure, of the
     sort passed to XCheckIfEvent.  It must have arguments and result that
     match the type Tk_RestrictProc:
          typedef Bool Tk_RestrictProc(
               Display *display,
               XEvent *eventPtr,
               char *arg);
     The display argument to proc is the display from which eventPtr was
     received, and eventPtr points to an event under consideration.  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.  Proc
     must return True or False.  True means the event should be processed
     immediately and False means the event should not be processed now, but
     should be saved for some later time.

     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.  Please use
     it only where it is absolutely necessary.  If only a local restriction is
     needed, it can probably be achieved more cleanly by changing event-to-Tcl
     bindings or by calling Tk_DeleteEventHandler.


KEYWORDS
     delay, event, filter, restriction