TkRestrictEvents(3) Tk Library Procedures TkRestrictEvents(3)

NAME
       TkRestrictEvents - filter and selectively delay X events

SYNOPSIS
       ##iinncclluuddee <>

       TkRestrictProc *
       TTkkRReessttrriiccttEEvveennttss(proc, clientData, prevClientDataPtr)

AARRGGUUMMEENNTTSS
       TkRestrictProc   *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 TTkkRReessttrriiccttEEvveennttss is
       called, TTkkDDooOOnneeEEvveenntt (and  hence  TTkkMMaaiinnLLoooopp)  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 TTkkRReessttrriiccttPPrroocc:
              typedef TkRestrictAction TkRestrictProc(
                ClientData clientData,
                XEvent *eventPtr);
       The  clientData  argument  is  a  copy  of  the  clientData  passed  to
       TTkkRReessttrriiccttEEvveennttss;  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 TTkkRReessttrriicc-
       ttAAccttiioonn) that indicates what TTkkDDooOOnneeEEvveenntt should do  with  the  event.
       If the return value is TTKKPPRROOCCEESSSSEEVVEENNTT, then the event will be handled
       immediately.  If the return value is  TTKKDDEEFFEERREEVVEENNTT,  then  the  event
       will  be  left  on the event queue for later processing.  If the return
       value is TTKKDDIISSCCAARRDDEEVVEENNTT, then the event  will  be  removed  from  the
       event queue and discarded without being processed.

       TTkkRReessttrriiccttEEvveennttss 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 TTkkRReessttrriiccttEEvveennttss is needed.  In most
       cases, the best way to restrict events is by changing the bindings with
       the  bbiinndd  Tcl command or by calling TTkkCCrreeaatteeEEvveennttHHaannddlleerr and TTkkDDeellee-
       tteeEEvveennttHHaannddlleerr from C.  The main place where TTkkRReessttrriiccttEEvveennttss 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  XXNNeexxttEEvveenntt  or  XXWWiinnddooww-
       EEvveenntt,  but  these  procedures  cannot be used because Tk keeps its own
       event queue that is separate from the X  event  queue.   Instead,  call
       TTkkRReessttrriiccttEEvveennttss  to  set  up  a  filter,  then  call TTkkDDooOOnneeEEvveenntt to
       retrieve the desired event(s).

KKEEYYWWOORRDDSS
       delay, event, filter, restriction



Tk                                                        TkRestrictEvents(3)