java.awt
Class EventQueue

java.lang.Object
  java.awt.EventQueue

public class EventQueue

extends Object

EventQueue is a platform-independent class that queues events, both from the underlying peer classes and from trusted application classes.

It encapsulates asynchronous event dispatch machinery which extracts events from the queue and dispatches them by calling dispatchEvent(AWTEvent) method on this EventQueue with the event to be dispatched as an argument. The particular behavior of this machinery is implementation-dependent. The only requirements are that events which were actually enqueued to this queue (note that events being posted to the EventQueue can be coalesced) are dispatched:

Sequentially.

That is, it is not permitted that several events from this queue are dispatched simultaneously.

In the same order as they are enqueued.

That is, if AWTEvent A is enqueued to the EventQueue before AWTEvent B then event B will not be dispatched before event A.

Some browsers partition applets in different code bases into separate contexts, and establish walls between these contexts. In such a scenario, there will be one EventQueue per context. Other browsers place all applets into the same context, implying that there will be only a single, global EventQueue for all applets. This behavior is implementation-dependent. Consult your browser's documentation for more information.

For information on the threading issues of the event dispatch machinery, see AWT Threading Issues.

Since:

1.1

Author:

Thomas Ball, Fred Ecks, David Mendenhall

Field Summary

private ClassLoader	classLoader
private WeakReference	currentEvent The modifiers field of the current event, if the current event is an InputEvent or ActionEvent.
private static sun.awt.DebugHelper	dbg
private static boolean	debug
private EventDispatchThread	dispatchThread
private static int	HIGH_PRIORITY
private static int	LOW_PRIORITY
private long	mostRecentEventTime
private String	name
private EventQueue	nextQueue
private static int	NORM_PRIORITY
private static int	NUM_PRIORITIES
private EventQueue	previousQueue
private Queue[]	queues
private ThreadGroup	threadGroup
private static int	threadInitNumber
private int	waitForID

Constructor Summary

EventQueue()

Method Summary

(package private) void	detachDispatchThread()
protected void	dispatchEvent(AWTEvent event) Dispatches an event.
static AWTEvent	getCurrentEvent() Returns the the event currently being dispatched by the EventQueue associated with the calling thread.
private AWTEvent	getCurrentEventImpl()
(package private) EventDispatchThread	getDispatchThread()
static long	getMostRecentEventTime() Returns the timestamp of the most recent event that had a timestamp, and that was dispatched from the EventQueue associated with the calling thread.
private long	getMostRecentEventTimeImpl()
AWTEvent	getNextEvent() Removes an event from the EventQueue and returns it.
(package private) AWTEvent	getNextEvent(int id)
(package private) void	initDispatchThread()
static void	invokeAndWait(Runnable runnable) Causes runnable to have its run method called in the dispatch thread of the EventQueue.
static void	invokeLater(Runnable runnable) Causes runnable to have its run method called in the dispatch thread of the EventQueue.
static boolean	isDispatchThread() Returns true if the calling thread is the current AWT EventQueue's dispatch thread.
private static int	nextThreadNum()
private boolean	noEvents() Returns whether an event is pending on any of the separate Queues.
AWTEvent	peekEvent() Returns the first event on the EventQueue without removing it.
AWTEvent	peekEvent(int id) Returns the first event with the specified id, if any.
protected void	pop() Stops dispatching events using this EventQueue.
void	postEvent(AWTEvent theEvent) Posts a 1.1-style event to the EventQueue.
private void	postEvent(AWTEvent theEvent, int priority) Posts the event to the internal Queue of specified priority, coalescing as appropriate.
(package private) void	postEventPrivate(AWTEvent theEvent) Posts a 1.1-style event to the EventQueue.
void	push(EventQueue newEventQueue) Replaces the existing EventQueue with the specified one.
(package private) void	removeSourceEvents(Object source, boolean removeAllEvents)
(package private) static void	setCurrentEventAndMostRecentTime(AWTEvent e)
private void	setCurrentEventAndMostRecentTimeImpl(AWTEvent e)
private void	wakeup(boolean isShutdown)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

dbg

private static final sun.awt.DebugHelper dbg

threadInitNumber

private static int threadInitNumber

LOW_PRIORITY

private static final int LOW_PRIORITY

See Also:

Constant Field Values

NORM_PRIORITY

private static final int NORM_PRIORITY

See Also:

Constant Field Values

HIGH_PRIORITY

private static final int HIGH_PRIORITY

See Also:

Constant Field Values

NUM_PRIORITIES

private static final int NUM_PRIORITIES

See Also:

Constant Field Values

queues

private Queue[] queues

nextQueue

private EventQueue nextQueue

previousQueue

private EventQueue previousQueue

dispatchThread

private EventDispatchThread dispatchThread

threadGroup

private final ThreadGroup threadGroup

classLoader

private final ClassLoader classLoader

debug

private static final boolean debug

See Also:

Constant Field Values

mostRecentEventTime

private long mostRecentEventTime

currentEvent

private WeakReference currentEvent

The modifiers field of the current event, if the current event is an InputEvent or ActionEvent.

waitForID

private int waitForID

name

private final String name

Constructor Detail

EventQueue

public EventQueue()

Method Detail

nextThreadNum

private static int nextThreadNum()

postEvent

public void postEvent(AWTEvent theEvent)

Posts a 1.1-style event to the EventQueue. If there is an existing event on the queue with the same ID and event source, the source Component's coalesceEvents method will be called.

Parameters:

theEvent - an instance of java.awt.AWTEvent, or a subclass of it

Throws:

NullPointerException - if theEvent is null

postEventPrivate

final void postEventPrivate(AWTEvent theEvent)

Posts a 1.1-style event to the EventQueue. If there is an existing event on the queue with the same ID and event source, the source Component's coalesceEvents method will be called.

Parameters:

theEvent - an instance of java.awt.AWTEvent, or a subclass of it

postEvent

private void postEvent(AWTEvent theEvent,
                       int priority)

Posts the event to the internal Queue of specified priority, coalescing as appropriate.

Parameters:

theEvent - an instance of java.awt.AWTEvent, or a subclass of it

priority - the desired priority of the event

noEvents

private boolean noEvents()

Returns whether an event is pending on any of the separate Queues.

Returns:

whether an event is pending on any of the separate Queues

getNextEvent

public AWTEvent getNextEvent()
                      throws InterruptedException

Removes an event from the EventQueue and returns it. This method will block until an event has been posted by another thread.

Returns:

the next AWTEvent

Throws:

InterruptedException - if another thread has interrupted this thread

getNextEvent

AWTEvent getNextEvent(int id)
                throws InterruptedException

Throws:

InterruptedException

peekEvent

public AWTEvent peekEvent()

Returns the first event on the EventQueue without removing it.

Returns:

the first event

peekEvent

public AWTEvent peekEvent(int id)

Returns the first event with the specified id, if any.

Parameters:

id - the id of the type of event desired

Returns:

the first event of the specified id or null if there is no such event

dispatchEvent

protected void dispatchEvent(AWTEvent event)

Dispatches an event. The manner in which the event is dispatched depends upon the type of the event and the type of the event's source object:

Event Type	Source Type	Dispatched To
ActiveEvent	Any	event.dispatch()
Other	Component	source.dispatchEvent(AWTEvent)
Other	MenuComponent	source.dispatchEvent(AWTEvent)
Other	Other	No action (ignored)

Parameters:

event - an instance of java.awt.AWTEvent, or a subclass of it

Throws:

NullPointerException - if event is null

getMostRecentEventTime

public static long getMostRecentEventTime()

Returns the timestamp of the most recent event that had a timestamp, and that was dispatched from the EventQueue associated with the calling thread. If an event with a timestamp is currently being dispatched, its timestamp will be returned. If no events have yet been dispatched, the EventQueue's initialization time will be returned instead.In the current version of the Java platform SDK, only InputEvents, ActionEvents, and InvocationEvents have timestamps; however, future versions of the SDK may add timestamps to additional event types. Note that this method should only be invoked from an application's event dispatching thread. If this method is invoked from another thread, the current system time (as reported by System.currentTimeMillis()) will be returned instead.

Returns:

the timestamp of the last InputEvent, ActionEvent, or InvocationEvent to be dispatched, or System.currentTimeMillis() if this method is invoked on a thread other than an event dispatching thread

Since:

1.4

See Also:

InputEvent.getWhen(), ActionEvent.getWhen(), InvocationEvent.getWhen()

getMostRecentEventTimeImpl

private long getMostRecentEventTimeImpl()

getCurrentEvent

public static AWTEvent getCurrentEvent()

Returns the the event currently being dispatched by the EventQueue associated with the calling thread. This is useful if a method needs access to the event, but was not designed to receive a reference to it as an argument. Note that this method should only be invoked from an application's event dispatching thread. If this method is invoked from another thread, null will be returned.

Returns:

the event currently being dispatched, or null if this method is invoked on a thread other than an event dispatching thread

Since:

1.4

getCurrentEventImpl

private AWTEvent getCurrentEventImpl()

push

public void push(EventQueue newEventQueue)

Replaces the existing EventQueue with the specified one. Any pending events are transferred to the new EventQueue for processing by it.

Parameters:

newEventQueue - an EventQueue (or subclass thereof) instance to be use

Throws:

NullPointerException - if newEventQueue is null

See Also:

pop()

pop

protected void pop()
            throws EmptyStackException

Stops dispatching events using this EventQueue. Any pending events are transferred to the previous EventQueue for processing.

Warning: To avoid deadlock, do not declare this method synchronized in a subclass.

Throws:

EmptyStackException - if no previous push was made on this EventQueue

See Also:

push(java.awt.EventQueue)

isDispatchThread

public static boolean isDispatchThread()

Returns true if the calling thread is the current AWT EventQueue's dispatch thread. Use this call the ensure that a given task is being executed (or not being) on the current AWT EventDispatchThread.

Returns:

true if running on the current AWT EventQueue's dispatch thread

initDispatchThread

final void initDispatchThread()

detachDispatchThread

final void detachDispatchThread()

getDispatchThread

final EventDispatchThread getDispatchThread()

removeSourceEvents

final void removeSourceEvents(Object source,
                              boolean removeAllEvents)

setCurrentEventAndMostRecentTime

static void setCurrentEventAndMostRecentTime(AWTEvent e)

setCurrentEventAndMostRecentTimeImpl

private void setCurrentEventAndMostRecentTimeImpl(AWTEvent e)

invokeLater

public static void invokeLater(Runnable runnable)

Causes runnable to have its run method called in the dispatch thread of the EventQueue. This will happen after all pending events are processed.

Parameters:

runnable - the Runnable whose run method should be executed synchronously on the EventQueue

Since:

1.2

See Also:

invokeAndWait(java.lang.Runnable)

invokeAndWait

public static void invokeAndWait(Runnable runnable)
                          throws InterruptedException,
                                 InvocationTargetException

Causes runnable to have its run method called in the dispatch thread of the EventQueue. This will happen after all pending events are processed. The call blocks until this has happened. This method will throw an Error if called from the event dispatcher thread.

Parameters:

runnable - the Runnable whose run method should be executed synchronously on the EventQueue

Throws:

InterruptedException - if another thread has interrupted this thread

InvocationTargetException - if an exception is thrown when running runnable

Since:

1.2

See Also:

invokeLater(java.lang.Runnable)

wakeup

private void wakeup(boolean isShutdown)