Tk_DoOneEvent, Tk_MainLoop - wait for events and
invoke event handlers
#include <tk.h>
int
Tk_DoOneEvent(flags)
Tk_MainLoop()
- int flags (in)
-
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.
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.
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.
callback, event, handler, idle, timer
Copyright © 1990-1992 The Regents of the University of California.
Copyright © 1994-1995 Sun Microsystems, Inc.
Copyright © 1995 Roger E. Critchlow Jr.