Java AWT: Delegation Event Model

Last updated: February 3, 1997

Purpose

This document explains the rationale behind introducing a new event model into the AWT and describes specifically how the new model maps to the AWT API. This new model has also been adopted by the JavaBeans architecture for general event processing and is described at a high level in the JavaBeans Specification document.

The 1.0 Event Model

The model for event processing in version 1.0 of the AWT is based on inheritance. In order for a program to catch and process GUI events, it must subclass GUI components and override either action() or handleEvent() methods. Returning "true" from one of these methods consumes the event so it is not processed further; otherwise the event is propagated sequentially up the GUI hierarchy until either it is consumed or the root of the hierarchy is reached. The result of this model is that programs have essentially two choices for structuring their event-handling code:

Each individual component can be subclassed to specifically handle its target events. The result of this is a plethora of classes.
All events for an entire hierarchy (or subset thereof) can be handled by a particular container; the result is that the container's overridden action() or handleEvent() method must contain a complex conditional statement in order to process the events.

Issues with the 1.0 Event Model

While the above model works fine for small applets with simple interfaces, it does not scale well for larger java programs for the following reasons:

The requirement to subclass a component in order make any real use of its functionality is cumbersome to developers; subclassing should be reserved for circumstances where components are being extended in some functional or visual way.
The inheritance model does not lend itself well to maintaining a clean separation between the application model and the GUI because application code must be integrated directly into the subclassed components at some level.
Since ALL event types are filtered through the same methods, the logic to process the different event types (and possibly the event targets in approach #2) is complex and error-prone. It is not uncommon for programs to have perplexing bugs that are the result of returning an incorrect result (true or false) from the handleEvent() method. This becomes an even greater problem as new event types are added to the AWT; if the logic of existing handleEvent() methods isn't set up to deal properly with unknown types, programs could potentially break in very unpredictable ways.
There is no filtering of events. Events are always delivered to components regardless of whether the components actually handle them or not. This is a general performance problem, particularly with high-frequency type events such as mouse moves.
For many components, the action() method passes a String parameter which is equivalent to either the label of the component (Button, MenuItem) or the item selected (List, Choice). For programs which use approach #2, this often leads to poor coding and unwieldy string-compare logic that doesn't localize well.

The Delegation Model

Version 1.1 of the Java^TM platform introduced a new delegation-based event model in AWT in order to:

Resolve the problems mentioned previously
Provide a more robust framework to support more complex java programs.

Design Goals

The primary design goals of the new model in the AWT are the following:

Simple and easy to learn
Support a clean separation between application and GUI code
Facilitate the creation of robust event handling code which is less error-prone (strong compile-time checking)
Flexible enough to enable varied application models for event flow and propagation
For visual tool builders, enable run-time discovery of both events that a component generates as well as the events it may observe
Support backward binary compatibility with the old model

Note: These goals are described from the particular perspective of the AWT. Since this model has also been designed to accommodate the JavaBeans architecture, the design goals from the JavaBeans perspective are described in the "Events" section of the JavaBeans Specification and may vary slightly from these goals.

Delegation Model Overview

Event types are encapsulated in a class hierarchy rooted at java.util.EventObject. An event is propagated from a "Source" object to a "Listener" object by invoking a method on the listener and passing in the instance of the event subclass which defines the event type generated.

A Listener is an object that implements a specific EventListener interface extended from the generic java.util.EventListener. An EventListener interface defines one or more methods which are to be invoked by the event source in response to each specific event type handled by the interface.

An Event Source is an object which originates or "fires" events. The source defines the set of events it emits by providing a set of set<EventType>Listener (for single-cast) and/or add<EventType>Listener (for mult-cast) methods which are used to register specific listeners for those events.

In an AWT program, the event source is typically a GUI component and the listener is commonly an "adapter" object which implements the appropriate listener (or set of listeners) in order for an application to control the flow/handling of events. The listener object could also be another AWT component which implements one or more listener interfaces for the purpose of hooking GUI objects up to each other.

Event Hierarchy

Events are no longer represented by a single Event class (like java.awt.Event) with numeric ids, but instead by a hierarchy of event classes. Each event class is defined by the data representing that event type or related group of events types.

Since a single event class may be used to represent more than one event type (i.e. MouseEvent represents mouse up, mouse down, mouse drag, mouse move, etc), some event classes may also contain an "id" (unique within that class) which maps to its specific event types.

The event classes contain no public fields; the data in the event is completely encapsulated by proper get<Attr>()/set<Attr>() methods (where set<Attr>() only exists for attributes on an event that could be modified by a listener).

Although these are the concrete set defined by the AWT, programs are free to define their own event types by subclassing either java.util.EventObject or one of the AWT event classes. Programs should choose event ID values which are greater than the constant:

        java.awt.AWTEvent.RESERVED_ID_MAX

Low-level vs. Semantic Events

The AWT provides two conceptual types of events: low-level and semantic.

A low-level event is one which represents a low-level input or window-system occurrence on a visual component on the screen. The low-level event classes defined by the AWT are as follows:

	java.util.EventObject

		java.awt.AWTEvent

		    java.awt.event.ComponentEvent (component resized, moved, etc.)

			java.awt.event.FocusEvent (component got focus, lost focus)

			java.awt.event.InputEvent

			    java.awt.event.KeyEvent (component got key-press, key-release, etc.)

			    java.awt.event.MouseEvent (component got mouse-down, mouse-move, etc.)

			java.awt.event.ContainerEvent

			java.awt.event.WindowEvent

Semantic events are defined at a higher-level to encapsulate the semantics of a user interface component's model. The semantic event classes defined by the AWT are as follows:

	java.util.EventObject

	    java.awt.AWTEvent

		java.awt.event.ActionEvent ("do a command")

		java.awt.event.AdjustmentEvent ("value was adjusted")

		java.awt.event.ItemEvent ("item state has changed")

		java.awt.event.TextEvent ("the value of the text object changed")

Note that these semantic events are not tied to specific screen-based component classes, but may apply across a set of components which implement a similar semantic model. For example, a Button object will fire an "action" event when it is pressed, a List object will fire an "action" event when an item is double-clicked, a MenuItem will fire an "action" event when it was selected from a menu, and a non-visual Timer object might fire an "action" when its timer goes off (the latter is a hypothetical case).

Event Listeners

An EventListener interface will typically have a separate method for each distinct event type the event class represents. So in essence, particular event semantics are defined by the combination of an Event class paired with a particular method in an EventListener. For example, the FocusListener interface defines two methods, focusGained() and focusLost(), one for each event type that FocusEvent class represents.

The API attempts to define a balance between providing a reasonable granularity of Listener interface types and not providing a separate interface for every single event type.

The low-level listener interfaces defined by the AWT are as follows:

	java.util.EventListener

	    java.awt.event.ComponentListener

	    java.awt.event.ContainerListener

	    java.awt.event.FocusListener

	    java.awt.event.KeyListener

	    java.awt.event.MouseListener

	    java.awt.event.MouseMotionListener

	    java.awt.event.WindowListener

The semantic listener interfaces defined by the AWT are as follows:

	java.util.EventListener

	    java.awt.event.ActionListener

	    java.awt.event.AdjustmentListener

	    java.awt.event.ItemListener

	    java.awt.event.TextListener

Event Sources

Because the events fired by an event source are defined by particular methods on that object, it is completely clear from the API documentation (as well as by using run-time introspection techniques) exactly which events an object supports.

All AWT event sources support a multicast model for listeners. This means that multiple listeners can be added and removed from a single source. The API makes no guarantees about the order in which the events are delivered to a set of registered listeners for a given event on a given source. Additionally, any event which allows its properties to be modified (via setXXX() methods) will be explicitly copied such that each listener receives a replica of the original event. If the order in which events are delivered to listeners is a factor for your program, you should chain the listeners off a single listener which is registered on the source (the fact that the event data is encapsulated in a single object makes propagating the event extremely simple).

Event delivery is synchronous (as with 1.0's handleEvent()), however programs should not make the assumption that the delivery of an event to a set of listeners will occur on the same thread.

Once again, a distinction is drawn between low-level and semantic events. For low-level events, the source will be one of the visual component classes (Button, Scrollbar, etc) since the event is tightly bound to the actual component on the screen. The low-level listeners are defined on the following components:

java.awt.Component

	addComponentListener(ComponentListener l)

	addFocusListener(FocusListener l)

	addKeyListener(KeyListener l)

	addMouseListener(MouseListener l)

	addMouseMotionListener(MouseMotionListener l)

java.awt.Container

	addContainerListener(ContainerListener l)

java.awt.Dialog

	addWindowListener(WindowListener l)

java.awt.Frame

	addWindowListener(WindowListener l)

For semantic events, the source is typically a higher-level interface representing the semantic model (and this higher-level interface is commonly `implemented' by components using the model). Following are the semantic listeners defined for AWT components:

java.awt.Button

	addActionListener(ActionListener l)

java.awt.Choice (implements java.awt.ItemSelectable)

	addItemListener(ItemListener l)

java.awt.Checkbox (implements java.awt.ItemSelectable)

	addItemListener(ItemListener l)

java.awt.CheckboxMenuItem (implements java.awt.ItemSelectable)

	addItemListener(ItemListener l)

java.awt.List (implements java.awt.ItemSelectable)

	addActionListener(ActionListener l)

	addItemListener(ItemListener l)

java.awt.MenuItem

	addActionListener(ActionListener l)

java.awt.Scrollbar (implements java.awt.Adjustable)

	addAdjustmentListener(AdjustmentListener l)

java.awt.TextArea

	addTextListener(TextListener l)

java.awt.TextField

	addActionListener(ActionListener l)

	addTextListener(TextListener l)

Adapters

Since many of the EventListener interfaces are designed to listen to multiple event subtypes (i.e. the MouseListener listens to mouse-down, mouse-up, mouse-enter, etc.), the AWT will provide a a set of abstract "adapter" classes, one which implements each listener interface. This will allow programs to easily subclass the Adapters and override ONLY the methods representing event types they are interested in.

The Adapter classes provided by AWT are as follows:

	java.awt.event.ComponentAdapter

	java.awt.event.ContainerAdapter

	java.awt.event.FocusAdapter

	java.awt.event.KeyAdapter

	java.awt.event.MouseAdapter

	java.awt.event.MouseMotionAdapter

	java.awt.event.WindowAdapter

Note: There are no default Adapters provided for the semantic listeners, since each of those only contain a single method and an adapter would provide no real value.

Filtering for Performance

One of the great benefits of the new model is that since listeners are registered to handle specific event types, it's relatively easy for the toolkit to filter the events and deliver ONLY the events a component is interested in. This was not true with the old model!. Filtering should improve performance, especially with high frequency type events, such as mouse-moves.

All platforms should see some performance improvement from reduced event traffic, but the Solaris implementation should gain exceptional improvement since it's a network-based window system.

Code Example

Following is some sample code that uses the new model:

	
import java.awt.*;
import java.awt.event.*;

public class App {
    public void search() { 
        /* do search operation ...*/ 
        System.out.println("Searching...");
    }
    public void sort() { 
        /* do sort operation ...*/ 
        System.out.println("Sorting....");
    }

    static public void main(String args[]) {
       App app = new App();
       GUI gui = new GUI(app);
    }
}

class Command implements ActionListener  {
    static final int SEARCH = 0;
    static final int SORT = 1;
    int id;
    App app;

    public Command(int id, App app) {
        this.id = id;
        this.app = app;
    }

    public void actionPerformed(ActionEvent e) {
        switch(id) {
          case SEARCH: 
            app.search();
            break;
          case SORT:
            app.sort();
            break;
        }
    }
}

class GUI {

    public GUI(App app) {
        Frame f = new Frame();
        f.setLayout(new FlowLayout());          

        Command searchCmd = new Command(Command.SEARCH, app);
        Command sortCmd = new Command(Command.SORT, app);

        Button b;
        f.add(b = new Button("Search"));
        b.addActionListener(searchCmd);
        f.add(b = new Button("Sort"));
        b.addActionListener(sortCmd);

        List l;
        f.add(l = new List());
        l.add("Alphabetical");
        l.add("Chronological");
        l.addActionListener(sortCmd);
        f.pack();

        f.show();
    }
}

Note in particular the following differences between this example and how this would have been implemented in the old model:

The application code/logic is completely separate from the GUI. The GUI can be modified (or alternatives provided) without touching the application-specific code. This benefit may not be as apparent from this over-simplified case. However, as applications get larger and more complex, this becomes extremely important.
Absolutely no subclassing of AWT components is required.
ONLY the action events are delivered to this program; in the old model all other events would have also been delivered even though they performed no required function.
This code is not necessarily leaner than the code that would have been required for the old event model. This is mostly due to the requirement for writing the adapter class which listens to the events and dispatches them into application commands appropriately. The adapter classes are required because the Java language supports neither method references nor closures. In this context, it was believed that using interfaces/adapters would be the most type-safe option for making connections between objects. This code could be condensed by using the new JDK1.1 "Inner classes" java language feature.

Handling Events in Extended Components

For Java programs which are extending component classes via subclassing, it would be burdensome to require the registration of separate listener objects to respond to events. Therefore, for this case, the AWT defines that each component provide specific protected methods (that can be overridden by subclasses) which actually dispatch the events to listeners if they exist. This way a subclass can simply override one of these methods in order to process an event.

In order to make this as flexible as possible, this event processing capability is provided in two levels. The first is a single method on all components:

     protected void processEvent(AWTEvent)

All events for a component are first funneled through this method so that subclasses can choose to handle all events in a single place (similar to the 1.0 model's "handleEvent" with the main difference being that events are NOT propagated up the containment hierarchy in the new model).

The second option for processing events is provided at the event class level; there is a separate method for each class of event handled by that component:

     protected void processEventClass(EventClass)

For example, the java.awt.List component has the following event-class processing methods:

     protected void processActionEvent(ActionEvent e)

     protected void processItemEvent(ItemEvent e)

By default, the single processEvent method will invoke the proper event-class processing method. The event-class processing method by default will invoke any listeners which are registered. It's important to remember that these methods perform a critical function in the event processing for an AWT component and so if you override them you should remember to call the superclass's method somewhere within your own!

Selecting for Event Types

One of the goals of the listener model is to improve performance by NOT delivering events which components are not interested in. By default, if a listener type is not registered on a component, then those events will NOT be delivered and these processing methods will therefore NOT be called. So if you are using this extension mechanism for event-handling, you'll need to select for the specific types of events your component wishes to receive (in case no listener is registered). This can be done by using the following method on java.awt.Component:

     protected final void enableEvents(long eventsToEnable)

The parameter to this method is a bitwise mask of the event types you wish to enable. The event masks are defined in java.awt.AWTEvent. Note that changing this mask will not affect the delivery of events to listeners -- it only controls the delivery to the component's processing methods. The bottom line is that the set of events which are delivered to processEvent() is defined by the union of event types which have listeners registered and event types explicitly turned on via enableEvents().

Example using Extension Mechanism

Following is an example of how this extension mechanism may be used. For Example, if a subclass of java.awt.Canvas wishes to render some visual feedback when it receives/loses keyboard focus, it could do the following.

     
    public class TextCanvas extends Canvas {
	  boolean haveFocus = false;

	  public TextCanvas() {
	      enableEvents(AWTEvent.FOCUS_EVENT_MASK); // ensure we get focus events
	      ...
	  }
	  protected void processFocusEvent(FocusEvent e) {
	      switch(e.getID()) {
	        case FocusEvent.FOCUS_GAINED:
	          haveFocus = true;
	          break;
	        case FocusEvent.FOCUS_LOST:
	          haveFocus = false;
	      }
	      repaint(); // need to repaint with focus feedback on or off...

	      super.processFocusEvent(e); // let superclass dispatch to listeners
	  }
	  public void paint(Graphics g) {
	      if (haveFocus) {
	          // render focus feedback...
	      }
	  }
	  ...rest of TextCanvas class...
    }

A Word of Caution

In general we recommend you use the delegation-based listener model for most of your basic event handling needs and reserve the use of the above when you are truly extending the look or behavior of a component. This is because the above mechanism suffers from some of the same ills as the 1.0 event model (complex, error-prone logic in processing methods, forgetting to call "super.processEvent", etc.), and unless you clearly understand what you are doing, your program may not behave as you expect!

An alternative to using the above approach would be to simply have your component subclass implement the particular listener interface for the events it wishes to receive and then register itself as a listener. For example, the above code example would be rewritten to:

     
    public class TextCanvas extends Canvas implements FocusListener {
	  boolean haveFocus = false;

	  public TextCanvas() {
	      addFocusListener(this); // ensure we get focus events
	  }
	  public void focusGained(FocusEvent e) {
	       haveFocus = true;
	       repaint();
          }								
	  public void focusLost(FocusEvent e) {
	       haveFocus = false;	      
	       repaint(); 
	  }	      
	  public void paint(Graphics g) {
	      if (haveFocus) {
	          // render focus feedback...
	      }
	  }
	  ...rest of TextCanvas class...
    }

Consuming Events

There are cases where programs need to prevent certain types of events from being processed normally by a component (i.e. a builder wants to use mouse events to enable a user to graphically move a button around and it wants to prevent the mouse press from 'pushing' the button).

We have explicitly enabled this capability for input events only by providing two methods on java.awt.event.InputEvent:

     public void consume()

     public boolean isConsumed()

Note that if some object 'consumes' an input event, it is strictly an indication to the source component that the event should not be processed in its default manner (i.e. consuming a mousePressed event on a Button will prevent it from being activated). The event will still be dispatched to all listeners registered, regardless of whether a listener in the chain consumes the event.

The Event Queue

Another feature of the 1.1 event model is the addition of an event queue class:

     java.awt.EventQueue

This class provides a number of public instance methods to manipulate the queue:

     public synchronized void postEvent(AWTEvent e)

     public synchronized AWTEvent getNextEvent()

     public synchronized AWTEvent peekEvent()

     public synchronized AWTEvent peekEvent(int eventID)

Programs can actually use this class to instantiate their own event queue instances for the purpose of asynchronously posting events. The EventQueue class automatically instantiates an internal thread for dispatching the events appropriately.

In the default JDK implementation, all events generated on components are first posted to a special "system" EventQueue instance before being dispatched to their target component.

The Toolkit class provides a method to access the handle of the system EventQueue instance:

     public final EventQueue getSystemEventQueue()

It would obviously be a security problem to allow untrusted applets to freely manipulate the system event queue, therefore the getSystemEventQueue() method is protected by a SecurityManager check which disallows applets direct access to the system queue. We realize that applets would also like access to an event queue which is scoped to their own containment hierarchies and we are working on an architecture to allow that for a follow-on release.

Compatibility with the old Model

Our intention is to maintain binary compatibility for programs written to the old model for the 1.1 release. However, we strongly recommend new java programs migrate to the new model. We do not encourage the explicit mixing of the two models within a single Applet. However, we realize that programs which code to the new model may need/wish to use existing GUI classes which still use the old model and so we have done our best to ensure this works (for example, the hotjava browser is a java application which will need to be able to load both 1.0 and 1.1 style applets).

The way this works is that the AWT will recognize a component as being either a 1.0-event-model "target" OR a 1.1-event-model "source", but not both. A component is recognized to be a 1.1-event-model "source" by meeting one of the following conditions:

A listener (of any kind) is registered
An event type (of any kind) was explicitly enabled by calling enableEvents()

ELSE the component will be treated as a 1.0-event-model "target" and all events will be delivered to the 1.0 handleEvent method as before.

Note that this is an "all or nothing" distinction and that once the AWT determines a component is a particular event model type, ALL events on that component will be processed in that context. For example, if a TextField object has only a FocusListener registered, then only focus events will be dispatched to the textfield in the 1.1 mechanism and the old 1.0 handleEvent method will NEVER be called (not even for other event types!). So while it is possible to combine components which use the different models, it is not possible to get a single component to mix both models.

One key difference between the two models is that the old model would automatically propagate events up the containment hierarchy, while the new model does NOT propagate events in this way. The way this works for compatibility is that if an event originates on a component which is a 1.0-event-model "target", then it WILL be propagated up the hierarchy in the 1.0 fashion, regardless of the event model type of its ancestor containers. If an event originates on a 1.1-event-model "source", then that event will NOT propagate up the hierarchy, regardless of the event model type of its ancestor containers.

Send feedback to: java-awt@java.sun.com