Wizard API updated!
Tim Boudreau has released a new version of the Swing Wizard library (version 0.997) that fixes the WizardException bug reported in JavaWorld's recent Open Source Java Project profile. The article's examples have been reworked to test out the new, improved WizardException. Thanks, Tim, for this helpful fix!
Open Source Java Projects: The Wizard API

Newsletter sign-up

Sign up for our technology specific newsletters.

Enterprise Java
View all newsletters

Email Address:

Moving to JDK 1.1: Using the delegation event model to create custom AWT components

Learn how a move to JDK 1.1 affects the way you create custom components

Although many applications currently require JDK 1.0.2, a transition to 1.1 is inevitable for any serious development efforts. This move introduces significant changes to the Abstract Windowing Toolkit (AWT), some of which we'll address in this article. Over the next few virtual pages, we'll step through the how-tos of building reusable AWT components that operate within the new event delegation model. The concepts we cover also will be helpful when you need to update existing custom components to work within the new event model. Those with an eye to the future should make an effort to be aware of the additional changes JDK 1.2 will bring, but that's another story....

To keep things simple, we're going to look at a fairly basic example. My goal is to show you how to acquire, process, and dispatch events, without getting bogged down by the complicated color selection details.

The ColorPicker interface

As you can see in the figure below, the ColorPicker component consists of three regions: The left-hand region displays a swatch of colors, with the red level varying from left to right across the swatch and the green level varying from top to bottom. The user selects red and green levels by clicking in this swatch. The middle region displays a vertical bar of blue. The user specifies the amount blue by clicking on the proper location in the bar. The right-hand region displays the current color, which is a combination of the red, green, and blue levels the user selects. Clicking in this region selects the current color, causing an appropriate AWT event to occur.

The ColorPicker interface


New AWT essentials

The following list includes the essential elements of the AWT that are affected by JDK 1.1, as they apply to custom components:

  • Event model -- Events do not percolate up the container hierarchy as before; instead, interested listeners register themselves with AWT components, and events are multicast through listener interfaces.

  • Event types -- A single monolothic Event class is no longer used for the delivery of all events; instead, different event classes are derived from java.util.EventObject (or, with respect to the AWT, java.awt.AWTEvent) and provide an appropriate interface to the relevant occurrence.

  • Event methods -- Events are no longer delivered to components through the traditional handleEvent() method; instead, a processEvent() method is used along with various associated helpers.

  • Event masks -- Event masks of the events that a particular component should generate are now maintained. This new approach is more efficient because a particular event will not be generated and processed if no target is listening for it. As a result, if you subclass a component, then it will, by default, not generate the usual AWT events. If you wish to receive certain events, you must explicitly flag those event types that you wish generated.

  • Method names -- Many methods have been renamed to achieve a more consistent and Beans-like interface. This change was necessary for a transition to the new event model.



The ColorPicker implementation

Here are the four classes that implement our component:

  • ColorEvent is a custom event class that transports the ColorPicker's Color result.

  • ColorListener is the interface through which interested parties listen for ColorEvents.

  • ColorPicker is the actual graphical color picker component.

  • ColorEventMulticaster is used by the ColorPicker class to maintain a list of registered ColorListeners.


Let's take a detailed look at each of these classes, and then I'll show how you the ColorPicker component works.

Class ColorEvent
Events of type ColorEvent are posted by the ColorPicker component when the user selects a color by clicking in the right-hand GUI region. The event contains a Color field, which is the color selected by the user and is extractable through the getColor() method.

Any event that will be used by an AWT component must be a subclass of the AWTEvent class. In this case, we declare a ColorEvent subclass to transport color events:

import java.awt.AWTEvent;
import java.awt.Color;
public class ColorEvent extends AWTEvent {


All AWT events must be assigned integer identifiers; a valid user identifier is any value above AWTEvent.RESERVED_ID_MAX.

public static final int COLOR_PICKED = AWTEvent.RESERVED_ID_MAX + 1;


Because the class of an event is now used as a distinguishing feature and not just its ID, user components no longer have to choose globally unique values. Instead, this identifier can be used to distinguish among different types of a particular event class. For example, we also could define a COLOR_CHANGED identifier that identifies when the user has changed the selection but not yet accepted the result. We then could distinguish between the two events with one ColorEvent class and two identifiers instead of two separate event classes.

The color associated with this event is stored in the color variable:

protected Color color;


The constructor for this event accepts the source of the event, source, which for this example will be a ColorPicker, and the Color color that was picked:

public ColorEvent (Object source, Color color) {
  super (source, COLOR_PICKED);
  this.color = color;
}


The getColor method allows the event's recipient to extract the associated color:

public Color getColor () {
  return color;
}


The paramString method simply is a convenience method that is used when an AWTEvent is printed to the console:

public String paramString () {
    return "COLOR_PICKED,color=" + color;
}


Interface ColorListener
Classes interested in receiving ColorEvents must implement the ColorListener interface that declares a colorPicked() method through which such events will be delivered.

All event listener interfaces must extend the EventListener dummy interface:

import java.util.EventListener;
public interface ColorListener extends EventListener {


The colorPicked() method will be called on all interested parties when a color has been picked. The parameter e contains the relevant ColorEvent:

  
public void colorPicked (ColorEvent e);


Class ColorPicker
The ColorPicker class is a simple color-picking component that uses the new event delegation model of JDK 1.1. You add it to a container as you would any normal AWT component, and it delivers a new-paradigm event when the user selects a color.

I've intentionally made the color selection user interface very primitive because we are concerned with the internals of 1.1 eventing, not usability. Lines of code that bear particular relevance to JDK 1.1 are highlighted in red. I recommend you experiment with creating a more friendly interface.

We extend Canvas because ColorPicker is an entirely custom-drawn component. If we wanted to build our color picker from other components, we would extend Panel instead:

import java.awt.*;
import java.awt.event.MouseEvent;
public class ColorPicker extends Canvas {


The color picker quantizes the 0-255^3 RGB space into six levels of each component: 0, 51, 102, 153, 204, 255. This corresponds to the typical 256-color browser color cube. For finer granularity of color selection, use more levels:

protected static final int LEVELS = 6;


The current levels of red, green, and blue are stored in the variables r, g, and b, respectively:

protected int r, g, b;


In the constructor we extract the various color levels from the initial color color, and then enable mouse events using the enableEvents() method and a mask of AWTEvent.MOUSE_EVENT_MASK. If we did not enable events in this manner, the mouse events would not be generated by this component. We'll get into this in greater detail later when we discuss the processMouseEvent() method.

public ColorPicker (Color color) {
  r = color.getRed ();
  g = color.getGreen ();
  b = color.getBlue ();
  enableEvents (AWTEvent.MOUSE_EVENT_MASK);
}


The following table shows the event masks in the AWTEvent class that correspond to the different AWT event listeners. Multiple event types can be enabled by either ORing together the masks or by calling enableEvents() repeatedly. Registering a listener for an event type automatically enables the relevant event type.

Event mask Listener interface
ACTION_EVENT_MASK ActionListener
ADJUSTMENT_EVENT_MASK AdjustmentListener
COMPONENT_EVENT_MASK ComponentListener
CONTAINER_EVENT_MASK ContainerListener
FOCUS_EVENT_MASK FocusListener
ITEM_EVENT_MASK ItemListener
KEY_EVENT_MASK KeyListener
MOUSE_EVENT_MASK MouseListener
MOUSE_MOTION_EVENT_MASK MouseMotionListener
TEXT_EVENT_MASK TextListener
WINDOW_EVENT_MASK WindowListener


Event masks and their corresponding listeners


An alternative means for this component to receive its own mouse events would be to implement the MouseListener interface and register as a listener.

This constructor calls the other constructor with an initial color value of black:

public ColorPicker () {
    this (Color.black);
  }


The getPreferredSize() method, shown next, chooses an appropriate size for the component. Under JDK 1.0.2 this method was called preferredSize(). For sake of completeness, we should also implement the getMinimumSize() and getMaximumSize() methods; however, for clarity (not to mention brevity) I've omitted these from this example:

1 | 2 |  Next >
Resources
  • Previous Step By Step articles