manpagez: man pages & more
man RestrictEv(3)
Home | html | info | man
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, arg, prevArgPtr)


ARGUMENTS

       Tk_RestrictProc *proc (in)                 Predicate  procedure to call
                                                  to filter incoming X events.
                                                  NULL  means  do not restrict
                                                  events at all.

       ClientData arg (in)                        Arbitrary argument  to  pass
                                                  to proc.

       ClientData *prevArgPtr (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,  Tcl_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 arg,
                      XEvent *eventPtr);
       The  arg  argument is a copy of the arg 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
       Tcl_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_DIS-
       CARD_EVENT,  then  the  event  will be removed from the event queue and
       discarded without being processed.

       Tk_RestrictEvents uses its return value and prevArgPtr to return infor-
       mation  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
       do not 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  Tcl_DoOneEvent  to
       retrieve the desired event(s).


KEYWORDS

       delay, event, filter, restriction



Tk                                                        Tk_RestrictEvents(3)

tk 8.6.10 - Generated Sun Jan 5 07:38:15 CST 2020
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.