1Tcl_DoOneEvent(3)           Tcl Library Procedures           Tcl_DoOneEvent(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_DoOneEvent - wait for events and invoke event handlers
9

SYNOPSIS

11       #include <tcl.h>
12
13       int
14       Tcl_DoOneEvent(flags)
15

ARGUMENTS

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
24

DESCRIPTION

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
44       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
48       TCL_WINDOW_EVENTS -        Process window system events.
49
50       TCL_FILE_EVENTS -          Process file events.
51
52       TCL_TIMER_EVENTS -         Process timer events.
53
54       TCL_IDLE_EVENTS -          Process idle callbacks.
55
56       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
60       TCL_DONT_WAIT -            Do  not sleep:  process only events that are
61                                  ready at the time of the call.
62
63       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
71       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
79       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
86

KEYWORDS

88       callback, event, handler, idle, timer
89
90
91
92Tcl                                   7.5                    Tcl_DoOneEvent(3)
Impressum