+++ /dev/null
-'\"
-'\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-'\" SCCS: @(#) Notifier.3 1.16 97/05/17 17:03:17
-'\"
-.so man.macros
-.TH Notifier 3 8.0 Tcl "Tcl Library Procedures"
-.BS
-.VS
-.SH NAME
-Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_DeleteEvents, Tcl_WaitForEvent, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode \- the event queue and notifier interfaces
-
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-\fBTcl_CreateEventSource\fR(\fIsetupProc, checkProc, clientData\fB)\fR
-.sp
-\fBTcl_DeleteEventSource\fR(\fIsetupProc, checkProc, clientData\fB)\fR
-.sp
-\fBTcl_SetMaxBlockTime\fR(\fItimePtr\fB)\fR
-.sp
-\fBTcl_QueueEvent\fR(\fIevPtr, position\fR)
-.VS
-.sp
-\fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR)
-.sp
-int
-\fBTcl_WaitForEvent\fR(\fItimePtr\fR)
-.sp
-\fBTcl_SetTimer\fR(\fItimePtr\fR)
-.sp
-int
-\fBTcl_ServiceAll\fR()
-.sp
-int
-\fBTcl_ServiceEvent\fR(\fIflags\fR)
-.sp
-int
-\fBTcl_GetServiceMode\fR()
-.sp
-int
-\fBTcl_SetServiceMode\fR(\fImode\fR)
-.VE
-
-.SH ARGUMENTS
-.AS Tcl_EventDeleteProc milliseconds
-.AS Tcl_EventSetupProc *setupProc
-.AP Tcl_EventSetupProc *setupProc in
-Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR.
-.AP Tcl_EventCheckProc *checkProc in
-Procedure for \fBTcl_DoOneEvent\fR to invoke after waiting for
-events. Checks to see if any events have occurred and, if so,
-queues them.
-.AP ClientData clientData in
-Arbitrary one-word value to pass to \fIsetupProc\fR, \fIcheckProc\fR, or
-\fIdeleteProc\fR.
-.AP Tcl_Time *timePtr in
-Indicates the maximum amount of time to wait for an event. This
-is specified as an interval (how long to wait), not an absolute
-time (when to wakeup). If the pointer passed to \fBTcl_WaitForEvent\fR
-is NULL, it means there is no maximum wait time: wait forever if
-necessary.
-.AP Tcl_Event *evPtr in
-An event to add to the event queue. The storage for the event must
-have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR.
-.AP Tcl_QueuePosition position in
-Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR,
-\fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR.
-.AP int flags in
-What types of events to service. These flags are the same as those
-passed to \fBTcl_DoOneEvent\fR.
-.AP Tcl_EventDeleteProc *deleteProc in
-Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR.
-.VS
-.AP int mode in
-Inidicates whether events should be serviced by \fBTcl_ServiceAll\fR.
-Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR.
-.VE
-.BE
-
-.SH INTRODUCTION
-.PP
-.VS
-The interfaces described here are used to customize the Tcl event
-loop. The two most common customizations are to add new sources of
-events and to merge Tcl's event loop with some other event loop, such
-as one provided by an application in which Tcl is embedded. Each of
-these tasks is described in a separate section below.
-.VE
-.PP
-The procedures in this manual entry are the building blocks out of which
-the Tcl event notifier is constructed. The event notifier is the lowest
-layer in the Tcl event mechanism. It consists of three things:
-.IP [1]
-Event sources: these represent the ways in which events can be
-generated. For example, there is a timer event source that implements
-the \fBTcl_CreateTimerHandler\fR procedure and the \fBafter\fR
-command, and there is a file event source that implements the
-\fBTcl_CreateFileHandler\fR procedure on Unix systems. An event
-source must work with the notifier to detect events at the right
-times, record them on the event queue, and eventually notify
-higher-level software that they have occurred. The procedures
-\fBTcl_CreateEventSource\fR, \fBTcl_DeleteEventSource\fR,
-and \fBTcl_SetMaxBlockTime\fR, \fBTcl_QueueEvent\fR, and
-\fBTcl_DeleteEvents\fR are used primarily by event sources.
-.IP [2]
-The event queue: there is a single queue for the whole application,
-containing events that have been detected but not yet serviced. Event
-sources place events onto the queue so that they may be processed in
-order at appropriate times during the event loop. The event queue
-guarantees a fair discipline of event handling, so that no event
-source can starve the others. It also allows events to be saved for
-servicing at a future time.
-.VS
-\fBTcl_QueueEvent\fR is used (primarily
-by event sources) to add events to the event queue and
-\fBTcl_DeleteEvents\fR is used to remove events from the queue without
-processing them.
-.IP [3]
-The event loop: in order to detect and process events, the application
-enters a loop that waits for events to occur, places them on the event
-queue, and then processes them. Most applications will do this by
-calling the procedure \fBTcl_DoOneEvent\fR, which is described in a
-separate manual entry.
-.PP
-Most Tcl applications need not worry about any of the internals of
-the Tcl notifier. However, the notifier now has enough flexibility
-to be retargeted either for a new platform or to use an external event
-loop (such as the Motif event loop, when Tcl is embedded in a Motif
-application). The procedures \fBTcl_WaitForEvent\fR and
-\fBTcl_SetTimer\fR are normally implemented by Tcl, but may be
-replaced with new versions to retarget the notifier (the \fBTcl_Sleep\fR,
-\fBTcl_CreateFileHandler\fR, and \fBTcl_DeleteFileHandler\fR must
-also be replaced; see CREATING A NEW NOTIFIER below for details).
-The procedures \fBTcl_ServiceAll\fR, \fBTcl_ServiceEvent\fR,
-\fBTcl_GetServiceMode\fR, and \fBTcl_SetServiceMode\fR are provided
-to help connect Tcl's event loop to an external event loop such as
-Motif's.
-.SH "NOTIFIER BASICS"
-.VE
-.PP
-The easiest way to understand how the notifier works is to consider
-what happens when \fBTcl_DoOneEvent\fR is called.
-\fBTcl_DoOneEvent\fR is passed a \fIflags\fR argument that indicates
-what sort of events it is OK to process and also whether or not to
-block if no events are ready. \fBTcl_DoOneEvent\fR does the following
-things:
-.IP [1]
-Check the event queue to see if it contains any events that can
-be serviced. If so, service the first possible event, remove it
-.VS
-from the queue, and return. It does this by calling
-\fBTcl_ServiceEvent\fR and passing in the \fIflags\fR argument.
-.VE
-.IP [2]
-Prepare to block for an event. To do this, \fBTcl_DoOneEvent\fR
-invokes a \fIsetup procedure\fR in each event source.
-The event source will perform event-source specific initialization and
-.VS
-possibly call \fBTcl_SetMaxBlockTime\fR to limit how long
-.VE
-\fBTcl_WaitForEvent\fR will block if no new events occur.
-.IP [3]
-Call \fBTcl_WaitForEvent\fR. This procedure is implemented differently
-on different platforms; it waits for an event to occur, based on the
-information provided by the event sources.
-It may cause the application to block if \fItimePtr\fR specifies
-an interval other than 0.
-\fBTcl_WaitForEvent\fR returns when something has happened,
-such as a file becoming readable or the interval given by \fItimePtr\fR
-expiring. If there are no events for \fBTcl_WaitForEvent\fR to
-wait for, so that it would block forever, then it returns immediately
-and \fBTcl_DoOneEvent\fR returns 0.
-.IP [4]
-Call a \fIcheck procedure\fR in each event source. The check
-procedure determines whether any events of interest to this source
-occurred. If so, the events are added to the event queue.
-.IP [5]
-Check the event queue to see if it contains any events that can
-be serviced. If so, service the first possible event, remove it
-from the queue, and return.
-.IP [6]
-See if there are idle callbacks pending. If so, invoke all of them and
-return.
-.IP [7]
-Either return 0 to indicate that no events were ready, or go back to
-step [2] if blocking was requested by the caller.
-
-.SH "CREATING A NEW EVENT SOURCE"
-.PP
-An event source consists of three procedures invoked by the notifier,
-plus additional C procedures that are invoked by higher-level code
-to arrange for event-driven callbacks. The three procedures called
-by the notifier consist of the setup and check procedures described
-above, plus an additional procedure that is invoked when an event
-is removed from the event queue for servicing.
-.PP
-The procedure \fBTcl_CreateEventSource\fR creates a new event source.
-Its arguments specify the setup procedure and check procedure for
-the event source.
-\fISetupProc\fR should match the following prototype:
-.CS
-typedef void Tcl_EventSetupProc(
- ClientData \fIclientData\fR,
- int \fIflags\fR);
-.CE
-The \fIclientData\fR argument will be the same as the \fIclientData\fR
-argument to \fBTcl_CreateEventSource\fR; it is typically used to
-point to private information managed by the event source.
-The \fIflags\fR argument will be the same as the \fIflags\fR
-argument passed to \fBTcl_DoOneEvent\fR except that it will never
-be 0 (\fBTcl_DoOneEvent\fR replaces 0 with \fBTCL_ALL_EVENTS\fR).
-\fIFlags\fR indicates what kinds of events should be considered;
-if the bit corresponding to this event source isn't set, the event
-source should return immediately without doing anything. For
-example, the file event source checks for the \fBTCL_FILE_EVENTS\fR
-bit.
-.PP
-\fISetupProc\fR's job is to make sure that the application wakes up
-when events of the desired type occur. This is typically done in a
-platform-dependent fashion. For example, under Unix an event source
-might call \fBTcl_CreateFileHandler\fR; under Windows it might
-request notification with a Windows event. For timer-driven event
-sources such as timer events or any polled event, the event source
-can call \fBTcl_SetMaxBlockTime\fR to force the application to wake
-up after a specified time even if no events have occurred.
-.VS
-If no event source calls \fBTcl_SetMaxBlockTime\fR
-then \fBTcl_WaitForEvent\fR will wait as long as necessary for an
-event to occur; otherwise, it will only wait as long as the shortest
-interval passed to \fBTcl_SetMaxBlockTime\fR by one of the event
-sources. If an event source knows that it already has events ready to
-report, it can request a zero maximum block time. For example, the
-setup procedure for the X event source looks to see if there are
-events already queued. If there are, it calls
-\fBTcl_SetMaxBlockTime\fR with a 0 block time so that
-\fBTcl_WaitForEvent\fR does not block if there is no new data on the X
-connection.
-.VE
-The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR points to
-a structure that describes a time interval in seconds and
-microseconds:
-.CS
-typedef struct Tcl_Time {
- long \fIsec\fR;
- long \fIusec\fR;
-} Tcl_Time;
-.CE
-The \fIusec\fR field should be less than 1000000.
-.PP
-.VS
-Information provided to \fBTcl_SetMaxBlockTime\fR
-is only used for the next call to \fBTcl_WaitForEvent\fR; it is
-discarded after \fBTcl_WaitForEvent\fR returns.
-.VE
-The next time an event wait is done each of the event sources'
-setup procedures will be called again, and they can specify new
-information for that event wait.
-.PP
-.VS
-If the application uses an external event loop rather than
-\fBTcl_DoOneEvent\fR, the event sources may need to call
-\fBTcl_SetMaxBlockTime\fR at other times. For example, if a new event
-handler is registered that needs to poll for events, the event source
-may call \fBTcl_SetMaxBlockTime\fR to set the block time to zero to
-force the external event loop to call Tcl. In this case,
-\fBTcl_SetMaxBlockTime\fR invokes \fBTcl_SetTimer\fR with the shortest
-interval seen since the last call to \fBTcl_DoOneEvent\fR or
-\fBTcl_ServiceAll\fR.
-.PP
-In addition to the generic procedure \fBTcl_SetMaxBlockTime\fR, other
-platform-specific procedures may also be available for
-\fIsetupProc\fR, if there is additional information needed by
-\fBTcl_WaitForEvent\fR on that platform. For example, on Unix systems
-the \fBTcl_CreateFileHandler\fR interface can be used to wait for file events.
-.VE
-.PP
-The second procedure provided by each event source is its check
-procedure, indicated by the \fIcheckProc\fR argument to
-\fBTcl_CreateEventSource\fR. \fICheckProc\fR must match the
-following prototype:
-.CS
-typedef void Tcl_EventCheckProc(
- ClientData \fIclientData\fR,
- int \fIflags\fR);
-.CE
-The arguments to this procedure are the same as those for \fIsetupProc\fR.
-\fBCheckProc\fR is invoked by \fBTcl_DoOneEvent\fR after it has waited
-for events. Presumably at least one event source is now prepared to
-queue an event. \fBTcl_DoOneEvent\fR calls each of the event sources
-in turn, so they all have a chance to queue any events that are ready.
-The check procedure does two things. First, it must see if any events
-have triggered. Different event sources do this in different ways.
-.PP
-If an event source's check procedure detects an interesting event, it
-must add the event to Tcl's event queue. To do this, the event source
-calls \fBTcl_QueueEvent\fR. The \fIevPtr\fR argument is a pointer to
-a dynamically allocated structure containing the event (see below for
-more information on memory management issues). Each event source can
-define its own event structure with whatever information is relevant
-to that event source. However, the first element of the structure
-must be a structure of type \fBTcl_Event\fR, and the address of this
-structure is used when communicating between the event source and the
-rest of the notifier. A \fBTcl_Event\fR has the following definition:
-.CS
-typedef struct Tcl_Event {
- Tcl_EventProc *\fIproc\fR;
- struct Tcl_Event *\fInextPtr\fR;
-};
-.CE
-The event source must fill in the \fIproc\fR field of
-the event before calling \fBTcl_QueueEvent\fR.
-The \fInextPtr\fR is used to link together the events in the queue
-and should not be modified by the event source.
-.PP
-An event may be added to the queue at any of three positions, depending
-on the \fIposition\fR argument to \fBTcl_QueueEvent\fR:
-.IP \fBTCL_QUEUE_TAIL\fR 24
-Add the event at the back of the queue, so that all other pending
-events will be serviced first. This is almost always the right
-place for new events.
-.IP \fBTCL_QUEUE_HEAD\fR 24
-Add the event at the front of the queue, so that it will be serviced
-before all other queued events.
-.IP \fBTCL_QUEUE_MARK\fR 24
-Add the event at the front of the queue, unless there are other
-events at the front whose position is \fBTCL_QUEUE_MARK\fR; if so,
-add the new event just after all other \fBTCL_QUEUE_MARK\fR events.
-This value of \fIposition\fR is used to insert an ordered sequence of
-events at the front of the queue, such as a series of
-Enter and Leave events synthesized during a grab or ungrab operation
-in Tk.
-.PP
-.VS
-When it is time to handle an event from the queue (steps 1 and 4
-above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified
-.VE
-in the first queued \fBTcl_Event\fR structure.
-\fIProc\fR must match the following prototype:
-.CS
-typedef int Tcl_EventProc(
- Tcl_Event *\fIevPtr\fR,
- int \fIflags\fR);
-.CE
-The first argument to \fIproc\fR is a pointer to the event, which will
-be the same as the first argument to the \fBTcl_QueueEvent\fR call that
-added the event to the queue.
-The second argument to \fIproc\fR is the \fIflags\fR argument for the
-.VS
-current call to \fBTcl_ServiceEvent\fR; this is used by the event source
-.VE
-to return immediately if its events are not relevant.
-.PP
-It is up to \fIproc\fR to handle the event, typically by invoking
-one or more Tcl commands or C-level callbacks.
-Once the event source has finished handling the event it returns 1
-to indicate that the event can be removed from the queue.
-If for some reason the event source decides that the event cannot
-be handled at this time, it may return 0 to indicate that the event
-.VS
-should be deferred for processing later; in this case \fBTcl_ServiceEvent\fR
-.VE
-will go on to the next event in the queue and attempt to service it.
-There are several reasons why an event source might defer an event.
-One possibility is that events of this type are excluded by the
-\fIflags\fR argument.
-For example, the file event source will always return 0 if the
-\fBTCL_FILE_EVENTS\fR bit isn't set in \fIflags\fR.
-Another example of deferring events happens in Tk if
-\fBTk_RestrictEvents\fR has been invoked to defer certain kinds
-of window events.
-.PP
-.VS
-When \fIproc\fR returns 1, \fBTcl_ServiceEvent\fR will remove the
-event from the event queue and free its storage.
-Note that the storage for an event must be allocated by
-the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR)
-before calling \fBTcl_QueueEvent\fR, but it
-will be freed by \fBTcl_ServiceEvent\fR, not by the event source.
-.PP
-\fBTcl_DeleteEvents\fR can be used to explicitly remove one or more
-events from the event queue. \fBTcl_DeleteEvents\fR calls \fIproc\fR
-for each event in the queue, deleting those for with the procedure
-returns 1. Events for which the procedure returns 0 are left in the
-queue. \fIProc\fR should match the following prototype:
-.CS
-typedef int Tcl_EventDeleteProc(
- Tcl_Event *\fIevPtr\fR,
- ClientData \fIclientData\fR);
-.CE
-The \fIclientData\fR argument will be the same as the \fIclientData\fR
-argument to \fBTcl_DeleteEvents\fR; it is typically used to point to
-private information managed by the event source. The \fIevPtr\fR will
-point to the next event in the queue.
-.VE
-
-.SH "CREATING A NEW NOTIFIER"
-.PP
-The notifier consists of all the procedures described in this manual
-entry, plus \fBTcl_DoOneEvent\fR and \fBTcl_Sleep\fR, which are
-.VS
-available on all platforms, and \fBTcl_CreateFileHandler\fR and
-\fBTcl_DeleteFileHandler\fR, which are Unix-specific. Most of these
-procedures are generic, in that they are the same for all notifiers.
-However, five of the procedures are notifier-dependent:
-\fBTcl_SetTimer\fR, \fBTcl_Sleep\fR, \fBTcl_WaitForEvent\fR,
-\fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR. To
-support a new platform or to integrate Tcl with an
-application-specific event loop, you must write new versions of these
-procedures.
-.PP
-\fBTcl_WaitForEvent\fR is the lowest-level procedure in the notifier;
-it is responsible for waiting for an ``interesting'' event to occur or
-for a given time to elapse. Before \fBTcl_WaitForEvent\fR is invoked,
-each of the event sources' setup procedure will have been invoked.
-The \fItimePtr\fR argument to
-\fBTcl_WaitForEvent\fR gives the maximum time to block for an event,
-based on calls to \fBTcl_SetMaxBlockTime\fR made by setup procedures
-and on other information (such as the \fBTCL_DONT_WAIT\fR bit in
-\fIflags\fR).
-.PP
-Ideally, \fBTcl_WaitForEvent\fR should only wait for an event
-to occur; it should not actually process the event in any way.
-Later on, the
-event sources will process the raw events and create Tcl_Events on
-the event queue in their \fIcheckProc\fR procedures.
-However, on some platforms (such as Windows) this isn't possible;
-events may be processed in \fBTcl_WaitForEvent\fR, including queuing
-Tcl_Events and more (for example, callbacks for native widgets may be
-invoked). The return value from \fBTcl_WaitForEvent\fR must be either
-0, 1, or \-1. On platforms such as Windows where events get processed in
-\fBTcl_WaitForEvent\fR, a return value of 1 means that there may be more
-events still pending that haven't been processed. This is a sign to the
-caller that it must call \fBTcl_WaitForEvent\fR again if it wants all
-pending events to be processed. A 0 return value means that calling
-\fBTcl_WaitForEvent\fR again will not have any effect: either this is a
-platform where \fBTcl_WaitForEvent\fR only waits without doing any event
-processing, or \fBTcl_WaitForEvent\fR knows for sure that there are no
-additional events to process (e.g. it returned because the time
-elapsed). Finally, a return value of \-1 means that the event loop is
-no longer operational and the application should probably unwind and
-terminate. Under Windows this happens when a WM_QUIT message is received;
-under Unix it happens when \fBTcl_WaitForEvent\fR would have waited
-forever because there were no active event sources and the timeout was
-infinite.
-.PP
-If the notifier will be used with an external event loop, then it must
-also support the \fBTcl_SetTimer\fR interface. \fBTcl_SetTimer\fR is
-invoked by \fBTcl_SetMaxBlockTime\fR whenever the maximum blocking
-time has been reduced. \fBTcl_SetTimer\fR should arrange for the
-external event loop to invoke \fBTcl_ServiceAll\fR after the specified
-interval even if no events have occurred. This interface is needed
-because \fBTcl_WaitForEvent\fR isn't invoked when there is an external
-event loop. If the
-notifier will only be used from \fBTcl_DoOneEvent\fR, then
-\fBTcl_SetTimer\fR need not do anything.
-.PP
-On Unix systems, the file event source also needs support from the
-notifier. The file event source consists of the
-\fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR
-procedures, which are described elsewhere.
-.PP
-The \fBTcl_Sleep\fR and \fBTcl_DoOneEvent\fR interfaces are described
-elsewhere.
-.PP
-The easiest way to create a new notifier is to look at the code
-for an existing notifier, such as the files \fBunix/tclUnixNotfy.c\fR
-or \fBwin/tclWinNotify.c\fR in the Tcl source distribution.
-
-.SH "EXTERNAL EVENT LOOPS"
-.PP
-The notifier interfaces are designed so that Tcl can be embedded into
-applications that have their own private event loops. In this case,
-the application does not call \fBTcl_DoOneEvent\fR except in the case
-of recursive event loops such as calls to the Tcl commands \fBupdate\fR
-or \fBvwait\fR. Most of the time is spent in the external event loop
-of the application. In this case the notifier must arrange for the
-external event loop to call back into Tcl when something
-happens on the various Tcl event sources. These callbacks should
-arrange for appropriate Tcl events to be placed on the Tcl event queue.
-.PP
-Because the external event loop is not calling \fBTcl_DoOneEvent\fR on
-a regular basis, it is up to the notifier to arrange for
-\fBTcl_ServiceEvent\fR to be called whenever events are pending on the
-Tcl event queue. The easiest way to do this is to invoke
-\fBTcl_ServiceAll\fR at the end of each callback from the external
-event loop. This will ensure that all of the event sources are
-polled, any queued events are serviced, and any pending idle handlers
-are processed before returning control to the application. In
-addition, event sources that need to poll for events can call
-\fBTcl_SetMaxBlockTime\fR to force the external event loop to call
-Tcl even if no events are available on the system event queue.
-.PP
-As a side effect of processing events detected in the main external
-event loop, Tcl may invoke \fBTcl_DoOneEvent\fR to start a recursive event
-loop in commands like \fBvwait\fR. \fBTcl_DoOneEvent\fR will invoke
-the external event loop, which will result in callbacks as described
-in the preceding paragraph, which will result in calls to
-\fBTcl_ServiceAll\fR. However, in these cases it is undesirable to
-service events in \fBTcl_ServiceAll\fR. Servicing events there is
-unnecessary because control will immediately return to the
-external event loop and hence to \fBTcl_DoOneEvent\fR, which can
-service the events itself. Furthermore, \fBTcl_DoOneEvent\fR is
-supposed to service only a single event, whereas \fBTcl_ServiceAll\fR
-normally services all pending events. To handle this situation,
-\fBTcl_DoOneEvent\fR sets a flag for \fBTcl_ServiceAll\fR
-that causes it to return without servicing any events.
-This flag is called the \fIservice mode\fR;
-\fBTcl_DoOneEvent\fR restores it to its previous value before it returns.
-.PP
-In some cases, however, it may be necessary for \fBTcl_ServiceAll\fR
-to service events
-even when it has been invoked from \fBTcl_DoOneEvent\fR. This happens
-when there is yet another recursive event loop invoked via an
-event handler called by \fBTcl_DoOneEvent\fR (such as one that is
-part of a native widget). In this case, \fBTcl_DoOneEvent\fR may not
-have a chance to service events so \fBTcl_ServiceAll\fR must service
-them all. Any recursive event loop that calls an external event
-loop rather than \fBTcl_DoOneEvent\fR must reset the service mode so
-that all events get processed in \fBTcl_ServiceAll\fR. This is done
-by invoking the \fBTcl_SetServiceMode\fR procedure. If
-\fBTcl_SetServiceMode\fR is passed \fBTCL_SERVICE_NONE\fR, then calls
-to \fBTcl_ServiceAll\fR will return immediately without processing any
-events. If \fBTcl_SetServiceMode\fR is passed \fBTCL_SERVICE_ALL\fR,
-then calls to \fBTcl_ServiceAll\fR will behave normally.
-\fBTcl_SetServiceMode\fR returns the previous value of the service
-mode, which should be restored when the recursive loop exits.
-\fBTcl_GetServiceMode\fR returns the current value of the service
-mode.
-.VE
-
-.SH KEYWORDS
-event, notifier, event queue, event sources, file events, timer, idle, service mode
OSDN Git Service
