# Copyright (c) 1990-1992 The Regents of the University of California. # Copyright (c) 1994-1995 Sun Microsystems, Inc. # See the file "license.terms" for information on usage and redistribution # of this file, and for a DISCLAIMER OF ALL WARRANTIES. # # @(#) DoOneEvent.3 1.12 95/05/06 15:29:18 # =head1 NAME Tk_DoOneEvent, Tk_MainLoop, Tk_HandleEvent - wait for events and invoke event handlers =for category C Programming =head1 SYNOPSIS B<#include Etk.hE> int B(I) B() B(I) =head1 ARGUMENTS =over 4 =item int flags (in) 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. =item XEvent *eventPtr (in) Pointer to X event to dispatch to relevant handler(s). =back =head1 DESCRIPTION These three procedures are responsible for waiting for events and dispatching to event handlers created with the procedures B, B, B, and B. B 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. B 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 B checks to see if timer callbacks are ready; if so, it makes a single callback and returns. If no timer callbacks are ready, B checks for B callbacks; if any are found, it invokes all of them and returns. Finally, if no events or work have been found, B 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. If no event or callback is processed (under various conditions described below), then 0 is returned. If the I argument to B is non-zero then it restricts the kinds of events that will be processed by B. I may be an OR-ed combination of any of the following bits: =over 4 =item B - Process X events. =item B - Process file events. =item B - Process timer events. =item B - Process B callbacks. =item B - Process all kinds of events: equivalent to OR-ing together all of the above flags or specifying none of them. =item B - Don't sleep: process only events that are ready at the time of the call. =back If any of the flags B, B, B, or B 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 B, which causes all event types to be processed. The B flag causes B 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. B will also return 0 without doing anything if I is B and there are no B callbacks pending. Lastly, B will return 0 without doing anything if there are no events or work found and if there are no files, displays, or timer handlers to wait for. B is a procedure that loops repeatedly calling B. It returns only when there are no applications left in this process (i.e. no main windows exist anymore). Most X applications will call B after initialization; the main execution of the application will consist entirely of callbacks invoked by B. B is a lower-level procedure invoked by B. It makes callbacks to any event handlers (created by calls to B) that match I and then returns. In some cases it may be useful for an application to read events directly from X and dispatch them by calling B, without going through the additional mechanism provided by B. These procedures may be invoked recursively. For example, it is possible to invoke B recursively from a handler called by B. 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. =head1 KEYWORDS callback, event, handler, idle, timer