#include <tk.h> int Tk_DoOneEvent(flags) Tk_MainLoop() Tk_HandleEvent(eventPtr)
These three procedures are responsible for waiting for events and dispatching to event handlers created with the procedures Tk_CreateEventHandler, Tk_CreateFileHandler, Tk_CreateTimerHandler, and Tk_DoWhenIdle. Tk_DoOneEvent 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. Tk_DoOneEvent 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 Tk_DoOneEvent checks to see if timer callbacks are ready; if so, it makes a single callback and returns. If no timer callbacks are ready, Tk_DoOneEvent checks for Tk_DoWhenIdle callbacks; if any are found, it invokes all of them and returns. Finally, if no events or work have been found, Tk_DoOneEvent 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 flags argument to Tk_DoOneEvent is non-zero then it restricts the kinds of events that will be processed by Tk_DoOneEvent. Flags may be an OR-ed combination of any of the following bits:
If any of the flags TK_X_EVENTS, TK_FILE_EVENTS, TK_TIMER_EVENTS, or TK_IDLE_EVENTS 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 TK_ALL_EVENTS, which causes all event types to be processed.
The TK_DONT_WAIT flag causes Tk_DoWhenIdle 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. Tk_DoOneEvent will also return 0 without doing anything if flags is TK_IDLE_EVENTS and there are no Tk_DoWhenIdle callbacks pending. Lastly, Tk_DoOneEvent 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.
Tk_MainLoop is a procedure that loops repeatedly calling Tk_DoOneEvent. It returns only when there are no applications left in this process (i.e. no main windows exist anymore). Most X applications will call Tk_MainLoop after initialization; the main execution of the application will consist entirely of callbacks invoked by Tk_DoOneEvent.
Tk_HandleEvent is a lower-level procedure invoked by Tk_DoOneEvent. It makes callbacks to any event handlers (created by calls to Tk_CreateEventHandler) that match eventPtr and then returns. In some cases it may be useful for an application to read events directly from X and dispatch them by calling Tk_HandleEvent, without going through the additional mechanism provided by Tk_DoOneEvent.
These procedures may be invoked recursively. For example, it is possible to invoke Tk_DoOneEvent recursively from a handler called by Tk_DoOneEvent. 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.