Tk_QueueEvent(3)

NAME
Tk_QueueEvent, Tk_ServiceEvent, Tk_ServiceIdle, Tk_IdlePending - add events to the Tk event queue and invoke event or idle handlers

SYNOPSIS
#include <tk.h>

Tk_QueueEvent(eventPtr)

int
Tk_ServiceEvent(flags)

int
Tk_ServiceIdle()

int
Tk_IdlePending()

ARGUMENTS
Pointer to data structure containing information about the event that is to be added to the Tk event queue. The data structure pointed to by eventPtr may be freed upon return. This parameter may be an OR-ed combination of any of the following flag bits: TK_WINDOW_EVENTS, TK_FILE_EVENTS, TK_TIMER_EVENTS, TK_ALL_EVENTS. It is normally passed TK_ALL_EVENTS.

DESCRIPTION

These procedures represent Tk's half of the notifier interface. The procedures are part of Tk, and they are called by the notifier to initiate the handling of events. See the Tk_NotifyDisplay manual entry for information on the notifier's half of the interface. Tk maintains a queue of pending events on which the notifier places new events as they arrive by calling Tk_QueueEvent. When the notifier is ready to initiate event handling, it calls the Tk procedure Tk_ServiceEvent. This two step interface allows Tk to manage the event queue and event priorities internally, thereby simplifying the job of the notifier. It is also possible for the notifier to queue several events at once before calling Tk_ServiceEvent. This allows Tk to collapse events and give the notifier more control over the scheduling of event processing.

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_WINDOW_EVENTS -
    Process window system events.

TK_FILE_EVENTS -
    Process file events.

TK_TIMER_EVENTS -
    Process timer events.

TK_ALL_EVENTS -
    Process all kinds of events: equivalent to OR-ing together all of the above flags.

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 since the previous call to Tk_ServiceIdle. Tk_ServiceIdle normally returns 1, unless there were no pending idle handlers found, in which case it returns 0.

Tk_IdlePending is used by the notifier subsystem to detect whether any idle handlers are currently registered. Tk_IdlePending returns 1 if it detects any pending idle handlers, othwise 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.

KEYWORDS
callback, event, handler, idle, timer, queue, service