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.

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:

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 Colorcolor that was picked:

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:

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.

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:

Moving right along, the paint() method draws a color swatch on the left, a blue bar with a small blue level marker in the middle, and the current color on the right. The details are not particularly interesting; We choose a block size based on the number of levels desired and the component size and then fill in the blanks:

The processMouseEvent() method is called automatically by Component's processEvent() method when a mouse event is generated. We override this method to call our own mousePressed() method for mouse-press events, and then we call the superclass processMouseEvent() to perform further appropriate processing. If there are other registered listeners for our own mouse events, the superclass method will appropriately inform them through their MouseListener interface:

We call mousePressed when the user clicks on the color picker. If the user clicks in the swatch of colors, we assign new red and green color levels, quantized to the chosen number of color levels. If the user clicks in the blue bar, we assign a new blue level. If the user clicks in the right-hand region, we call the postColorEvent() method to post an appropriate event. Let's see how this works:

The postColorEvent method creates a new ColorEvent with this as its origin and the currently selected color as its payload, and posts it to the system event queue. Under JDK 1.0.2 we called the postEvent() method to cause an event to percolate up the container hierarchy. Under JDK 1.1 we can either call dispatchEvent() to immediately dispatch an event or we can post an event to the system event queue. This event queue is monitored by an AWT thread (EventDispatchThread), which simply extracts AWTEvents and calls dispatchEvent() on the component that is the source of the event.