NAME

Tk_NotifyDisplay, Tk_IgnoreDisplay, Tk_NotifyFile, Tk_IgnoreFile, Tk_NotifyIdle, Tk_NotifyTimer - register/unregister interest in different event types

SYNOPSIS

#include <tk.h>
Tk_NotifyDisplay(display)
Tk_IgnoreDisplay(display)
Tk_NotifyFile(id, mask)
Tk_IgnoreFile(id)
Tk_NotifyIdle()
Tk_NotifyTimer(time)

ARGUMENTS

int id (in)
Integer identifier for an open file or device (such as returned by open system call).
int mask (in)
Conditions under which file events should be generated: OR-ed combination of TK_READABLE, TK_WRITABLE, and TK_EXCEPTION.
Display *display (in)
Display that notifier should register/unregister.
Tk_Time *time (in)
Absolute time, in elapsed seconds and microseconds since 00:00 GMT, January 1, 1970, when the notifier should generate a timer event.

DESCRIPTION

These procedures, in conjunction with Tk_DoOneEvent and Tk_Sleep, comprise the system-dependent notifier subsystem of Tk. The notifier is responsible for checking sources of events (files, the window system, timers, etc.) and passing event information to the main part of Tk when events occur. Events are reported in different ways on different platforms, so the notifier interface is designed to allow different implementations of the notifier without changing the rest of Tk. The notifier can also be replaced to allow Tk to be integrated with the event loop from another toolkit such as Xt. The procedures described here are implemented by the notifier and called by Tk so that the notifier knows what events Tk cares about. When Tk_DoOneEvent is called later, it checks for the events of interest and calls other procedures in Tk to handle the events (see the Tk_QueueEvent manual entry for information on these procedures).

Tk_NotifyFile tells the notifier that Tk should be notified the next time I/O becomes possible on a file or if an exceptional condition exists for a file. The file is indicated by id, and the conditions of interest are indicated by mask. For example, if mask is TK_READABLE, notification will occur when the file is readable. Note that this procedure is a one-shot registration. Once the event has been sent, Tk_DoOneEvent will not consider any more events for the file until after the next call to Tk_NotifyFile. If Tk_NotifyFile is called for a file which is still registered, the new value of mask replaces the previous one.

Tk_IgnoreFile cancels a prior call to Tk_NotifyFile so the notifier will stop looking for events on the I/O channel given by id. If an event has already been sent for the file since the last call to Tk_NotifyFile, then Tk_IgnoreFile has no effect.

Tk_NotifyDisplay arranges for the notifier to monitor the X connection to display and generate window events. This procedure will be called by Tk when it first connects to a given display. Note that this is not a one-shot registration. The notifier will continue to notify Tk of window events until Tk explicitly tells it to stop.

Tk_IgnoreDisplay arranges for the notifier to stop notifying Tk of events from the given X display.

Tk_NotifyIdle informs the notifier that Tk has idle processing to do. The next time Tk_DoOneEvent would normally block, it should call Tk_ServiceIdle instead. Like Tk_NotifyFile, this is a one-shot registration.

Tk_NotifyTimer arranges for the notifier to generate a timer event at a particular time in the future specified by the time argument. Like Tk_NotifyFile, this is a one-shot registration. There is only one outstanding timer, so if Tk_NotifyTimer is invoked before the previous timer has expired, the new timer value will replace the previous value. Only one timer event will be generated after the timer expires. See the Tk_QueueEvent manual page for more details on the Tk_Time structure.

KEYWORDS

ignore, notify, file, display, timer, idle
Copyright © 1995 Sun Microsystems, Inc.
Copyright © 1995 Roger E. Critchlow Jr.