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.

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

Since:
1.1

  • Constructor Summary

    Constructors
    Constructor
    Description
    EventQueue()
    Initializes a new instance of EventQueue.

  • Method Summary

    Modifier and Type
    Method
    Description
    SecondaryLoop
    createSecondaryLoop()
    Creates a new secondary loop associated with this event queue.
    protected void
    dispatchEvent(AWTEvent event)
    Dispatches an event.
    static AWTEvent
    getCurrentEvent()
    Returns the event currently being dispatched by the EventQueue associated with the calling thread.
    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.
    AWTEvent
    getNextEvent()
    Removes an event from the EventQueue and returns it.
    static void
    invokeAndWait(Runnable runnable)
    Causes runnable to have its run method called in the dispatch thread of the system EventQueue.
    static void
    invokeLater(Runnable runnable)
    Causes runnable to have its run method called in the dispatch thread of the system EventQueue.
    static boolean
    isDispatchThread()
    Returns true if the calling thread is the current AWT EventQueue's dispatch thread.
    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.
    void
    push(EventQueue newEventQueue)
    Replaces the existing EventQueue with the specified one.

    Methods declared in class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    Modifier and Type
    Method
    Description
    protected Object
    clone()
    Creates and returns a copy of this object.
    boolean
    equals(Object obj)
    Indicates whether some other object is "equal to" this one.
    protected void
    finalize()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Finalization is deprecated and subject to removal in a future release.
    final Class<?>
    getClass()
    Returns the runtime class of this Object.
    int
    hashCode()
    Returns a hash code value for this object.
    final void
    notify()
    Wakes up a single thread that is waiting on this object's monitor.
    final void
    notifyAll()
    Wakes up all threads that are waiting on this object's monitor.
    String
    toString()
    Returns a string representation of the object.
    final void
    wait()
    Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
    final void
    wait(long timeoutMillis)
    Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
    final void
    wait(long timeoutMillis, int nanos)
    Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

  • Constructor Details

    • EventQueue

      public EventQueue()
      Initializes a new instance of EventQueue.

  • Method Details

    • 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

    • 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 any thread has interrupted this thread

    • 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 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 of java.awt.AWTEvent, or a subclass of it
      Throws:
      NullPointerException - if event is null
      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 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 JDK, only InputEvents, ActionEvents, and InvocationEvents 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 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:

    • getCurrentEvent

      public static AWTEvent getCurrentEvent()
      Returns 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

    • 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
      Since:
      1.2
      See Also:

    • 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
      Since:
      1.2
      See Also:

    • createSecondaryLoop

      public SecondaryLoop createSecondaryLoop()
      Creates a new secondary loop associated with this event queue. Use the SecondaryLoop.enter() and SecondaryLoop.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 is the 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(Runnable) or invokeAndWait(Runnable) methods to execute a task in the current AWT EventQueue's dispatch thread.

      Returns:
      true if running in the current AWT EventQueue's dispatch thread
      Since:
      1.2
      See Also:

    • invokeLater

      public static void invokeLater(Runnable runnable)
      Causes runnable to have its run method called in the dispatch thread of the system EventQueue. This will happen after all pending events are processed.
      Parameters:
      runnable - the Runnable whose run method should be executed asynchronously in the event dispatch thread of the system EventQueue
      Since:
      1.2
      See Also:

    • invokeAndWait

      public static void invokeAndWait(Runnable runnable) throws InterruptedException, InvocationTargetException
      Causes runnable to have its run method called in the dispatch thread of 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 event dispatcher thread.
      Parameters:
      runnable - the Runnable whose run method should be executed synchronously in the event dispatch thread of the system EventQueue
      Throws:
      InterruptedException - if any thread has interrupted this thread
      InvocationTargetException - if an throwable is thrown when running runnable
      Since:
      1.2
      See Also: