Tk_RestrictEvents(3tk)

______________________________________________________________________________

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 pre-
                                                         vious restrict proce-
                                                         dure.
_________________________________________________________________

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  consid-
       eration.   Proc  returns a restrict action (enumerated type Tk_Restric-
       tAction) 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_Dele-
       teEventHandler 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
       don't  want  to invoke any handlers for any other events).  The ``obvi-
       ous'' solution in these situations is to call  XNextEvent  or  XWindow-
       Event,  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(3)