Java AWT Event and Listener Reference Chart

The Java Event Delegation Model specifies that:

• Event sources are objects that produce (or fire) events.  Examples include Buttons, Scrollbars, MenuItems, etc.
  
• Event listeners are objects that handle events.  Listener objects must register their interest in receiving events from some event source.  Whenever an event is produced the event source invokes a method in every registered listener.  (We say the event source notifies the registered listeners.  This is sometimes referred to as a call-back.)
  
• Events are objects that represent various user actions (although there are other event types too such as timer events.)  Examples include Button clicks, typing (each keypress), menu selections, adjusting scrollbars, etc.  Each event object includes a reference to the event source object, the time the event occurred, and other information (depending on the type of event, for instance what key was typed or the coordinates of the mouse).
  

For each Event there is a corresponding Listener interface.  This interface must be implemented by all event listeners interested in receiving these types of event.  It specifies all the methods that must be implemented by the listener.  There may be more than one method per event/listener because each event may have several types.  For instance a MouseEvent is generated when the user (1) moves the cursor onto the event source, (2) moves the cursor off of the event source, (3) presses any mouse buttons when the cursor is on some event source, (4) releases the mouse button when the cursor is on some event source.  For each of these different types of MouseEvents a different method of the MouseListener interface is invoked.

A single user action may generate several different events.  In some cases several different listener methods will be invoked with the same event object.  For example clicking the mouse with the cursor on a Button will generate an ActionEvent and three MouseEvents!  For any registered mouse event listeners, three methods of that interface are invoked in order: mousePressed, mouseReleased, and mouseClicked.  For any registered ActionEvent listeners the method actionPerformed is invoked.

In most cases all but one of the events will be ignored.  In the case of Buttons your code will typically ignore any MouseEvents and only listen for the ActionEvent.

Java makes no guarantee about the ordering of events when several are generated at once.  (In the case of PaintEvents several different events in a row may be coalesced into a single event; that is, all but the last is discarded.)  There is no guarantee about the order that registered listeners are notified of the event when multiple listeners are registered.

The AWT defines many event types and listener interfaces in java.awt.event package.  The most commonly used are shown in the chart below.  (Note there are more events than listener interfaces since some events extend others and some have special purposes.)  All the interfaces inherit from java.util.EventListener and all the events inherit from java.awt.AWTEvent (or each other).  AWTEvent in turn inherits from java.util.EventObject.  By extending EventObject you can define your own custom events (for which you must also define an appropriate interface).

Note that the swing GUI library that was added in version 1.2 (Java2) uses these same events although swing defines several additional events and listeners.

1. An event occurs: User clicks or types something, a timer goes off, data arrives from a network connection, etc.
   
2. The Operating System tells Java (the JRE) of the event.
   
3. The JRE creates an Event object for the event and puts it on the end of the AWT Event Queue.
   
4. The AWT Event Handling Thread does the following (an infinite loop until the JRE shuts down):
   

        while ( true )
        {
           remove next event from the event queue (wait if no events are pending)
           determine the source of the event
           dispatch the event by invoking the method source.dispatchEvent( event )
        }

5. The dispatchEvent supports pre-1.1 style of event handling.  As of Java 1.1 there is a better way but this old way still works.  To support the newer delegation model, dispatchEvent passes the event to the method processEvent.
   
6. Each GUI Java Component has a processEvent method.  This method in turn invokes a method specific to the type of event.  (These extra methods allow you to override some types of event processing while not affecting the other types.)
   
7. The Component that is the event source then enters a loop:

        for each registered listener for this type of event:
            invoke listener.eventHandlingMethod( event )

   The eventHandlingMethod varies depending on the exact type of event.  For example, a MouseEvent has five different types: entered, exited, pressed, released, and clicked.  The appropriate method is invoked with the MouseEvent object depending on which of these types of mouse events actually occurred.
   

So how does some object get to become a registered listener?  If some Object handler is to become a registered listener for MouseEvents for some event source Component comp, then the following with register handler:

comp.addMouseListener( handler );

In many cases an object can register itself to handle (say) ActionEvents (clicking the mouse) on some Button btn by "btn.addActionListener( this )".

There is also a removeMouseListener method, and a similar pair of addXListener and removeXListener for each type of event X.

A typical GUI program or applet initially must perform three tasks: create and initialize the objects to be displayed, position (or layout) the objects in a window, and attach the event listeners with the event sources.  Below is a simple applet called EventDemo that changes its background color when its button is clicked.  It illustrates all three tasks needed by all GUI programs.  Although the example uses AWT Applets, the event code would be nearly the same if Swing and/or Frames were used instead:

import java.applet.Applet;
import java.awt.*;
import java.awt.event.*;

public class EventDemo extends Applet
{
   private Button btn;

   public void init ()
   {
      // Create objects and initialize properties:
      setBackground( Color.YELLOW );
      btn = new Button( " Change color " );

      // Add objects to window (and position them):
      add( btn );

      // Hook up event handlers:
      btn.addActionListener( new
         ActionListener ()
         {
            public void actionPerformed ( ActionEvent ae )
            {
               if ( getBackground() == Color.YELLOW )
                  setBackground( Color.CYAN );
               else
                  setBackground( Color.YELLOW );
            }
         }
      );
   }
}

(See EventDemo.java and EventDemoSwing.java in the resources for Frame (and JFrame) versions, including runnable JAR files for each.)

Java AWT Event Reference Chart

Event	Comments	Common Source Objects	Useful Methods
EventObject	Ancestor of all event classes (found in java.util)	none	getSource
AWTEvent	Parent or ancestor of all AWT event classes (found in java.awt)	none	getId
ActionEvent	This event is generated by a component (such as a Button) when the component-specific action occurs (such as being pressed).  This is probably the most used Event type in a GUI.	Button List MenuItem	getActionCommand getModifiers
AdjustmentEvent	Caused by adjusting scrollbars	Scrollbar	getAdjustable getValue getAdjustmentType
ComponentEvent	Parent of many event class, one or more component events are fired by a Component object just after that component is hidden, made visible, moved, or resized.	Scrollbar Button all others	getComponent
ContainerEvent	Indicates that a container's contents changed because a Component was added or removed to some Container (such as a Panel).	Panel Frame	getChild getContainer
FocusEvent
InputEvent
ItemEvent
KeyEvent
MouseEvent
MouseWheelEvent
PaintEvent
TextEvent
WindowEvent

 

Listener Interface Reference Chart

Action that Generates an Event	Interface (and Adapter if any)	Interface Methods	Comments
EventObject	none	none	none
AWTEvent	none	none	none
User clicks a button, presses Return while typing in a text field, or chooses a menu item ActionEvent	ActionListener	actionPerformed	none
AdjustmentEvent	AdjustmentListener	adjustmentValueChanged	none
ComponentEvent	ComponentListener	addComponentListener addFocusListener addInputMethodListener addKeyListener addMouseListener addMouseMotionListener	none
ContainerEvent
FocusEvent
InputEvent
ItemEvent
KeyEvent
MouseEvent
PaintEvent
TextEvent
WindowEvent