The procedures described here are responsible for putting events onto the Tk event queue and dispatching to event handlers created with the procedures Tk_CreateEventHandler, Tk_CreateFileHandler, Tk_CreateTimerHandler, and Tk_DoWhenIdle. These procedures are typically called by the notifier routine Tk_DoOneEvent whenever an event is detected, queued events need to be serviced, or the system is in an idle state.
Tk_QueueEvent arranges for an event, described by the eventPtr argument, to be placed on the Tk event queue. Tk will not invoke any event handlers at this point. The structure pointed to by eventPtr contains information about the event to be queued:
typedef union { int type; Tk_FileEvent file; Tk_TimerEvent timer; Tk_WindowEvent window; } Tk_Event typedef struct { int type; int fd; int mask; } Tk_FileEvent; typedef struct { int type; Tk_Time time; } Tk_TimerEvent; typedef struct { int type; XEvent event; } Tk_WindowEvent; typedef struct Tk_Time { long sec; long usec; } Tk_Time;The type field is one of three possible values: TK_WINDOW_EVENTS, TK_FILE_EVENTS, TK_TIMER_EVENTS. These values are the same as those used in Tk_DoOneEvent and Tk_ServiceEvent. For file events, the fd is an integer identifier for an open file or device (such as returned by the open system call). mask is the condition that was detected on the file represented by an OR-ed combination of TK_READABLE, TK_WRITABLE, and TK_EXCEPTION. For timer events, time is the time when the timer event was generated. The Tk_Time structure expresses absolute times in elapsed seconds and microseconds since 00:00 GMT, January 1, 1970. This corresponds to the times used by the gettimeofday procedure. For window events, event is the X event that occured.
Tk_ServiceEvent causes Tk to process one event from its internal event queue. It is called by Tk_DoOneEvent when the notifier determines that it is safe to invoke event handlers. If the flags argument is non-zero then it restricts the kinds of events that will be processed by Tk_ServiceEvent; it is usually the same as the flags argument passed to Tk_DoOneEvent, although some of the bits may be ignored. Flags may be an OR-ed combination of any of the following bits:
Tk_ServiceEvent searches the event queue, starting with the oldest event, until it finds an event which is can be handled. If one is found, then it calls the handler(s) for the event and returns. If there are no events pending, it iterates over the procedures registered by Tk_CreateFileHandler2 until one returns TK_FILE_HANDLED. Tk_ServiceEvent returns 1 if it processed an event or 0 if no processing occured.
Tk_ServiceIdle causes Tk to invoke all of the idle handlers registered by Tk_DoWhenIdle. Tk_ServiceIdle normally returns 1, unless there were no pending idle handlers found, in which case it returns 0.
These procedures may be invoked recursively. For example, it is possible to invoke Tk_DoOneEvent recursively from a handler called by Tk_ServiceEvent. 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.
Copyright © 1995 Sun Microsystems, Inc. Copyright © 1995 Roger E. Critchlow Jr.