diff options
Diffstat (limited to 'doc/RestrictEv.3')
| -rw-r--r-- | doc/RestrictEv.3 | 81 |
1 files changed, 81 insertions, 0 deletions
diff --git a/doc/RestrictEv.3 b/doc/RestrictEv.3 new file mode 100644 index 0000000..5daaac4 --- /dev/null +++ b/doc/RestrictEv.3 @@ -0,0 +1,81 @@ +'\" +'\" Copyright (c) 1990 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) RestrictEv.3 1.13 96/08/27 13:21:55 +'\" +.so man.macros +.TH Tk_RestrictEvents 3 "" Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_RestrictEvents \- filter and selectively delay X events +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_RestrictProc * +\fBTk_RestrictEvents\fR(\fIproc, clientData, prevClientDataPtr\fR) +.SH ARGUMENTS +.AS Tk_RestrictProc **prevClientDataPtr +.AP Tk_RestrictProc *proc in +Predicate procedure to call to filter incoming X events. +NULL means do not restrict events at all. +.AP ClientData clientData in +Arbitrary argument to pass to \fIproc\fR. +.AP ClientData *prevClientDataPtr out +Pointer to place to save argument to previous restrict procedure. +.BE + +.SH DESCRIPTION +.PP +This procedure is useful in certain situations where applications +are only prepared to receive certain X events. After +\fBTk_RestrictEvents\fR is called, \fBTk_DoOneEvent\fR (and +hence \fBTk_MainLoop\fR) will filter X input events through +\fIproc\fR. \fIProc\fR 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. +\fIProc\fR +is a procedure with arguments and result that match +the type \fBTk_RestrictProc\fR: +.CS +typedef Tk_RestrictAction Tk_RestrictProc( + ClientData \fIclientData\fR, + XEvent *\fIeventPtr\fR); +.CE +The \fIclientData\fR argument is a copy of the \fIclientData\fR passed +to \fBTk_RestrictEvents\fR; it may be used to provide \fIproc\fR with +information it needs to filter events. The \fIeventPtr\fR points to +an event under consideration. \fIProc\fR returns a restrict action +(enumerated type \fBTk_RestrictAction\fR) that indicates what +\fBTk_DoOneEvent\fR should do with the event. If the return value is +\fBTK_PROCESS_EVENT\fR, then the event will be handled immediately. +If the return value is \fBTK_DEFER_EVENT\fR, then the event will be +left on the event queue for later processing. If the return value is +\fBTK_DISCARD_EVENT\fR, then the event will be removed from the event +queue and discarded without being processed. +.PP +\fBTk_RestrictEvents\fR uses its return value and \fIprevClientDataPtr\fR +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. +.PP +There are very few places where \fBTk_RestrictEvents\fR is needed. +In most cases, the best way to restrict events is by changing the +bindings with the \fBbind\fR Tcl command or by calling +\fBTk_CreateEventHandler\fR and \fBTk_DeleteEventHandler\fR from C. +The main place where \fBTk_RestrictEvents\fR 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 handlers for any other events). The ``obvious'' +solution in these situations is to call \fBXNextEvent\fR or +\fBXWindowEvent\fR, but these procedures cannot be used because +Tk keeps its own event queue that is separate from the X event +queue. Instead, call \fBTk_RestrictEvents\fR to set up a filter, +then call \fBTk_DoOneEvent\fR to retrieve the desired event(s). +.SH KEYWORDS +delay, event, filter, restriction |