144 lines
5.5 KiB
Groff
144 lines
5.5 KiB
Groff
'\"
|
|
'\" Copyright (c) 1990-1992 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/DoOneEvent.3,v 1.8 93/04/01 09:41:17 ouster Exp $ SPRITE (Berkeley)
|
|
'\"
|
|
.so man.macros
|
|
.HS Tk_DoOneEvent tkc
|
|
.BS
|
|
.SH NAME
|
|
Tk_DoOneEvent, Tk_MainLoop, Tk_HandleEvent \- wait for events and
|
|
invoke event handlers
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tk.h>\fR
|
|
.sp
|
|
int
|
|
.VS
|
|
\fBTk_DoOneEvent\fR(\fIflags\fR)
|
|
.VE
|
|
.sp
|
|
\fBTk_MainLoop\fR()
|
|
.sp
|
|
\fBTk_HandleEvent\fR(\fIeventPtr\fR)
|
|
.SH ARGUMENTS
|
|
.AS XEvent *eventPtr
|
|
.AP int flags in
|
|
.VS
|
|
This parameter is normally zero. It may be an OR-ed combination
|
|
of any of the following flag bits: TK_X_EVENTS, TK_FILE_EVENTS,
|
|
TK_TIMER_EVENTS, TK_IDLE_EVENTS, TK_ALL_EVENTS, or TK_DONT_WAIT.
|
|
.VE
|
|
.AP XEvent *eventPtr in
|
|
Pointer to X event to dispatch to relevant handler(s).
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
These three procedures are responsible for waiting for events
|
|
and dispatching to event handlers created with the procedures
|
|
\fBTk_CreateEventHandler\fR, \fBTk_CreateFileHandler\fR,
|
|
\fBTk_CreateTimerHandler\fR, and \fBTk_DoWhenIdle\fR.
|
|
\fBTk_DoOneEvent\fR is the key procedure. It waits for a single
|
|
event of any sort to occur, invokes the handler(s) for that
|
|
event, and then returns. \fBTk_DoOneEvent\fR first checks
|
|
for X events and file-related events; if one is found then
|
|
it calls the handler(s) for the event and returns. If there
|
|
are no X or file events pending, then \fBTk_DoOneEvent\fR
|
|
checks to see if timer callbacks are ready; if so, it
|
|
makes a single callback and returns. If no timer callbacks
|
|
are ready, \fBTk_DoOneEvent\fR checks for \fBTk_DoWhenIdle\fR
|
|
callbacks; if any are found, it invokes all of them and returns.
|
|
Finally, if events or work have been found found, \fBTk_DoOneEvent\fR
|
|
sleeps until a timer, file, or X event occurs; then it processes
|
|
the first event found (in the order given above) and returns.
|
|
The normal return value is 1 to signify that some event or callback
|
|
was processed.
|
|
.PP
|
|
If the \fIflags\fR argument to \fBTk_DoOneEvent\fR is non-zero then
|
|
.VS
|
|
it restricts the kinds of events that will be processed by
|
|
\fBTk_DoOneEvent\fR.
|
|
\fIFlags\fR may be an OR-ed combination of any of the following bits:
|
|
.TP 24
|
|
\fBTK_X_EVENTS\fR \-
|
|
Process X events.
|
|
.TP 24
|
|
\fBTK_FILE_EVENTS\fR \-
|
|
Process file events.
|
|
.TP 24
|
|
\fBTK_TIMER_EVENTS\fR \-
|
|
Process timer events.
|
|
.TP 24
|
|
\fBTK_IDLE_EVENTS\fR \-
|
|
Process \fBTk_DoWhenIdle\fR callbacks.
|
|
.TP 24
|
|
\fBTK_ALL_EVENTS\fR \-
|
|
Process all kinds of events: equivalent to OR-ing together all of the
|
|
above flags or specifying none of them.
|
|
.TP 24
|
|
\fBTK_DONT_WAIT\fR \-
|
|
Don't sleep: process only events that are ready at the time of the
|
|
call.
|
|
.LP
|
|
If any of the flags \fBTK_X_EVENTS\fR, \fBTK_FILE_EVENTS\fR,
|
|
\fBTK_TIMER_EVENTS\fR, or \fBTK_IDLE_EVENTS\fR is set, then the only
|
|
events that will be considered are those for which flags are set.
|
|
Setting none of these flags is equivalent to the value
|
|
\fBTK_ALL_EVENTS\fR, which causes all event types to be processed.
|
|
.PP
|
|
The \fBTK_DONT_WAIT\fR flag causes \fBTk_DoWhenIdle\fR not to put
|
|
the process to sleep: it will check for events but if none are found
|
|
then it returns immediately with a return value of 0 to indicate
|
|
that no work was done.
|
|
\fBTk_DoOneEvent\fR will also return 0 without doing anything if
|
|
\fIflags\fR is \fBTK_IDLE_EVENTS\fR and there are no
|
|
\fBTk_DoWhenIdle\fR callbacks pending.
|
|
.VE
|
|
.PP
|
|
\fBTk_MainLoop\fR is a procedure that loops repeatedly
|
|
calling \fBTk_DoOneEvent\fR. It returns only when there
|
|
are no applications left in this process (i.e. no main windows
|
|
exist anymore). Most X applications will
|
|
call \fBTk_MainLoop\fR after initialization; the main
|
|
execution of the application will consist entirely of
|
|
callbacks invoked by \fBTk_DoOneEvent\fR.
|
|
.PP
|
|
\fBTk_HandleEvent\fR is a lower-level procedure invoked
|
|
by \fBTk_DoOneEvent\fR. It makes callbacks to any event
|
|
handlers (created by calls to \fBTk_CreateEventHandler\fR)
|
|
that match \fIeventPtr\fR and then returns. In some cases
|
|
it may be useful for an application to read events directly
|
|
from X and dispatch them by calling \fBTk_HandleEvent\fR,
|
|
without going through the additional mechanism provided
|
|
by \fBTk_DoOneEvent\fR.
|
|
.PP
|
|
These procedures may be invoked recursively. For example,
|
|
it is possible to invoke \fBTk_DoOneEvent\fR recursively
|
|
from a handler called by \fBTk_DoOneEvent\fR. This sort
|
|
of operation is useful in some modal situations, such
|
|
as when a
|
|
notifier has been popped up and an application wishes to
|
|
wait for the user to click a button in the notifier before
|
|
doing anything else.
|
|
|
|
.SH KEYWORDS
|
|
callback, event, handler, idle, timer
|