Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

Tcl_DoOneEvent(3)                          Tcl Library Procedures                          Tcl_DoOneEvent(3)



____________________________________________________________________________________________________________

NAME
       Tcl_DoOneEvent - wait for events and invoke event handlers

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_DoOneEvent(flags)

ARGUMENTS
       int flags (in)          This  parameter  is  normally zero.  It may be an OR-ed combination of any of
                               the    following    flag    bits:     TCL_WINDOW_EVENTS,     TCL_FILE_EVENTS,
                               TCL_TIMER_EVENTS, TCL_IDLE_EVENTS, TCL_ALL_EVENTS, or TCL_DONT_WAIT.
____________________________________________________________________________________________________________


DESCRIPTION
       This  procedure  is the entry point to Tcl's event loop; it is responsible for waiting for events and
       dispatching event handlers created with procedures such as Tk_CreateEventHandler,  Tcl_CreateFileHan-dler, Tcl_CreateFileHandler,
       dler, Tcl_CreateTimerHandler, and Tcl_DoWhenIdle.  Tcl_DoOneEvent 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 Tcl_DoOneEvent
       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,
       Tcl_DoOneEvent checks for Tcl_DoWhenIdle callbacks; if any are found, it  invokes  all  of  them  and
       returns.   Finally,  if no events or idle callbacks have been found, then Tcl_DoOneEvent sleeps until
       an event occurs; then it adds any new events to the Tcl event queue, calls  handlers  for  the  first
       event, and returns.  The normal return value is 1 to signify that some event was processed (see below
       for other alternatives).

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

       TCL_WINDOW_EVENTS -        Process window system events.

       TCL_FILE_EVENTS -          Process file events.

       TCL_TIMER_EVENTS -         Process timer events.

       TCL_IDLE_EVENTS -          Process idle callbacks.

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

       TCL_DONT_WAIT -            Do not sleep:  process only events that are ready at the time of the call.

       If  any of the flags TCL_WINDOW_EVENTS, TCL_FILE_EVENTS, TCL_TIMER_EVENTS, or TCL_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 TCL_ALL_EVENTS, which causes all event types to be processed.
       If an application has defined additional event sources with  Tcl_CreateEventSource,  then  additional
       flag values may also be valid, depending on those event sources.

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

       Tcl_DoOneEvent  may  be  invoked  recursively.   For example, it is possible to invoke Tcl_DoOneEvent
       recursively from a handler called by Tcl_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.


KEYWORDS
       callback, event, handler, idle, timer



Tcl                                                  7.5                                   Tcl_DoOneEvent(3)