Tk_RestrictEvents(3)

_________________________________________________________________

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)      Predi-
                                                         cate
                                                         proce-
                                                         dure  to
                                                         call  to
                                                         filter
                                                         incoming
                                                         X
                                                         events.
                                                         NULL
                                                         means do
                                                         not
                                                         restrict
                                                         events
                                                         at  all.

       ClientData        clientData            (in)      Arbi-
                                                         trary
                                                         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 pro-
       cessed 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 prevClientDat-
       aPtr   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 don't want to  invoke  any  han-
       dlers  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