TclJava Library Procedures - Notifier manual page

Thread thread (): The thread in which the Notifier should run.
EventDeleter deleter (): The EventDeleter determines which event in the event queue should be deleted.
TclEvent event (): The event to put into the event queue.
int pos (): The position at which the event should be queued.
int flags (): What types of events to service.

The Notifier is the lowest-level part of the TclJava event system. It is used by higher-level event sources such as file, JavaBean and timer events. The Notifier manages an event queue that holds TclEvent objects. The TclJava Notifier is designed to run in a multi-threaded environment. Each Notifier instance is associated with a primary thread. Any thread can queue (or dequeue) events using the queueEvent (or deleteEvents) call. However, only the primary thread may process events in the queue using the doOneEvent call. Attempts to call doOneEvent from a non-primary thread will cause a TclRuntimeError. This class doesn't have a public constructor and cannot be directly instantiated. You can get to it only through Notifier.getNotifierForThread or the getNotifier method of the Interp class.

getNotifierForThread

This static method returns the Notifier instance whose primary thread is the given thread. If such an instance does not yet exist, it is created automatically.

preserve, release

These two methods maintain a reference count to manage the lifetime of a Notifier and its corresponding event queue. When a Notifier is created inside the getNotifierForThread method, its reference count is zero. A call to preserve increments the reference count by one; a call to release decrements the reference count by one. When the reference count goes from one to zero, the Notifier is disposed -- its event queue is deleted and any left-over events in the queue will not be processed.

If a Java module intends to use a Notifier returned by getNotifierForThread over one or more method calls, it should call preserve immediately after getNotifierForThread returns. The module should call relase when it no longer needs access to the notifier.

NOTE: the notifier returned by interp.getNotifier will remain valid as long as the Interpreter is valid. Hence, if a module always access a notifier via calls to interp.getNotifier, it needs not use the notifier's preserve and release methods.

queueEvent

This method puts the event into the event queue at the position specified by the pos argument. The pos argument may be one of the following:

TCL.QUEUE_TAIL: 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.
TCL.QUEUE_HEAD: Add the event at the front of the queue, so that it will be serviced before all other queued events.
TCL.QUEUE_MARK: Add the event at the front of the queue, unless there are other events at the front whose position is TCL.QUEUE_MARK; if so, add the new event just after all other TCL.QUEUE_MARK events. This value of position 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.

deleteEvents

This method provides a way to selectively delete events in the event queue. It calls deleter.deleteEvent for each event in the queue and deletes those for which deleter.deleteEvent returns 1. Events for which the deleter returns 0 are left in the queue.

doOneEvent

This method is called in the context of the Notifier's primary thread to dispatch events in the event queue. If events are found in the event queue, the processEvent method of the first available event is called. If no event are in the queue, doOneEvent checks if there are idle handlers. If there are any, it invokes all of them and returns. Finally, if no events or idle callbacks have been found, then doOneEvent sleeps until an event occurs, calles processEvent the of the event and returns.

If the flags argument to doOneEvent is non-zero, it restricts the kinds of events that will be processed by 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: Don't 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 additional event sources then additional flag values may also be valid, depending on those event sources.

The TCL.DONT_WAIT flag causes 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. 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 idle callbacks pending, or if no event handlers or timer handlers exist).

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

EQUIVALENT C FUNCTIONS

Tcl_QueueEvent, Tcl_DeleteEvents, Tcl_DoOneEvent

KEYWORDS

event, notifier, event queue, event sources, file events, timer, idle

Copyright © 1998 Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.

CLASS

METHODS

ARGUMENTS

DESCRIPTION

EQUIVALENT C FUNCTIONS

SEE ALSO

KEYWORDS