Tk_RestrictEvents(3)

Tk_RestrictEvents(3)  Tk Library Procedures  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)                        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 argu-
                                                       ment    to
                                                       previous
                                                       restrict
                                                       procedure.
_________________________________________________________________

DESCRIPTION

     This procedure is useful in certain situations where  appli-
     cations  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  immedi-
     ately,  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);

Tk                        Last change:                          1

Tk_RestrictEvents(3)  Tk Library Procedures  Tk_RestrictEvents(3)

     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 process-
     ing.   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  prevClientDa-
     taPtr to return information about the current event restric-
     tion  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 chang-
     ing 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 per-
     forming  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                        Last change:                          2