Tk_DoOneEvent(3)

NAME
Tk_DoOneEvent, Tk_MainLoop - wait for events and invoke event handlers

SYNOPSIS
#include <tk.h>

int
Tk_DoOneEvent(flags)

Tk_MainLoop()

ARGUMENTS
This parameter is normally zero. It may be an OR-ed combination of any of the following flag bits: TK_WINDOW_EVENTS, TK_FILE_EVENTS, TK_TIMER_EVENTS, TK_IDLE_EVENTS, TK_ALL_EVENTS, or TK_DONT_WAIT.

DESCRIPTION

These two procedures embody Tk's event loop; they 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 checks to see if there is a previously queued event on the Tk event queue; if one is found, it calls the handler(s) for the event and returns. If there are no events ready to be handled, then it checks for new events. If any are found, it puts all of them on Tk's event queue and returns. The first new event will be handled the next time Tk_DoOneEvent is called. If no events are found, 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, then Tk_DoOneEvent sleeps until a timer, file, or window event occurs; then it adds any new events to the Tk event queue and returns. The normal return value is 1 to signify that some event or callback was processed. If Tk_DoOneEvent found no pending or new events and there were no idle handlers to process, then it returns 0. 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:

TK_WINDOW_EVENTS -
    Process window system events.

TK_FILE_EVENTS -
    Process file events.

TK_TIMER_EVENTS -
    Process timer events.

TK_IDLE_EVENTS -
    Process Tk_DoWhenIdle callbacks.

TK_ALL_EVENTS -
    Process all kinds of events: equivalent to OR-ing together all of the above flags or specifying none of them.

TK_DONT_WAIT -
    Don't sleep: process only events that are ready at the time of the call.

If any of the flags TK_WINDOW_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_DoOneEvent 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.

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 windowing applications will call Tk_MainLoop after initialization; the main execution of the application will consist entirely of callbacks invoked by Tk_ServiceEvent which is called by Tk_DoOneEvent.

These routines 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 notification dialog has been popped up and an application wishes to wait for the user to click a button in the dialog before doing anything else.

IMPLEMENTATION

Tk_DoOneEvent is the key procedure in the system-dependent notifier. It is the procedure that watches for system events and generates the appropriate Tk event structures to put on the Tk event queue. This procedure along with Tk_Sleep and the procedures desribed in the Tk_NotifyDisplay manual page comprise a replaceable module which can be changed to support different system interfaces. See the Tk_QueueEvent and the Tk_NotifyDisplay manual pages for additional details. The rest of this section describes the expected behavior of Tk_DoOneEvent:

The Tk_DoOneEvent procedure first calls Tk_ServiceEvent to process the first eligible event on the Tk event queue. If an event was processed, Tk_DoOneEvent returns, otherwise it looks for new events. If it finds any timer, window system, or file events pending, it puts all of them on the Tk event queue by calling Tk_QueueEvent for each event, and then returns. If no events were found and Tk_NotifyIdle has been called since the last call to Tk_ServiceIdle, then Tk_DoOneEvent will invoke Tk_ServiceIdle, to process all of the Tk_DoWhenIdle callbacks, and then return. If Tk_NotifyIdle has not been called and flags did not contain the TK_DONT_WAIT bit, then Tk_DoOneEvent will sleep until a new event arrives, queue all detected events, and return.

KEYWORDS
callback, event, handler, idle, timer