dooneevent(3Tk)

NAME
     Tk_DoOneEvent, Tk_MainLoop, Tk_HandleEvent - wait for events and invoke
     event handlers

SYNOPSIS
     #include <tk.h>

     int
     Tk_DoOneEvent(flags)

     Tk_MainLoop()

     Tk_HandleEvent(eventPtr)

ARGUMENTS
     int      flags       (in)      This parameter is normally zero.  It may
                                    be an OR-ed combination of any of the
                                    following flag bits:  TK_X_EVENTS,
                                    TK_FILE_EVENTS, TK_TIMER_EVENTS,
                                    TK_IDLE_EVENTS, TK_ALL_EVENTS, or
                                    TK_DONT_WAIT.

     XEvent   *eventPtr   (in)      Pointer to X event to dispatch to relevant
                                    handler(s).


DESCRIPTION
     These three procedures 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 waits for a
     single event of any sort to occur, invokes the handler(s) for that event,
     and then returns.  Tk_DoOneEvent first checks for X events and file-
     related events;  if one is found then it calls the handler(s) for the
     event and returns.  If there are no X or file events pending, then
     Tk_DoOneEvent checks to see if timer callbacks are ready;  if so, it
     makes a single callback and returns.  If no timer callbacks are ready,
     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, Tk_DoOneEvent sleeps until a timer, file, or X event occurs;  then
     it processes the first event found (in the order given above) and
     returns.  The normal return value is 1 to signify that some event or
     callback was processed.  If no event or callback is processed (under
     various conditions described below), then 0 is returned.

     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_X_EVENTS -           Process X 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_X_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_DoWhenIdle 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.  Lastly,|
     Tk_DoOneEvent will return 0 without doing anything if there are no events|
     or work found and if there are no files, displays, or timer handlers to  |
     wait for.

     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 X applications will call
     Tk_MainLoop after initialization;  the main execution of the application
     will consist entirely of callbacks invoked by Tk_DoOneEvent.

     Tk_HandleEvent is a lower-level procedure invoked by Tk_DoOneEvent.  It
     makes callbacks to any event handlers (created by calls to
     Tk_CreateEventHandler) that match eventPtr and then returns.  In some
     cases it may be useful for an application to read events directly from X
     and dispatch them by calling Tk_HandleEvent, without going through the
     additional mechanism provided by Tk_DoOneEvent.

     These procedures 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 notifier has been popped up and an application
     wishes to wait for the user to click a button in the notifier before
     doing anything else.


KEYWORDS
     callback, event, handler, idle, timer