91 lines
3.6 KiB
Groff
91 lines
3.6 KiB
Groff
|
'\"
|
||
|
|
'\" Copyright (c) 1990 The Regents of the University of California.
|
||
|
|
'\" All rights reserved.
|
||
|
|
'\"
|
||
|
|
'\" Permission is hereby granted, without written agreement and without
|
||
|
|
'\" license or royalty fees, to use, copy, modify, and distribute this
|
||
|
|
'\" documentation for any purpose, provided that the above copyright
|
||
|
|
'\" notice and the following two paragraphs appear in all copies.
|
||
|
|
'\"
|
||
|
|
'\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
|
||
|
|
'\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
|
||
|
|
'\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
|
||
|
|
'\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||
|
|
'\"
|
||
|
|
'\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
|
||
|
|
'\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
|
||
|
|
'\" AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
|
||
|
|
'\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
|
||
|
|
'\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
|
||
|
|
'\"
|
||
|
|
'\" $Header: /user6/ouster/wish/man/RCS/RestrictEv.3,v 1.6 93/04/01 09:41:55 ouster Exp $ SPRITE (Berkeley)
|
||
|
|
'\"
|
||
|
|
.so man.macros
|
||
|
|
.HS Tk_RestrictEvents tkc
|
||
|
|
.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, arg, prevArgPtr\fR)
|
||
|
|
.SH ARGUMENTS
|
||
|
|
.AS Tk_RestrictProc **prevArgPtr
|
||
|
|
.AP Tk_RestrictProc *proc in
|
||
|
|
Predicate procedure to call to filter incoming X events.
|
||
|
|
NULL means do not restrict events at all.
|
||
|
|
.AP char *arg in
|
||
|
|
Arbitrary argument to pass to \fIproc\fR.
|
||
|
|
.AP char **prevArgPtr in/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 or deferred until some
|
||
|
|
later time (e.g. when the event restriction is lifted). \fIProc\fR
|
||
|
|
is a standard X predicate procedure, of the sort passed to
|
||
|
|
\fBXCheckIfEvent\fR. It must have arguments and result that match
|
||
|
|
the type \fBTk_RestrictProc\fR:
|
||
|
|
.nf
|
||
|
|
.RS
|
||
|
|
typedef Bool Tk_RestrictProc(
|
||
|
|
.RS
|
||
|
|
Display *\fIdisplay\fR,
|
||
|
|
XEvent *\fIeventPtr\fR,
|
||
|
|
char *\fIarg\fR);
|
||
|
|
.RE
|
||
|
|
.RE
|
||
|
|
.fi
|
||
|
|
The \fIdisplay\fR argument to \fIproc\fR is the display from which
|
||
|
|
\fIeventPtr\fR was received, and \fIeventPtr\fR points to an event
|
||
|
|
under consideration. The \fIarg\fR argument is a copy of the \fIarg\fR
|
||
|
|
passed to \fBTk_RestrictEvents\fR; it may be used to provide
|
||
|
|
\fIproc\fR with information it needs to filter events. \fIProc\fR
|
||
|
|
must return \fBTrue\fR or \fBFalse\fR. \fBTrue\fR means the event
|
||
|
|
should be processed immediately and \fBFalse\fR means the event
|
||
|
|
should not be processed now, but should be saved for some later
|
||
|
|
time.
|
||
|
|
.PP
|
||
|
|
\fBTk_RestrictEvents\fR uses its return value and \fIprevArgPtr\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.
|
||
|
|
Please use it only where it is absolutely necessary.
|
||
|
|
If only a local restriction is needed, it can probably
|
||
|
|
be achieved more cleanly by changing event-to-Tcl bindings or by
|
||
|
|
calling \fBTk_DeleteEventHandler\fR.
|
||
|
|
|
||
|
|
.SH KEYWORDS
|
||
|
|
delay, event, filter, restriction
|