1Tk_RestrictEvents(3)         Tk Library Procedures        Tk_RestrictEvents(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tk_RestrictEvents - filter and selectively delay X events
9

SYNOPSIS

11       #include <tk.h>
12
13       Tk_RestrictProc *
14       Tk_RestrictEvents(proc, arg, prevArgPtr)
15

ARGUMENTS

17       Tk_RestrictProc *proc (in)                 Predicate  procedure to call
18                                                  to filter incoming X events.
19                                                  NULL  means  do not restrict
20                                                  events at all.
21
22       ClientData arg (in)                        Arbitrary argument  to  pass
23                                                  to proc.
24
25       ClientData *prevArgPtr (out)               Pointer to place to save ar‐
26                                                  gument to previous  restrict
27                                                  procedure.
28______________________________________________________________________________
29

DESCRIPTION

31       This  procedure  is useful in certain situations where applications are
32       only prepared to receive certain X events.  After Tk_RestrictEvents  is
33       called,  Tcl_DoOneEvent  (and  hence  Tk_MainLoop)  will filter X input
34       events through proc.  Proc indicates whether a given  event  is  to  be
35       processed  immediately,  deferred  until some later time (e.g. when the
36       event restriction is lifted), or discarded.  Proc is a  procedure  with
37       arguments and result that match the type Tk_RestrictProc:
38              typedef Tk_RestrictAction Tk_RestrictProc(
39                      ClientData arg,
40                      XEvent *eventPtr);
41       The  arg  argument is a copy of the arg passed to Tk_RestrictEvents; it
42       may be used to provide proc with information it needs to filter events.
43       The  eventPtr  points  to an event under consideration.  Proc returns a
44       restrict action (enumerated type Tk_RestrictAction) that indicates what
45       Tcl_DoOneEvent  should  do  with  the  event.   If  the return value is
46       TK_PROCESS_EVENT, then the event will be handled immediately.   If  the
47       return  value  is  TK_DEFER_EVENT,  then  the event will be left on the
48       event queue for later processing.   If  the  return  value  is  TK_DIS‐
49       CARD_EVENT,  then  the  event  will be removed from the event queue and
50       discarded without being processed.
51
52       Tk_RestrictEvents uses its return value and prevArgPtr to return infor‐
53       mation  about  the  current  event restriction procedure (a NULL return
54       value means there are currently no restrictions).  These values may  be
55       used  to restore the previous restriction state when there is no longer
56       any need for the current restriction.
57
58       There are very few places where Tk_RestrictEvents is needed.   In  most
59       cases, the best way to restrict events is by changing the bindings with
60       the bind Tcl command or by calling Tk_CreateEventHandler  and  Tk_Dele‐
61       teEventHandler  from C.  The main place where Tk_RestrictEvents must be
62       used is when performing synchronous actions (for example, if  you  need
63       to  wait for a particular event to occur on a particular window but you
64       do not want to invoke any handlers for any other events).   The  “obvi‐
65       ous”  solution  in  these  situations is to call XNextEvent or XWindow‐
66       Event, but these procedures cannot be used because  Tk  keeps  its  own
67       event  queue  that  is  separate from the X event queue.  Instead, call
68       Tk_RestrictEvents to set up a filter, then call Tcl_DoOneEvent  to  re‐
69       trieve the desired event(s).
70

KEYWORDS

72       delay, event, filter, restriction
73
74
75
76Tk                                                        Tk_RestrictEvents(3)
Impressum