1Tcl_DoOneEvent(3) Tcl Library Procedures Tcl_DoOneEvent(3)
2______________________________________________________________________________
6
8 Tcl_DoOneEvent - wait for events and invoke event handlers
9
11 #include <tcl.h>
12 int
14 Tcl_DoOneEvent(flags)
15
17 int flags (in) This parameter is normally zero. It may be an
18 OR-ed combination of any of the following flag
19 bits: TCL_WINDOW_EVENTS, TCL_FILE_EVENTS,
20 TCL_TIMER_EVENTS, TCL_IDLE_EVENTS,
21 TCL_ALL_EVENTS, or TCL_DONT_WAIT.
22_________________________________________________________________
23
26 This procedure is the entry point to Tcl's event loop; it is responsi‐
27 ble for waiting for events and dispatching event handlers created with
28 procedures such as Tk_CreateEventHandler, Tcl_CreateFileHandler,
29 Tcl_CreateTimerHandler, and Tcl_DoWhenIdle. Tcl_DoOneEvent checks to
30 see if events are already present on the Tcl event queue; if so, it
31 calls the handler(s) for the first (oldest) event, removes it from the
32 queue, and returns. If there are no events ready to be handled, then
33 Tcl_DoOneEvent checks for new events from all possible sources. If any
34 are found, it puts all of them on Tcl's event queue, calls handlers for
35 the first event on the queue, and returns. If no events are found,
36 Tcl_DoOneEvent checks for Tcl_DoWhenIdle callbacks; if any are found,
37 it invokes all of them and returns. Finally, if no events or idle
38 callbacks have been found, then Tcl_DoOneEvent sleeps until an event
39 occurs; then it adds any new events to the Tcl event queue, calls han‐
40 dlers for the first event, and returns. The normal return value is 1
41 to signify that some event was processed (see below for other alterna‐
42 tives).
43 If the flags argument to Tcl_DoOneEvent is non-zero, it restricts the
45 kinds of events that will be processed by Tcl_DoOneEvent. Flags may be
46 an OR-ed combination of any of the following bits:
47 TCL_WINDOW_EVENTS - Process window system events.
49 TCL_FILE_EVENTS - Process file events.
51 TCL_TIMER_EVENTS - Process timer events.
53 TCL_IDLE_EVENTS - Process idle callbacks.
55 TCL_ALL_EVENTS - Process all kinds of events: equivalent to
57 OR-ing together all of the above flags or
58 specifying none of them.
59 TCL_DONT_WAIT - Don't sleep: process only events that are
61 ready at the time of the call.
62 If any of the flags TCL_WINDOW_EVENTS, TCL_FILE_EVENTS,
64 TCL_TIMER_EVENTS, or TCL_IDLE_EVENTS is set, then the only events that
65 will be considered are those for which flags are set. Setting none of
66 these flags is equivalent to the value TCL_ALL_EVENTS, which causes all
67 event types to be processed. If an application has defined additional
68 event sources with Tcl_CreateEventSource, then additional flag values
69 may also be valid, depending on those event sources.
70 The TCL_DONT_WAIT flag causes Tcl_DoOneEvent not to put the process to
72 sleep: it will check for events but if none are found then it returns
73 immediately with a return value of 0 to indicate that no work was done.
74 Tcl_DoOneEvent will also return 0 without doing anything if the only
75 alternative is to block forever (this can happen, for example, if flags
76 is TCL_IDLE_EVENTS and there are no Tcl_DoWhenIdle callbacks pending,
77 or if no event handlers or timer handlers exist).
78 Tcl_DoOneEvent may be invoked recursively. For example, it is possible
80 to invoke Tcl_DoOneEvent recursively from a handler called by
81 Tcl_DoOneEvent. This sort of operation is useful in some modal situa‐
82 tions, such as when a notification dialog has been popped up and an
83 application wishes to wait for the user to click a button in the dialog
84 before doing anything else.
85
88 callback, event, handler, idle, timer
89Tcl 7.5 Tcl_DoOneEvent(3)