'\"'\" 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 NAMETk_RestrictEvents \- filter and selectively delay X events.SH SYNOPSIS.nf\fB#include <tk.h>\fR.spTk_RestrictProc *\fBTk_RestrictEvents\fR(\fIproc, clientData, prevClientDataPtr\fR).SH ARGUMENTS.AS Tk_RestrictProc **prevClientDataPtr.AP Tk_RestrictProc *proc inPredicate procedure to call to filter incoming X events.NULL means do not restrict events at all..AP ClientData clientData inArbitrary argument to pass to \fIproc\fR..AP ClientData *prevClientDataPtr outPointer to place to save argument to previous restrict procedure..BE.SH DESCRIPTION.PPThis procedure is useful in certain situations where applicationsare only prepared to receive certain X events.  After\fBTk_RestrictEvents\fR is called, \fBTk_DoOneEvent\fR (andhence \fBTk_MainLoop\fR) will filter X input events through\fIproc\fR.  \fIProc\fR indicates whether agiven event is to be processed immediately, deferred until somelater time (e.g. when the event restriction is lifted), or discarded.\fIProc\fRis a procedure with arguments and result that matchthe type \fBTk_RestrictProc\fR:.CStypedef Tk_RestrictAction Tk_RestrictProc(	ClientData \fIclientData\fR,	XEvent *\fIeventPtr\fR);.CEThe \fIclientData\fR argument is a copy of the \fIclientData\fR passedto \fBTk_RestrictEvents\fR; it may be used to provide \fIproc\fR withinformation it needs to filter events.  The \fIeventPtr\fR points toan 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 beleft on the event queue for later processing.  If the return value is\fBTK_DISCARD_EVENT\fR, then the event will be removed from the eventqueue and discarded without being processed..PP\fBTk_RestrictEvents\fR uses its return value and \fIprevClientDataPtr\fRto 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 statewhen there is no longer any need for the current restriction..PPThere are very few places where \fBTk_RestrictEvents\fR is needed.In most cases, the best way to restrict events is by changing thebindings 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 whenperforming synchronous actions (for example, if you need to waitfor a particular event to occur on a particular window but you don'twant 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 becauseTk keeps its own event queue that is separate from the X eventqueue.  Instead, call \fBTk_RestrictEvents\fR to set up a filter,then call \fBTk_DoOneEvent\fR to retrieve the desired event(s)..SH KEYWORDSdelay, event, filter, restriction