< prev index next >
src/java.desktop/share/classes/java/awt/EventQueue.java
Print this page
*** 49,88 ****
import jdk.internal.misc.SharedSecrets;
import jdk.internal.misc.JavaSecurityAccess;
/**
! * <code>EventQueue</code> is a platform-independent class
* that queues events, both from the underlying peer classes
* and from trusted application classes.
* <p>
* It encapsulates asynchronous event dispatch machinery which
* extracts events from the queue and dispatches them by calling
* {@link #dispatchEvent(AWTEvent) dispatchEvent(AWTEvent)} method
! * on this <code>EventQueue</code> 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 <code>EventQueue</code> can be coalesced)
* are dispatched:
* <dl>
* <dt> Sequentially.
* <dd> That is, it is not permitted that several events from
* this queue are dispatched simultaneously.
* <dt> In the same order as they are enqueued.
! * <dd> That is, if <code>AWTEvent</code> A is enqueued
! * to the <code>EventQueue</code> before
! * <code>AWTEvent</code> B then event B will not be
* dispatched before event A.
* </dl>
* <p>
* 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 <code>EventQueue</code>
* per context. Other browsers place all applets into the same
* context, implying that there will be only a single, global
! * <code>EventQueue</code> for all applets. This behavior is
* implementation-dependent. Consult your browser's documentation
* for more information.
* <p>
* For information on the threading issues of the event dispatch
* machinery, see <a href="doc-files/AWTThreadIssues.html#Autoshutdown"
--- 49,88 ----
import jdk.internal.misc.SharedSecrets;
import jdk.internal.misc.JavaSecurityAccess;
/**
! * {@code EventQueue} is a platform-independent class
* that queues events, both from the underlying peer classes
* and from trusted application classes.
* <p>
* It encapsulates asynchronous event dispatch machinery which
* extracts events from the queue and dispatches them by calling
* {@link #dispatchEvent(AWTEvent) dispatchEvent(AWTEvent)} method
! * on this {@code 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 {@code EventQueue} can be coalesced)
* are dispatched:
* <dl>
* <dt> Sequentially.
* <dd> That is, it is not permitted that several events from
* this queue are dispatched simultaneously.
* <dt> In the same order as they are enqueued.
! * <dd> That is, if {@code AWTEvent} A is enqueued
! * to the {@code EventQueue} before
! * {@code AWTEvent} B then event B will not be
* dispatched before event A.
* </dl>
* <p>
* 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 {@code EventQueue}
* per context. Other browsers place all applets into the same
* context, implying that there will be only a single, global
! * {@code EventQueue} for all applets. This behavior is
* implementation-dependent. Consult your browser's documentation
* for more information.
* <p>
* For information on the threading issues of the event dispatch
* machinery, see <a href="doc-files/AWTThreadIssues.html#Autoshutdown"
*** 249,279 ****
pushPopLock = (Lock)appContext.get(AppContext.EVENT_QUEUE_LOCK_KEY);
pushPopCond = (Condition)appContext.get(AppContext.EVENT_QUEUE_COND_KEY);
}
/**
! * Posts a 1.1-style event to the <code>EventQueue</code>.
* If there is an existing event on the queue with the same ID
! * and event source, the source <code>Component</code>'s
! * <code>coalesceEvents</code> method will be called.
*
! * @param theEvent an instance of <code>java.awt.AWTEvent</code>,
* or a subclass of it
! * @throws NullPointerException if <code>theEvent</code> is <code>null</code>
*/
public void postEvent(AWTEvent theEvent) {
SunToolkit.flushPendingEvents(appContext);
postEventPrivate(theEvent);
}
/**
! * Posts a 1.1-style event to the <code>EventQueue</code>.
* If there is an existing event on the queue with the same ID
! * and event source, the source <code>Component</code>'s
! * <code>coalesceEvents</code> method will be called.
*
! * @param theEvent an instance of <code>java.awt.AWTEvent</code>,
* or a subclass of it
*/
private final void postEventPrivate(AWTEvent theEvent) {
theEvent.isPosted = true;
pushPopLock.lock();
--- 249,279 ----
pushPopLock = (Lock)appContext.get(AppContext.EVENT_QUEUE_LOCK_KEY);
pushPopCond = (Condition)appContext.get(AppContext.EVENT_QUEUE_COND_KEY);
}
/**
! * Posts a 1.1-style event to the {@code EventQueue}.
* If there is an existing event on the queue with the same ID
! * and event source, the source {@code Component}'s
! * {@code coalesceEvents} method will be called.
*
! * @param theEvent an instance of {@code java.awt.AWTEvent},
* or a subclass of it
! * @throws NullPointerException if {@code theEvent} is {@code null}
*/
public void postEvent(AWTEvent theEvent) {
SunToolkit.flushPendingEvents(appContext);
postEventPrivate(theEvent);
}
/**
! * Posts a 1.1-style event to the {@code EventQueue}.
* If there is an existing event on the queue with the same ID
! * and event source, the source {@code Component}'s
! * {@code coalesceEvents} method will be called.
*
! * @param theEvent an instance of {@code java.awt.AWTEvent},
* or a subclass of it
*/
private final void postEventPrivate(AWTEvent theEvent) {
theEvent.isPosted = true;
pushPopLock.lock();
*** 318,328 ****
/**
* Posts the event to the internal Queue of specified priority,
* coalescing as appropriate.
*
! * @param theEvent an instance of <code>java.awt.AWTEvent</code>,
* or a subclass of it
* @param priority the desired priority of the event
*/
private void postEvent(AWTEvent theEvent, int priority) {
if (coalesceEvent(theEvent, priority)) {
--- 318,328 ----
/**
* Posts the event to the internal Queue of specified priority,
* coalescing as appropriate.
*
! * @param theEvent an instance of {@code java.awt.AWTEvent},
* or a subclass of it
* @param priority the desired priority of the event
*/
private void postEvent(AWTEvent theEvent, int priority) {
if (coalesceEvent(theEvent, priority)) {
*** 530,543 ****
return true;
}
/**
! * Removes an event from the <code>EventQueue</code> and
* returns it. This method will block until an event has
* been posted by another thread.
! * @return the next <code>AWTEvent</code>
* @exception InterruptedException
* if any thread has interrupted this thread
*/
public AWTEvent getNextEvent() throws InterruptedException {
do {
--- 530,543 ----
return true;
}
/**
! * Removes an event from the {@code EventQueue} and
* returns it. This method will block until an event has
* been posted by another thread.
! * @return the next {@code AWTEvent}
* @exception InterruptedException
* if any thread has interrupted this thread
*/
public AWTEvent getNextEvent() throws InterruptedException {
do {
*** 615,625 ****
}
} while(true);
}
/**
! * Returns the first event on the <code>EventQueue</code>
* without removing it.
* @return the first event
*/
public AWTEvent peekEvent() {
pushPopLock.lock();
--- 615,625 ----
}
} while(true);
}
/**
! * Returns the first event on the {@code EventQueue}
* without removing it.
* @return the first event
*/
public AWTEvent peekEvent() {
pushPopLock.lock();
*** 637,647 ****
}
/**
* Returns the first event with the specified id, if any.
* @param id the id of the type of event desired
! * @return the first event of the specified id or <code>null</code>
* if there is no such event
*/
public AWTEvent peekEvent(int id) {
pushPopLock.lock();
try {
--- 637,647 ----
}
/**
* Returns the first event with the specified id, if any.
* @param id the id of the type of event desired
! * @return the first event of the specified id or {@code null}
* if there is no such event
*/
public AWTEvent peekEvent(int id) {
pushPopLock.lock();
try {
*** 694,706 ****
* <td>Other</td>
* <td>No action (ignored)</td>
* </tr>
* </table>
*
! * @param event an instance of <code>java.awt.AWTEvent</code>,
* or a subclass of it
! * @throws NullPointerException if <code>event</code> is <code>null</code>
* @since 1.2
*/
protected void dispatchEvent(final AWTEvent event) {
final Object src = event.getSource();
final PrivilegedAction<Void> action = new PrivilegedAction<Void>() {
--- 694,706 ----
* <td>Other</td>
* <td>No action (ignored)</td>
* </tr>
* </table>
*
! * @param event an instance of {@code java.awt.AWTEvent},
* or a subclass of it
! * @throws NullPointerException if {@code event} is {@code null}
* @since 1.2
*/
protected void dispatchEvent(final AWTEvent event) {
final Object src = event.getSource();
final PrivilegedAction<Void> action = new PrivilegedAction<Void>() {
*** 775,801 ****
}
}
/**
* Returns the timestamp of the most recent event that had a timestamp, and
! * that was dispatched from the <code>EventQueue</code> 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 JDK, only <code>InputEvent</code>s,
! * <code>ActionEvent</code>s, and <code>InvocationEvent</code>s 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's {@link #isDispatchThread event dispatching thread}.
* If this method is
* invoked from another thread, the current system time (as reported by
! * <code>System.currentTimeMillis()</code>) will be returned instead.
*
! * @return the timestamp of the last <code>InputEvent</code>,
! * <code>ActionEvent</code>, or <code>InvocationEvent</code> to be
! * dispatched, or <code>System.currentTimeMillis()</code> if this
* method is invoked on a thread other than an event dispatching
* thread
* @see java.awt.event.InputEvent#getWhen
* @see java.awt.event.ActionEvent#getWhen
* @see java.awt.event.InvocationEvent#getWhen
--- 775,801 ----
}
}
/**
* Returns the timestamp of the most recent event that had a timestamp, and
! * that was dispatched from the {@code 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 JDK, only {@code InputEvent}s,
! * {@code ActionEvent}s, and {@code InvocationEvent}s 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's {@link #isDispatchThread event dispatching thread}.
* If this method is
* invoked from another thread, the current system time (as reported by
! * {@code System.currentTimeMillis()}) will be returned instead.
*
! * @return the timestamp of the last {@code InputEvent},
! * {@code ActionEvent}, or {@code InvocationEvent} to be
! * dispatched, or {@code System.currentTimeMillis()} if this
* method is invoked on a thread other than an event dispatching
* thread
* @see java.awt.event.InputEvent#getWhen
* @see java.awt.event.ActionEvent#getWhen
* @see java.awt.event.InvocationEvent#getWhen
*** 829,839 ****
}
}
/**
* Returns the event currently being dispatched by the
! * <code>EventQueue</code> 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.
*
--- 829,839 ----
}
}
/**
* Returns the event currently being dispatched by the
! * {@code 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.
*
*** 854,871 ****
pushPopLock.unlock();
}
}
/**
! * Replaces the existing <code>EventQueue</code> with the specified one.
! * Any pending events are transferred to the new <code>EventQueue</code>
* for processing by it.
*
! * @param newEventQueue an <code>EventQueue</code>
* (or subclass thereof) instance to be use
* @see java.awt.EventQueue#pop
! * @throws NullPointerException if <code>newEventQueue</code> is <code>null</code>
* @since 1.2
*/
public void push(EventQueue newEventQueue) {
if (getEventLog().isLoggable(PlatformLogger.Level.FINE)) {
getEventLog().fine("EventQueue.push(" + newEventQueue + ")");
--- 854,871 ----
pushPopLock.unlock();
}
}
/**
! * Replaces the existing {@code EventQueue} with the specified one.
! * Any pending events are transferred to the new {@code EventQueue}
* for processing by it.
*
! * @param newEventQueue an {@code EventQueue}
* (or subclass thereof) instance to be use
* @see java.awt.EventQueue#pop
! * @throws NullPointerException if {@code newEventQueue} is {@code null}
* @since 1.2
*/
public void push(EventQueue newEventQueue) {
if (getEventLog().isLoggable(PlatformLogger.Level.FINE)) {
getEventLog().fine("EventQueue.push(" + newEventQueue + ")");
*** 919,937 ****
pushPopLock.unlock();
}
}
/**
! * Stops dispatching events using this <code>EventQueue</code>.
* Any pending events are transferred to the previous
! * <code>EventQueue</code> for processing.
* <p>
* Warning: To avoid deadlock, do not declare this method
* synchronized in a subclass.
*
* @exception EmptyStackException if no previous push was made
! * on this <code>EventQueue</code>
* @see java.awt.EventQueue#push
* @since 1.2
*/
protected void pop() throws EmptyStackException {
if (getEventLog().isLoggable(PlatformLogger.Level.FINE)) {
--- 919,937 ----
pushPopLock.unlock();
}
}
/**
! * Stops dispatching events using this {@code EventQueue}.
* Any pending events are transferred to the previous
! * {@code EventQueue} for processing.
* <p>
* Warning: To avoid deadlock, do not declare this method
* synchronized in a subclass.
*
* @exception EmptyStackException if no previous push was made
! * on this {@code EventQueue}
* @see java.awt.EventQueue#push
* @since 1.2
*/
protected void pop() throws EmptyStackException {
if (getEventLog().isLoggable(PlatformLogger.Level.FINE)) {
*** 1120,1133 ****
pushPopLock.unlock();
}
}
/*
! * Gets the <code>EventDispatchThread</code> for this
! * <code>EventQueue</code>.
* @return the event dispatch thread associated with this event queue
! * or <code>null</code> if this event queue doesn't have a
* working thread associated with it
* @see java.awt.EventQueue#initDispatchThread
* @see java.awt.EventQueue#detachDispatchThread
*/
final EventDispatchThread getDispatchThread() {
--- 1120,1133 ----
pushPopLock.unlock();
}
}
/*
! * Gets the {@code EventDispatchThread} for this
! * {@code EventQueue}.
* @return the event dispatch thread associated with this event queue
! * or {@code null} if this event queue doesn't have a
* working thread associated with it
* @see java.awt.EventQueue#initDispatchThread
* @see java.awt.EventQueue#detachDispatchThread
*/
final EventDispatchThread getDispatchThread() {
*** 1139,1157 ****
}
}
/*
* Removes any pending events for the specified source object.
! * If removeAllEvents parameter is <code>true</code> then all
* events for the specified source object are removed, if it
! * is <code>false</code> then <code>SequencedEvent</code>, <code>SentEvent</code>,
! * <code>FocusEvent</code>, <code>WindowEvent</code>, <code>KeyEvent</code>,
! * and <code>InputMethodEvent</code> are kept in the queue, but all other
* events are removed.
*
* This method is normally called by the source's
! * <code>removeNotify</code> method.
*/
final void removeSourceEvents(Object source, boolean removeAllEvents) {
SunToolkit.flushPendingEvents(appContext);
pushPopLock.lock();
try {
--- 1139,1157 ----
}
}
/*
* Removes any pending events for the specified source object.
! * If removeAllEvents parameter is {@code true} then all
* events for the specified source object are removed, if it
! * is {@code false} then {@code SequencedEvent}, {@code SentEvent},
! * {@code FocusEvent}, {@code WindowEvent}, {@code KeyEvent},
! * and {@code InputMethodEvent} are kept in the queue, but all other
* events are removed.
*
* This method is normally called by the source's
! * {@code removeNotify} method.
*/
final void removeSourceEvents(Object source, boolean removeAllEvents) {
SunToolkit.flushPendingEvents(appContext);
pushPopLock.lock();
try {
*** 1247,1262 ****
pushPopLock.unlock();
}
}
/**
! * Causes <code>runnable</code> to have its <code>run</code>
* method called in the {@link #isDispatchThread dispatch thread} of
* {@link Toolkit#getSystemEventQueue the system EventQueue}.
* This will happen after all pending events are processed.
*
! * @param runnable the <code>Runnable</code> whose <code>run</code>
* method should be executed
* asynchronously in the
* {@link #isDispatchThread event dispatch thread}
* of {@link Toolkit#getSystemEventQueue the system EventQueue}
* @see #invokeAndWait
--- 1247,1262 ----
pushPopLock.unlock();
}
}
/**
! * Causes {@code runnable} to have its {@code run}
* method called in the {@link #isDispatchThread dispatch thread} of
* {@link Toolkit#getSystemEventQueue the system EventQueue}.
* This will happen after all pending events are processed.
*
! * @param runnable the {@code Runnable} whose {@code run}
* method should be executed
* asynchronously in the
* {@link #isDispatchThread event dispatch thread}
* of {@link Toolkit#getSystemEventQueue the system EventQueue}
* @see #invokeAndWait
*** 1268,1294 ****
Toolkit.getEventQueue().postEvent(
new InvocationEvent(Toolkit.getDefaultToolkit(), runnable));
}
/**
! * Causes <code>runnable</code> to have its <code>run</code>
* method called in the {@link #isDispatchThread dispatch thread} of
* {@link Toolkit#getSystemEventQueue the 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 the
* {@link #isDispatchThread event dispatcher thread}.
*
! * @param runnable the <code>Runnable</code> whose <code>run</code>
* method should be executed
* synchronously in the
* {@link #isDispatchThread event dispatch thread}
* of {@link Toolkit#getSystemEventQueue the system EventQueue}
* @exception InterruptedException if any thread has
* interrupted this thread
* @exception InvocationTargetException if an throwable is thrown
! * when running <code>runnable</code>
* @see #invokeLater
* @see Toolkit#getSystemEventQueue
* @see #isDispatchThread
* @since 1.2
*/
--- 1268,1294 ----
Toolkit.getEventQueue().postEvent(
new InvocationEvent(Toolkit.getDefaultToolkit(), runnable));
}
/**
! * Causes {@code runnable} to have its {@code run}
* method called in the {@link #isDispatchThread dispatch thread} of
* {@link Toolkit#getSystemEventQueue the 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 the
* {@link #isDispatchThread event dispatcher thread}.
*
! * @param runnable the {@code Runnable} whose {@code run}
* method should be executed
* synchronously in the
* {@link #isDispatchThread event dispatch thread}
* of {@link Toolkit#getSystemEventQueue the system EventQueue}
* @exception InterruptedException if any thread has
* interrupted this thread
* @exception InvocationTargetException if an throwable is thrown
! * when running {@code runnable}
* @see #invokeLater
* @see Toolkit#getSystemEventQueue
* @see #isDispatchThread
* @since 1.2
*/
< prev index next >