Tcl/Tk Documentation > TclLib > DoOneEvent
- Tcl_DoOneEvent - wait for events and invoke event handlers
- 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.
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 -
- Do not 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.callback, event, handler, idle, timer