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