- tcl.lang.Notifier -- The event queue and notifier API.
- synchronized void deleteEvents(EventDeleter deleter)
- synchronized int doOneEvent(int flags)
- static synchronized Notifier getNotifierForThread(Thread thread)
- synchronized void preserve()
- synchronized void queueEvent(TclEvent event, int pos)
- synchronized void release()
- preserve, release
- EQUIVALENT C FUNCTIONS
- SEE ALSO
tcl.lang.Notifier -- The event queue and notifier API.
synchronized void deleteEvents(EventDeleter deleter)
synchronized int doOneEvent(int flags)
static synchronized Notifier getNotifierForThread(Thread thread)
synchronized void preserve()
synchronized void queueEvent(TclEvent event, int pos)
synchronized void release()
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.
- Thread thread ()
The thread in which the Notifier should run.
- EventDeleter deleter ()
The EventDeleter determines which event in the event queue should be
- 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.
Tcl_QueueEvent, Tcl_DeleteEvents, Tcl_DoOneEvent
TclEvent, TimerHandler, IdleHandler, EventDeleter, Interp
event, notifier, event queue, event sources, file events, timer, idle
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.
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:
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.
Add the event at the front of the queue, so that it will be serviced
before all other queued events.
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.
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
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
Process window system events.
Process file events.
Process timer events.
Process idle callbacks.
Process all kinds of events: equivalent to OR-ing together all of the
above flags or specifying none of them.
Don't sleep: process only events that are ready at the time of the
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.
Copyright © 1998 Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.