Class EventQueue
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
AWTEventA is enqueued to theEventQueuebeforeAWTEventB 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
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionCreates a newsecondary loopassociated with this event queue.protected voiddispatchEvent(AWTEvent event) Dispatches an event.static AWTEventReturns the event currently being dispatched by theEventQueueassociated with the calling thread.static longReturns the timestamp of the most recent event that had a timestamp, and that was dispatched from theEventQueueassociated with the calling thread.Removes an event from theEventQueueand returns it.static voidinvokeAndWait(Runnable runnable) static voidinvokeLater(Runnable runnable) static booleanReturns true if the calling thread isthe current AWT EventQueue's dispatch thread.Returns the first event on theEventQueuewithout removing it.peekEvent(int id) Returns the first event with the specified id, if any.protected voidpop()Stops dispatching events using thisEventQueue.voidPosts a 1.1-style event to theEventQueue.voidpush(EventQueue newEventQueue) Replaces the existingEventQueuewith the specified one.
-
Constructor Details
-
EventQueue
public EventQueue()Initializes a new instance ofEventQueue.
-
-
Method Details
-
postEvent
Posts a 1.1-style event to theEventQueue. If there is an existing event on the queue with the same ID and event source, the sourceComponent'scoalesceEventsmethod will be called.- Parameters:
theEvent- an instance ofjava.awt.AWTEvent, or a subclass of it- Throws:
NullPointerException- iftheEventisnull
-
getNextEvent
Removes an event from theEventQueueand returns it. This method will block until an event has been posted by another thread.- Returns:
- the next
AWTEvent - Throws:
InterruptedException- if any thread has interrupted this thread
-
peekEvent
Returns the first event on theEventQueuewithout removing it.- Returns:
- the first event
-
peekEvent
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
nullif there is no such event
-
dispatchEvent
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 types, source types, and dispatch methods 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 ofjava.awt.AWTEvent, or a subclass of it- Throws:
NullPointerException- ifeventisnull- Since:
- 1.2
-
getMostRecentEventTime
public static long getMostRecentEventTime()Returns the timestamp of the most recent event that had a timestamp, and that was dispatched from theEventQueueassociated 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 JDK, onlyInputEvents,ActionEvents, andInvocationEvents have timestamps; however, future versions of the JDK may add timestamps to additional event types. Note that this method should only be invoked from an application'sevent dispatching thread. If this method is invoked from another thread, the current system time (as reported bySystem.currentTimeMillis()) will be returned instead.- Returns:
- the timestamp of the last
InputEvent,ActionEvent, orInvocationEventto be dispatched, orSystem.currentTimeMillis()if this method is invoked on a thread other than an event dispatching thread - Since:
- 1.4
- See Also:
-
getCurrentEvent
Returns the event currently being dispatched by theEventQueueassociated 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
-
push
Replaces the existingEventQueuewith the specified one. Any pending events are transferred to the newEventQueuefor processing by it.- Parameters:
newEventQueue- anEventQueue(or subclass thereof) instance to be use- Throws:
NullPointerException- ifnewEventQueueisnull- Since:
- 1.2
- See Also:
-
pop
Stops dispatching events using thisEventQueue. Any pending events are transferred to the previousEventQueuefor processing.Warning: To avoid deadlock, do not declare this method synchronized in a subclass.
- Throws:
EmptyStackException- if no previous push was made on thisEventQueue- Since:
- 1.2
- See Also:
-
createSecondaryLoop
Creates a newsecondary loopassociated with this event queue. Use theSecondaryLoop.enter()andSecondaryLoop.exit()methods to start and stop the event loop and dispatch the events from this queue.- Returns:
- secondaryLoop A new secondary loop object, which can be used to launch a new nested event loop and dispatch events from this queue
- Since:
- 1.7
- See Also:
-
isDispatchThread
public static boolean isDispatchThread()Returns true if the calling thread isthe current AWT EventQueue's dispatch thread. Use this method to ensure that a particular task is being executed (or not being) there.Note: use the
invokeLater(java.lang.Runnable)orinvokeAndWait(java.lang.Runnable)methods to execute a task inthe current AWT EventQueue's dispatch thread.- Returns:
- true if running in
the current AWT EventQueue's dispatch thread - Since:
- 1.2
- See Also:
-
invokeLater
Causesrunnableto have itsrunmethod called in thedispatch threadofthe system EventQueue. This will happen after all pending events are processed.- Parameters:
runnable- theRunnablewhoserunmethod should be executed asynchronously in theevent dispatch threadofthe system EventQueue- Since:
- 1.2
- See Also:
-
invokeAndWait
public static void invokeAndWait(Runnable runnable) throws InterruptedException, InvocationTargetException Causesrunnableto have itsrunmethod called in thedispatch threadofthe system 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 theevent dispatcher thread.- Parameters:
runnable- theRunnablewhoserunmethod should be executed synchronously in theevent dispatch threadofthe system EventQueue- Throws:
InterruptedException- if any thread has interrupted this threadInvocationTargetException- if an throwable is thrown when runningrunnable- Since:
- 1.2
- See Also:
-