TclDoOneEvent(3) Tcl Library Procedures TclDoOneEvent(3)

NAME
       TclDoOneEvent - wait for events and invoke event handlers

SYNOPSIS
       ##iinncclluuddee <>

       int
       TTccllDDooOOnneeEEvveenntt(flags)

AARRGGUUMMEENNTTSS
       int   flags   (in)      This  parameter is normally zero.  It may be an
                               OR-ed combination of any of the following  flag
                               bits:    TCLWINDOWEVENTS,    TCLFILEEVENTS,
                               TCLTIMEREVENTS,              TCLIDLEEVENTS,
                               TCLALLEVENTS, or TCLDONTWAIT.



DESCRIPTION
       This  procedure is the entry point to Tcl's event loop; it is responsi-
       ble for waiting for events and dispatching event handlers created  with
       procedures   such   as   TTkkCCrreeaatteeEEvveennttHHaannddlleerr,  TTccllCCrreeaatteeFFiilleeHHaannddlleerr,
       TTccllCCrreeaatteeTTiimmeerrHHaannddlleerr, and TTccllDDooWWhheennIIddllee.  TTccllDDooOOnneeEEvveenntt  checks  to
       see  if  events  are  already present on the Tcl event queue; if so, it
       calls the handler(s) for the first (oldest) event, removes it from  the
       queue,  and  returns.  If there are no events ready to be handled, then
       TTccllDDooOOnneeEEvveenntt checks for new events from all possible sources.  If any
       are found, it puts all of them on Tcl's event queue, calls handlers for
       the first event on the queue, and returns.  If  no  events  are  found,
       TTccllDDooOOnneeEEvveenntt  checks  for TTccllDDooWWhheennIIddllee callbacks; if any are found,
       it invokes all of them and returns.  Finally,  if  no  events  or  idle
       callbacks  have  been  found, then TTccllDDooOOnneeEEvveenntt sleeps until an event
       occurs; then it adds any new events to the Tcl event queue, calls  han-
       dlers  for  the first event, and returns.  The normal return value is 1
       to signify that some event was processed (see below for other  alterna-
       tives).

       If  the  flags argument to TTccllDDooOOnneeEEvveenntt is non-zero, it restricts the
       kinds of events that will be processed by TTccllDDooOOnneeEEvveenntt.  Flags may be
       an OR-ed combination of any of the following bits:

       TTCCLLWWIINNDDOOWWEEVVEENNTTSS -        Process window system events.

       TTCCLLFFIILLEEEEVVEENNTTSS -          Process file events.

       TTCCLLTTIIMMEERREEVVEENNTTSS -         Process timer events.

       TTCCLLIIDDLLEEEEVVEENNTTSS -          Process idle callbacks.

       TTCCLLAALLLLEEVVEENNTTSS -           Process  all kinds of events:  equivalent to
                                  OR-ing together all of the  above  flags  or
                                  specifying none of them.

       TTCCLLDDOONNTTWWAAIITT -            Don't  sleep:   process only events that are
                                  ready at the time of the call.

       If   any   of    the    flags    TTCCLLWWIINNDDOOWWEEVVEENNTTSS,    TTCCLLFFIILLEEEEVVEENNTTSS,
       TTCCLLTTIIMMEERREEVVEENNTTSS,  or TTCCLLIIDDLLEEEEVVEENNTTSS 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 TTCCLLAALLLLEEVVEENNTTSS, which causes all
       event types to be processed.  If an application has defined  additional
       event  sources  with TTccllCCrreeaatteeEEvveennttSSoouurrccee, then additional flag values
       may also be valid, depending on those event sources.

       The TTCCLLDDOONNTTWWAAIITT flag causes TTccllDDooOOnneeEEvveenntt 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.
       TTccllDDooOOnneeEEvveenntt  will  also  return 0 without doing anything if the only
       alternative is to block forever (this can happen, for example, if flags
       is  TTCCLLIIDDLLEEEEVVEENNTTSS  and there are no TTccllDDooWWhheennIIddllee callbacks pending,
       or if no event handlers or timer handlers exist).

       TTccllDDooOOnneeEEvveenntt may be invoked recursively.  For example, it is possible
       to   invoke   TTccllDDooOOnneeEEvveenntt  recursively  from  a  handler  called  by
       TTccllDDooOOnneeEEvveenntt.  This sort of operation is useful in some modal  situa-
       tions,  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.


KKEEYYWWOORRDDSS
       callback, event, handler, idle, timer



Tcl                                   7.5                    TclDoOneEvent(3)