View Event and Listener Chart

Java AWT Event and Listener Reference Chart

An Overview of Java AWT GUI Events and Event Handling

Definitions and Basic Concepts

The Java Event Delegation Model specifies that:

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.

Sequence of Events

  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.

Registering a Listener

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.

GUI Program Template

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.)

Event Reference Charts

Java AWT Event Reference Chart
EventCommentsCommon
Source
Objects
Useful
Methods
EventObjectAncestor of all event classes (found in java.util) nonegetSource
AWTEvent Parent or ancestor of all AWT event classes (found in java.awt) nonegetId
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 ScrollbargetAdjustable
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 EventInterface (and Adapter if any) Interface
Methods
Comments
EventObject nonenone none
AWTEvent nonenone none
User clicks a button, presses Return while typing in a text field, or chooses a menu item ActionEvent ActionListeneractionPerformed none
AdjustmentEvent AdjustmentListeneradjustmentValueChanged none
ComponentEvent ComponentListeneraddComponentListener
addFocusListener
addInputMethodListener
addKeyListener
addMouseListener
addMouseMotionListener
none
ContainerEvent    
FocusEvent    
InputEvent    
ItemEvent    
KeyEvent    
MouseEvent    
PaintEvent    
TextEvent    
WindowEvent    

contact info
Send comments and questions to pollock@acm.org.
Valid HTML 4.01!   Valid CSS!   CAST: Bobby WorldWide Approved 508   CAST: Bobby WorldWide Approved AAA