_________________________________________________________________

     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