Tcl_DoOneEvent()

wait for events and invoke event handlers 

Tcl Library Procedures


SYNOPSIS

#include <tcl.h>

int Tcl_DoOneEvent(flags)


ARGUMENTS

int flags (in) 

This parameter is normally zero. It may be an OR-ed combination of any of the following flag bits: TCL_WINDOW_EVENTS, TCL_FILE_EVENTS, TCL_TIMER_EVENTS, TCL_IDLE_EVENTS, TCL_ALL_EVENTS, or TCL_DONT_WAIT.


DESCRIPTION

This procedure is the entry point to Tcl's event loop; it is responsible for waiting for events and dispatching event handlers created with procedures such as Tk_CreateEventHandler, Tcl_CreateFileHandler(), Tcl_CreateTimerHandler(), and Tcl_DoWhenIdle(). Tcl_DoOneEvent() checks to see if events are already present on the Tcl event queue; if so, it calls the handler(s) for the first (oldest) event, removes it from the queue, and returns. If there are no events ready to be handled, then Tcl_DoOneEvent() checks for new events from all possible sources. If any are found, it puts all of them on Tcl's event queue, calls handlers for the first event on the queue, and returns. If no events are found, Tcl_DoOneEvent() checks for Tcl_DoWhenIdle() callbacks; if any are found, it invokes all of them and returns. Finally, if no events or idle callbacks have been found, then Tcl_DoOneEvent() sleeps until an event occurs; then it adds any new events to the Tcl event queue, calls handlers for the first event, and returns. The normal return value is 1 to signify that some event was processed (see below for other alternatives).

If the flags argument to Tcl_DoOneEvent() is non-zero, it restricts the kinds of events that will be processed by Tcl_DoOneEvent(). Flags may be an OR-ed combination of any of the following bits:

TCL_WINDOW_EVENTS 

Process window system events.

TCL_FILE_EVENTS 

Process file events.

TCL_TIMER_EVENTS 

Process timer events.

TCL_IDLE_EVENTS 

Process idle callbacks.

TCL_ALL_EVENTS 

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

TCL_DONT_WAIT 

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

If any of the flags TCL_WINDOW_EVENTS, TCL_FILE_EVENTS, TCL_TIMER_EVENTS, or TCL_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 TCL_ALL_EVENTS, which causes all event types to be processed. If an application has defined additional event sources with Tcl_CreateEventSource(), then additional flag values may also be valid, depending on those event sources.

The TCL_DONT_WAIT flag causes Tcl_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. Tcl_DoOneEvent() will also return 0 without doing anything if the only alternative is to block forever (this can happen, for example, if flags is TCL_IDLE_EVENTS and there are no Tcl_DoWhenIdle() callbacks pending, or if no event handlers or timer handlers exist).

Tcl_DoOneEvent() may be invoked recursively. For example, it is possible to invoke Tcl_DoOneEvent() recursively from a handler called by Tcl_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.


PORTABILITY

Windows 8.1. Windows Server 2012 R2. Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


PTC MKS Toolkit 10.4 Documentation Build 39.