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) Predi-
cate
proce-
dure to
call to
filter
incoming
X
events.
NULL
means do
not
restrict
events
at all.
ClientData clientData (in) Arbi-
trary
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 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 pro-
cessed immediately, deferred until some later time (e.g.
when the event restriction is lifted), or discarded. Proc
Tk 1
Tk_RestrictEvents(3) Tk Library Procedures Tk_RestrictEvents(3)
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 prevClientDat-
aPtr 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 don't want to invoke any han-
dlers 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 2
