archie/tk3.6/doc/DoOneEvent.3

'\"
'\" 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