trusty (3) Tk_RestrictEvents.3tk.gz

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 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, 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 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_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 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