Using the 1.1 Event Model

Before jumping in and describing all the different pieces in detail, we will look at a simple applet that uses the Java 1.1 event model. Example 4.3 is equivalent to Example 4.2, except that it uses the new event model; when you press a mouse button, it just tells you what button you pressed. Notice how the new class, mouseEvent11, separates the user interface from the actual work. The class mouseEvent11 implements a very simple user interface. The class UpDownCatcher handles the events, figures out what to do, and calls some methods in mouseEvent11 to communicate the results. I added a simple interface that is called GetSetString to define the communications between the user interface and the event handler; strictly speaking, this isn't necessary, but it's a good programming practice.

// Java 1.1 only
import java.awt.*;
import java.awt.event.*;
import java.applet.*;
interface GetSetString {
    public void setString (String s);
    public String getString ();
}

The UpDownCatcher class is responsible for handling events generated by the user interface. It extends MouseAdapter so that it needs to implement only the MouseListener methods that we care about (such as mousePressed() and mouseReleased()).

class UpDownCatcher extends MouseAdapter {
    GetSetString gss;
    public UpDownCatcher (GetSetString s) {
        gss = s;
    }

The constructor simply saves a reference to the class that is using this handler.

    public void mousePressed (MouseEvent e) {
        int mods = e.getModifiers();
        if ((mods & MouseEvent.BUTTON3_MASK) != 0) {
            gss.setString ("Right Button Pressed");
        } else if ((mods & MouseEvent.BUTTON2_MASK) != 0) {
            gss.setString ("Middle Button Pressed");
        } else {
            gss.setString ("Left Button Pressed");
        }
        e.getComponent().repaint();
    }

The mousePressed method overrides one of the methods of the MouseAdapter class. The method mousePressed() is called whenever a user presses any mouse button. This method figures out which button on a three-button mouse was pressed and calls the setString() method in the user interface to inform the user of the result.

    public void mouseReleased (MouseEvent e) {
        gss.setString ("Press a Mouse Key");
        e.getComponent().repaint();
    }
}

The mouseReleased method overrides another of the methods of the MouseAdapter class. When the user releases the mouse button, it calls setString() to restore the user interface to the original message.

public class mouseEvent11 extends Applet implements GetSetString {
    private String theString = "Press a Mouse Key";
    public synchronized void setString (String s) {
        theString = s;
    }
    public synchronized String getString () {
        return theString;
    }
    public synchronized void paint (Graphics g) {
        g.drawString (theString, 20, 20);
    }
    public void init () {
        addMouseListener (new UpDownCatcher(this));
    }
}

mouseEvent11 is a very simple applet that implements our user interface. All it does is draw the desired string on the screen; the event handler tells it what string to draw. The init() method creates an instance of the event handler, which is UpDownCatcher, and registers it as interested in mouse events.

Because the user interface and the event processing are in separate classes, it would be easy to use this user interface for another purpose. You would have to replace only the UpDownCatcher class with something else--perhaps a more complex class that reported when the mouse entered and exited the area.

AWTEvent and Its Children

Under the 1.1 delegation event model, all system events are instances of AWTEvent or its subclasses. The model provides two sets of event types. The first set are fairly raw events, such as those indicating when a component gets focus, a key is pressed, or the mouse is moved. These events exist in ComponentEvent and its subclasses, along with some new events previously available only by overriding non-event-related methods. In addition, higher-level event types (for example, selecting a button) are encapsulated in other subclasses of AWTEvent that are not children of ComponentEvent.

java.awt.event.MouseEvent[MOUSE_RELEASED,(69,107),mods=0,clickCount=1] on panel1

java.awt.event.ComponentEvent[COMPONENT_RESIZED (0, 0, 100x100)] on button0

public final static int WINDOW_ACTIVATED

The WINDOW_ACTIVATED constant identifies window events that occur because the user brings the window to the front, either after showing the window, de-iconifying, or removing whatever was in front. The interface method WindowListener.windowActivated() handles this event.

public final static int WINDOW_DEACTIVATED

The WINDOW_DEACTIVATED constant identifies window events that occur because the user makes another window the active window. The interface method WindowListener.windowDeactivated() handles this event.

public WindowEvent(Window source, int id)

This constructor creates a WindowEvent with the given source; the source is the object generating the event. The id field serves as the identifier of the event type. If system generated, the id will be one of the seven constants described previously. However, nothing stops you from creating your own id for your event types.

public Window getWindow()

The getWindow() method returns the Window that generated the event.

public String paramString()

When you call the toString() method of an AWTEvent, the paramString() method is in turn called to build the string to display. At the WindowEvent level, paramString() adds a string containing the event id (if available). In a call to windowClosing(), printing the parameter would yield:

java.awt.event.WindowEvent[WINDOW_CLOSING] on frame0

PaintEvent

The PaintEvent class encapsulates the paint-oriented events. There is no corresponding PaintListener class, so you cannot listen for these events. To process them, override the paint() and update() routines of Component. The PaintEvent class exists to ensure that events are serialized properly through the event queue. Constants

public final static int PAINT_FIRST
public final static int PAINT_LAST

The PAINT_FIRST and PAINT_LAST constants hold the endpoints of the range of identifiers for PaintEvent types.

public final static int PAINT

The PAINT constant identifies paint events that occur because a component needs to be repainted. Override the Component.paint() method to handle this event.

public final static int UPDATE

The UPDATE constant identifies paint events that occur because a component needs to be updated before painting. This usually refreshes the display. Override the Component.update() method to handle this event.

public PaintEvent(Component source, int id, Rectangle updateRect)

This constructor creates a PaintEvent with the given source. The source is the object whose display needs to be updated. The id field identifies the event type. If system generated, the id will be one of the two constants described previously. However, nothing stops you from creating your own id for your event types. updateRect represents the rectangular area of source that needs to be updated.

public Rectangle getUpdateRect()

The getUpdateRect() method returns the rectangular area within the PaintEvent's source component that needs repainting. This area is set by either the constructor or the setUpdateRect() method.

public void setUpdateRect(Rectangle updateRect)

The setUpdateRect() method changes the area of the PaintEvent's source component that needs repainting.

public String paramString()

When you call the toString() method of an AWTEvent, the paramString() method is called in turn to build the string to display. At the PaintEvent level, paramString() adds a string containing the event id (if available) along with the area requiring repainting (a clipping rectangle). If you peek in the event queue, one possible result may yield:

java.awt.event.PaintEvent[PAINT,updateRect=java.awt.Rectangle[x=0,y=0,
width=192,height=173]] on frame0

InputEvent

The InputEvent class provides the basis for the key and mouse input and movement routines. KeyEvent and MouseEvent provide the specifics of each. Constants

The constants of InputEvent help identify which modifiers are present when an input event occurs, as shown in Example 4.3. To examine the event modifiers and test for the presence of these masks, call getModifiers() to get the current set of modifiers.

public final static int ALT_MASK
public final static int CTRL_MASK
public final static int META_MASK
public final static int SHIFT_MASK

The first set of InputEvent masks are for the different modifier keys on the keyboard. They are often set to indicate which button on a multibutton mouse has been pressed.

public final static int BUTTON1_MASK
public final static int BUTTON2_MASK
public final static int BUTTON3_MASK

The button mask constants are equivalents for the modifier masks, allowing you to write more intelligible code for dealing with button events. BUTTON2_MASK is the same as ALT_MASK, and BUTTON3_MASK is the same as META_MASK; BUTTON1_MASK currently isn't usable and is never set. For example, if you want to check whether the user pressed the second (middle) mouse button, you can test against BUTTON2_MASK rather than ALT_MASK. Example 4.3 demonstrates how to use these constants.

InputEvent is an abstract class with no public constructors. Methods

Unlike the Event class, InputEvent has an isAltDown() method to check the ALT_MASK setting.

public boolean isAltDown()

The isAltDown() method checks to see if ALT_MASK is set. If so, isAltDown() returns true; otherwise, it returns false.

public boolean isControlDown()

The isControlDown() method checks to see if CONTROL_MASK is set. If so, isControlDown() returns true; otherwise, it returns false.

public boolean isMetaDown()

The isMetaDown() method checks to see if META_MASK is set. If so, the method isMetaDown() returns true; otherwise, it returns false.

public boolean isShiftDown()

The isShiftDown() method checks to see if SHIFT_MASK is set. If so, the method isShiftDown() returns true; otherwise, it returns false.

public int getModifiers()

The getModifiers() method returns the current state of the modifier keys. For each modifier key pressed, a different flag is raised in the return argument. To check if a modifier is set, AND the return value with a flag and check for a nonzero value.

if ((ie.getModifiers() & MouseEvent.META_MASK) != 0) {
    System.out.println ("Meta is set");
}

public long getWhen()

The getWhen() method returns the time at which the event occurred. The return value is in milliseconds. Convert the long value to a Date to examine the contents. For example:

Date d = new Date (ie.getWhen());

public void consume()

This class overrides the AWTEvent.consume() method to make it public. Anyone, not just a subclass, can mark an InputEvent as consumed.

public boolean isConsumed()

This class overrides the AWTEvent.isconsumed() method to make it public. Anyone can find out if an InputEvent has been consumed.

KeyEvent

The KeyEvent class is a subclass of InputEvent for dealing with keyboard events. There are two fundamental key actions: key presses and key releases. These are represented by KEY_PRESSED and KEY_RELEASED events. Of course, it's inconvenient to think in terms of all these individual actions, so Java also keeps track of the "logical" keys you type. These are represented by KEY_TYPED events. For every keyboard key pressed, a KeyEvent.KEY_PRESSED event occurs; the key that was pressed is identified by one of the virtual keycodes from Table 4.4 and is available through the getKeyCode() method. For example, if you type an uppercase A, you will get two KEY_PRESSED events, one for shift (VK_SHIFT) and one for the "a" (VK_A). You will also get two KeyEvent.KEY_RELEASED events. However, there will only be one KeyEvent.KEY_TYPED event; if you call getKeyChar() for the KEY_TYPED event, the result will be the Unicode character "A" (type char). KEY_TYPED events do not happen for action-oriented keys like function keys. Constants

Like the Event class, numerous constants help you identify all the keyboard keys. Table 4.4 shows the constants that refer to these keyboard keys. The values are all declared public static final int. A few keys represent ASCII characters that have string equivalents like \n.

public final static int VK_UNDEFINED

When a KEY_TYPED event happens, there is no keycode. If you ask for it, the getKeyCode() method returns VK_UNDEFINED.

public final static char CHAR_UNDEFINED

For KEY_PRESSED and KEY_RELEASED events that do not have a corresponding Unicode character to display (like Shift), the getKeyChar() method returns CHAR_UNDEFINED.

Other constants identify what the user did with a key.

public final static int KEY_FIRST
public final static int KEY_LAST

The KEY_FIRST and KEY_LAST constants hold the endpoints of the range of identifiers for KeyEvent types.

public final static int KEY_PRESSED

The KEY_PRESSED constant identifies key events that occur because a keyboard key has been pressed. To differentiate between action and non-action keys, call the isActionKey() method described later. The KeyListener.keyPressed() interface method handles this event.

public final static int KEY_RELEASED

The KEY_RELEASED constant identifies key events that occur because a keyboard key has been released. The KeyListener.keyReleased() interface method handles this event.

public final static int KEY_TYPED

The KEY_TYPED constant identifies a combination of a key press followed by a key release for a non-action oriented key. The KeyListener.keyTyped() interface method handles this event.

public KeyEvent(Component source, int id, long when, int modifiers, int keyCode, char keyChar)

This constructor[2] creates a KeyEvent with the given source; the source is the object generating the event. The id field identifies the event type. If system-generated, the id will be one of the constants above. However, nothing stops you from creating your own id for your event types. The when parameter represents the time the event happened. The modifiers parameter holds the state of the various modifier keys; masks to represent these keys are defined in the InputEvent class. Finally, keyCode is the virtual key that triggered the event, and keyChar is the character that triggered it.

[2] Beta releases of Java 1.1 have an additional constructor that lacks the keyChar parameter. Comments in the code indicate that this constructor will be deleted prior to the 1.1.1 release.

The KeyEvent constructor throws the IllegalArgumentException run-time exception in two situations. First, if the id is KEY_TYPED and keyChar is CHAR_UNDEFINED, it throws an exception because if a key has been typed, it must be associated with a character. Second, if the id is KEY_TYPED and keyCode is not VK_UNDEFINED, it throws an exception because typed keys frequently represent combinations of key codes (for example, Shift struck with "a"). It is legal for a KEY_PRESSED or KEY_RELEASED event to contain both a keyCode and a keyChar, though it's not clear what such an event would represent.

public char getKeyChar()

The getKeyChar() method retrieves the Unicode character associated with the key in this KeyEvent. If there is no character, CHAR_UNDEFINED is returned.

public void setKeyChar(char KeyChar)

The setKeyChar() method allows you to change the character for the KeyEvent. You could use this method to convert characters to uppercase.

public int getKeyCode()

The getKeyCode() method retrieves the virtual keycode (i.e., one of the constants in Table 4.4) of this KeyEvent.

public void setKeyCode(int keyCode)

The setKeyCode() method allows you to change the keycode for the KeyEvent. Changes you make to the KeyEvent are seen by subsequent listeners and the component's peer.

public void setModifiers(int modifiers)

The setModifiers() method allows you to change the modifier keys associated with a KeyEvent to modifiers. The parent class InputEvent already has a getModifiers() method that is inherited. Since this is your own personal copy of the KeyEvent, no other listener can find out about the change.

public boolean isActionKey()

The isActionKey() method allows you to check whether the key associated with the KeyEvent is an action key (e.g., function, arrow, keypad) or not (e.g., an alphanumeric key). For action keys, this method returns true; otherwise, it returns false. For action keys, the keyChar field usually has the value CHAR_UNDEFINED.

public static String getKeyText (int keyCode)

The static getKeyText() method returns the localized textual string for keyCode. For each nonalphanumeric virtual key, there is a key name (the "key text"); these names can be changed using the AWT properties. Table 4.5 shows the properties used to redefine the key names and the default name for each key.

public static String getKeyModifiersText (int modifiers)

The static getKeyModifiersText() method returns the localized textual string for modifiers. The parameter modifiers is a combination of the key masks defined by the InputEvent class. As with the keys themselves, each modifier is associated with a textual name. If multiple modifiers are set, they are concatenated with a plus sign (+) separating them. Similar to getKeyText(), the strings are localized because for each modifier, an awt property is available to redefine the string. Table 4.6 lists the properties and the default modifier names.

public String paramString()

When you call the toString() method of an AWTEvent, the paramString() method is called in turn to build the string to display. At the KeyEvent level, paramString() adds a textual string for the id (if available), the text for the key (if available from getKeyText()), and modifiers (from getKeyModifiersText()). A key press event would result in something like the following:

java.awt.event.KeyEvent[KEY_PRESSED,keyCode=118,
F7,modifiers=Ctrl+Shift] on textfield0

MouseEvent

The MouseEvent class is a subclass of InputEvent for dealing with mouse events. Constants

public final static int MOUSE_FIRST
public final static int MOUSE_LAST

The MOUSE_FIRST and MOUSE_LAST constants hold the endpoints of the range of identifiers for MouseEvent types.

public final static int MOUSE_CLICKED

The MOUSE_CLICKED constant identifies mouse events that occur when a mouse button is clicked. A mouse click consists of a mouse press and a mouse release. The MouseListener.mouseClicked() interface method handles this event.

public final static int MOUSE_DRAGGED

The MOUSE_DRAGGED constant identifies mouse events that occur because the mouse is moved over a component with a mouse button pressed. The interface method MouseMotionListener.mouseDragged() handles this event.

public final static int MOUSE_ENTERED

The MOUSE_ENTERED constant identifies mouse events that occur when the mouse first enters a component. The MouseListener.mouseEntered() interface method handles this event.

public final static int MOUSE_EXITED

The MOUSE_EXISTED constant identifies mouse events that occur because the mouse leaves a component's space. The MouseListener.mouseExited() interface method handles this event.

public final static int MOUSE_MOVED

The MOUSE_MOVED constant identifies mouse events that occur because the mouse is moved without a mouse button down. The interface method MouseMotionListener.mouseMoved() handles this event.

public final static int MOUSE_PRESSED

The MOUSE_PRESSED constant identifies mouse events that occur because a mouse button has been pressed. The MouseListener.mousePressed() interface method handles this event.

public final static int MOUSE_RELEASED

The MOUSE_RELEASED constant identifies mouse events that occur because a mouse button has been released. The MouseListener.mouseReleased() interface method handles this event.

public MouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger)

This constructor creates a MouseEvent with the given source; the source is the object generating the event. The id field serves as the identifier of the event type. If system-generated, the id will be one of the constants described in the previous section. However, nothing stops you from creating your own id for your event types. The when parameter represents the time the event happened. The modifiers parameter holds the state of the various modifier keys, using the masks defined for the InputEvent class, and lets you determine which button was pressed. (x, y) represents the coordinates of the event relative to the origin of source, while clickCount designates the number of consecutive times the mouse button was pressed within an indeterminate time period. Finally, the popupTrigger parameter signifies whether this mouse event should trigger the display of a PopupMenu, if one is available. (The PopupMenu class is discussed in Chapter 10, Would You Like to Choose from the Menu?)

public int getX()

The getX() method returns the current x coordinate of the event relative to the source.

public int getY()

The getY() method returns the current y coordinate of the event relative to the source.

public synchronized Point getPoint()

The getPoint() method returns the current x and y coordinates of the event relative to the event source.

public synchronized void translatePoint(int x, int y)

The translatePoint() method translates the x and y coordinates of the MouseEvent instance by x and y. This method functions similarly to the Event.translate() method.

public int getClickCount()

The getClickCount() method retrieves the current clickCount setting for the event.

public boolean isPopupTrigger()

The isPopupTrigger() method retrieves the state of the popupTrigger setting for the event. If this method returns true and the source of the event has an associated PopupMenu, the event should be used to display the menu, as shown in the following code. Since the action the user performs to raise a pop-up menu is platform specific, this method lets you raise a pop-up menu without worrying about what kind of event took place. You only need to call isPopupTrigger() and show the menu if it returns true.

public void processMouseEvent(MouseEvent e) {
    if (e.isPopupTrigger())
        aPopup.show(e.getComponent(), e.getX(), e.getY());
    super.processMouseEvent(e);
}

public String paramString()

When you call the toString() method of an AWTEvent, the paramString() method is called in turn to build the string to display. At the MouseEvent level, a textual string for the id (if available) is tacked on to the coordinates, modifiers, and click count. A mouse down event would result in something like the following:

java.awt.event.MouseEvent[MOUSE_PRESSED,(5,7),mods=0,clickCount=2] on textfield0

ActionEvent

The ActionEvent class is the first higher-level event class. It encapsulates events that signify that the user is doing something with a component. When the user selects a button, list item, or menu item, or presses the Return key in a text field, an ActionEvent passes through the event queue looking for listeners. Constants

public final static int ACTION_FIRST
public final static int ACTION_LAST

The ACTION_FIRST and ACTION_LAST constants hold the endpoints of the range of identifiers for ActionEvent types.

public final static int ACTION_PERFORMED

The ACTION_PERFORMED constant represents when a user activates a component. The ActionListener.actionPerformed() interface method handles this event.

public static final int ALT_MASK
public static final int CTRL_MASK
public static final int META_MASK
public static final int SHIFT_MASK

Similar to the mouse events, action events have modifiers. However, they are not automatically set by the system, so they don't help you see what modifiers were pressed when the event occurred. You may be able to use these constants if you are generating your own action events. To see the value of an action event's modifiers, call getModifiers().

public ActionEvent(Object source, int id, String command)

This constructor creates an ActionEvent with the given source; the source is the object generating the event. The id field serves as the identifier of the event type. If system-generated, the id will be ACTION_PERFORMED. However, nothing stops you from creating your own id for your event types. The command parameter is the event's action command. Ideally, the action command should be some locale-independent string identifying the user's action. Most components that generate action events set this field to the selected item's label by default.

public ActionEvent(Object source, int id, String command, int modifiers)

This constructor adds modifiers to the settings for an ActionEvent. This allows you to define action-oriented events that occur only if certain modifier keys are pressed.

public String getActionCommand()

The getActionCommand() method retrieves the command field from the event. It represents the command associated with the object that triggered the event. The idea behind the action command is to differentiate the command associated with some event from the displayed content of the event source. For example, the action command for a button may be Help. However, what the user sees on the label of the button could be a string localized for the environment of the user. Instead of having your event handler look for 20 or 30 possible labels, you can test whether an event has the action command Help.

public int getModifiers()

The getModifiers() method returns the state of the modifier keys. For each one set, a different flag is raised in the method's return value. To check if a modifier is set, AND the return value with a flag, and check for a nonzero value.

public String paramString()

When you call the toString() method of an AWTEvent, the paramString() method is called in turn to build the string to display. At the ActionEvent level, paramString() adds a textual string for the event id (if available), along with the command from the constructor. When the user selects a Button with the action command Help, printing the resulting event yields:

java.awt.event.ActionEvent[ACTION_PERFORMED,cmd=Help] on button0

AdjustmentEvent

The AdjustmentEvent class is another higher-level event class. It encapsulates events that represent scrollbar motions. When the user moves the slider of a scrollbar or scroll pane, an AdjustmentEvent passes through the event queue looking for listeners. Although there is only one type of adjustment event, there are five subtypes represented by constants UNIT_DECREMENT, UNIT_INCREMENT, and so on. Constants

public final static int ADJUSTMENT_FIRST
public final static int ADJUSTMENT_LAST

The ADJUSTMENT_FIRST and ADJUSTMENT_LAST constants hold the endpoints of the range of identifiers for AdjustmentEvent types.

public final static int ADJUSTMENT_VALUE_CHANGED

The ADJUSTMENT_VALUE_CHANGED constant identifies adjustment events that occur because a user moves the slider of a Scrollbar or ScrollPane. The AdjustmentListener.adjustmentValueChanged() interface method handles this event.

public static final int UNIT_DECREMENT

UNIT_DECREMENT identifies adjustment events that occur because the user selects the increment arrow.

public static final int UNIT_INCREMENT

UNIT_INCREMENT identifies adjustment events that occur because the user selects the decrement arrow.

public static final int BLOCK_DECREMENT

BLOCK_DECREMENT identifies adjustment events that occur because the user selects the block decrement area, between the decrement arrow and the slider.

public static final int BLOCK_INCREMENT

BLOCK_INCREMENT identifies adjustment events that occur because the user selects the block increment area, between the increment arrow and the slider.

public static final int TRACK

TRACK identifies adjustment events that occur because the user selects the slider and drags it. Multiple adjustment events of this subtype usually occur consecutively.

public AdjustmentEvent(Adjustable source, int id, int type, int value)

This constructor creates an AdjustmentEvent with the given source; the source is the object generating the event. The id field serves as the identifier of the event type. If system-generated, the id of the AdjustmentEvent will be ADJUSTMENT_VALUE_CHANGED. However, nothing stops you from creating your own id for your event types. The type parameter is normally one of the five subtypes, with value being the current setting of the slider, but is not restricted to that.

public Adjustable getAdjustable()

The getAdjustable() method retrieves the Adjustable object associated with this event--that is, the event's source.

public int getAdjustmentType()

The getAdjustmentType() method retrieves the type parameter from the constructor. It represents the subtype of the current event and, if system-generated, is one of the following constants: UNIT_DECREMENT, UNIT_INCREMENT, BLOCK_DECREMENT, BLOCK_INCREMENT, or TRACK.

public int getValue()

The getValue() method retrieves the value parameter from the constructor. It represents the current setting of the adjustable object.

public String paramString()

When you call the toString() method of an AWTEvent, the paramString() method is called to help build the string to display. At the AdjustableEvent level, paramString() adds a textual string for the event id (if available), along with a textual string of the type (if available), and value. For example:

java.awt.event.AdjustableEvent[ADJUSTMENT_VALUE_CHANGED,
adjType=TRACK,value=27] on scrollbar0

ItemEvent

The ItemEvent class is another higher-level event class. It encapsulates events that occur when the user selects a component, like ActionEvent. When the user selects a checkbox, choice, list item, or checkbox menu item, an ItemEvent passes through the event queue looking for listeners. Although there is only one type of ItemEvent, there are two subtypes represented by the constants SELECTED and DESELECTED. Constants

public final static int ITEM_FIRST
public final static int ITEM_LAST

The ITEM_FIRST and ITEM_LAST constants hold the endpoints of the range of identifiers for ItemEvent types.

public final static int ITEM_STATE_CHANGED

The ITEM_STATE_CHANGED constant identifies item events that occur because a user selects a component, thus changing its state. The interface method ItemListener.itemStateChanged() handles this event.

public static final int SELECTED

SELECTED indicates that the user selected the item.

public static final int DESELECTED

DESELECTED indicates that the user deselected the item.

public ItemEvent(ItemSelectable source, int id, Object item, int stateChange)

This constructor creates a ItemEvent with the given source; the source is the object generating the event. The id field serves as the identifier of the event type. If system-generated, the id will be ITEM_STATE_CHANGE. However, nothing stops you from creating your own id for your event types. The item parameter represents the text of the item selected: for a Checkbox, this would be its label, for a Choice the current selection. For your own events, this parameter could be virtually anything, since its type is Object.

public ItemSelectable getItemSelectable()

The getItemSelectable() method retrieves the ItemSelectable object associated with this event--that is, the event's source.

public Object getItem()

The getItem() method returns the item that was selected. This usually represents some text to help identify the source but could be nearly anything for user-generated events.

public int getStateChange()

The getStateChange() method returns the stateChange parameter from the constructor and, if system generated, is either SELECTED or DESELECTED.

public String paramString()

When you call the toString() method of an AWTEvent, the paramString() method is called in turn to build the string to display. At the ItemEvent level, paramString() adds a textual string for the event id (if available), along with a textual string indicating the value of stateChange (if available) and item. For example:

java.awt.event.ItemEvent[ITEM_STATE_CHANGED,item=Help,
stateChange=SELECTED] on checkbox1

TextEvent

The TextEvent class is yet another higher-level event class. It encapsulates events that occur when the contents of a TextComponent have changed, although is not required to have a TextComponent source. When the contents change, either programmatically by a call to setText() or because the user typed something, a TextEvent passes through the event queue looking for listeners. Constants

public final static int TEXT_FIRST
public final static int TEXT_LAST

The TEXT_FIRST and TEXT_LAST constants hold the endpoints of the range of identifiers for TextEvent types.

public final static int TEXT_VALUE_CHANGED

The TEXT_VALUE_CHANGED constant identifies text events that occur because a user changes the contents of a text component. The interface method TextListener.textValueChanged() handles this event.

public TextEvent(Object source, int id)

This constructor creates a TextEvent with the given source; the source is the object generating the event. The id field identifies the event type. If system-generated, the id will be TEXT_VALUE_CHANGE. However, nothing stops you from creating your own id for your event types.

public String paramString()

When you call the toString() method of an AWTEvent, the paramString() method is called in turn to build the string to display. At the TextEvent level, paramString() adds a textual string for the event id (if available).

ActionListener

The ActionListener interface contains the one method that is called when an ActionEvent occurs. It has no adapter class. For an object to listen for action events, it is necessary to call the addActionListener() method with the class that implements the ActionListener interface as the parameter. The method addActionListener() is implemented by Button, List, MenuItem, and TextField components. Other components don't generate action events.

public abstract void actionPerformed(ActionEvent e)

The actionPerformed() method is called when a component is selected or activated. Every component is activated differently; for a List, activation means that the user has double-clicked on an entry. See the appropriate section for a description of each component.

actionPerformed() is the Java 1.1 equivalent of the action() method in the 1.0 event model.

AdjustmentListener

The AdjustmentListener interface contains the one method that is called when an AdjustmentEvent occurs. It has no adapter class. For an object to listen for adjustment events, it is necessary to call addAdjustmentListener() with the class that implements the AdjustmentListener interface as the parameter. The addAdjustmentListener() method is implemented by the Scrollbar component and the Adjustable interface. Other components don't generate adjustment events.

public abstract void adjustmentValueChanged(AdjustmentEvent e)

The adjustmentValueChanged() method is called when a slider is moved. The Scrollbar and ScrollPane components have sliders, and generate adjustment events when the sliders are moved. (The TextArea and List components also have sliders, but do not generate adjustment events.) See the appropriate section for a description of each component.

There is no real equivalent to adjustmentValueChanged() in Java 1.0; to work with scrolling events, you had to override the handleEvent() method.

ComponentListener and ComponentAdapter

The ComponentListener interface contains four methods that are called when a ComponentEvent occurs; component events are used for general actions on components, like moving or resizing a component. The adapter class corresponding to ComponentListener is ComponentAdapter. If you care only about one or two of the methods in ComponentListener, you can subclass the adapter and override only the methods that you are interested in. For an object to listen for component events, it is necessary to call Component.addComponentListener() with the class that implements the interface as the parameter.

public abstract void componentResized(ComponentEvent e)

The componentResized() method is called when a component is resized (for example, by a call to Component.setSize()).

public abstract void componentMoved(ComponentEvent e)

The componentMoved() method is called when a component is moved (for example, by a call to Component.setLocation()).

public abstract void componentShown(ComponentEvent e)

The componentShown() method is called when a component is shown (for example, by a call to Component.show()).

public abstract void componentHidden(ComponentEvent e)

The componentHidden() method is called when a component is hidden (for example, by a call to Component.hide()).

ContainerListener and ContainerAdapter

The ContainerListener interface contains two methods that are called when a ContainerEvent occurs; container events are generated when components are added to or removed from a container. The adapter class for ContainerListener is ContainerAdapter. If you care only about one of the two methods in ContainerListener, you can subclass the adapter and override only the method that you are interested in. For a container to listen for container events, it is necessary to call Container.addContainerListener() with the class that implements the interface as the parameter.

public abstract void componentAdded(ContainerEvent e)

The componentAdded() method is called when a component is added to a container (for example, by a call to Container.add()).

public abstract void componentRemoved(ContainerEvent e)

The componentRemoved() method is called when a component is removed from a container (for example, by a call to Container.remove()).

FocusListener and FocusAdapter

The FocusListener interface has two methods, which are called when a FocusEvent occurs. Its adapter class is FocusAdapter. If you care only about one of the methods, you can subclass the adapter and override the method you are interested in. For an object to listen for a FocusEvent, it is necessary to call the Component.addFocusListener() method with the class that implements the FocusListener interface as the parameter.

public abstract void focusGained(FocusEvent e)

The focusGained() method is called when a component receives input focus, usually by the user clicking the mouse in the area of the component.

This method is the Java 1.1 equivalent of Component.gotFocus() in the Java 1.0 event model.

public abstract void focusLost(FocusEvent e)

The focusLost() method is called when a component loses the input focus.

This method is the Java 1.1 equivalent of Component.lostFocus() in the Java 1.0 event model.

ItemListener

The ItemListener interface contains the one method that is called when an ItemEvent occurs. It has no adapter class. For an object to listen for an ItemEvent, it is necessary to call addItemListener() with the class that implements the ItemListener interface as the parameter. The addItemListener() method is implemented by the Checkbox, CheckboxMenuItem, Choice, and List components. Other components don't generate item events.

public abstract void itemStateChanged(ItemEvent e)

The itemStateChanged() method is called when a component's state is modified. Every component is modified differently; for a List, modifying the component means single-clicking on an entry. See the appropriate section for a description of each component.

KeyListener and KeyAdapter

The KeyListener interface contains three methods that are called when a KeyEvent occurs; key events are generated when the user presses or releases keys. The adapter class for KeyListener is KeyAdapter. If you only care about one or two of the methods in KeyListener, you can subclass the adapter and only override the methods that you are interested in. For an object to listen for key events, it is necessary to call Component.addKeyListener() with the class that implements the interface as the parameter.

public abstract void keyPressed(KeyEvent e)

The keyPressed() method is called when a user presses a key. A key press is, literally, just what it says. A key press event is called for every key that is pressed, including keys like Shift and Control. Therefore, a KEY_PRESSED event has a virtual key code identifying the physical key that was pressed; but that's not the same as a typed character, which usually consists of several key presses (for example, Shift+A to type an uppercase A). The keyTyped() method reports actual characters.

This method is the Java 1.1 equivalent of Component.keyDown() in the Java 1.0 event model.

public abstract void keyReleased(KeyEvent e)

The keyReleased() method is called when a user releases a key. Like the keyPressed() method, when dealing with keyReleased(), you must think of virtual key codes, not characters.

This method is the Java 1.1 equivalent of Component.keyUp() in the Java 1.0 event model.

public abstract void keyTyped(KeyEvent e)

The keyTyped() method is called when a user types a key. The method keyTyped() method reports the actual character typed. Action-oriented keys, like function keys, do not trigger this method being called.

MouseListener and MouseAdapter

The MouseListener interface contains five methods that are called when a nonmotion oriented MouseEvent occurs; mouse events are generated when the user presses or releases a mouse button. (Separate classes, MouseMotionListener and MouseMotionAdapter, are used to handle mouse motion events; this means that you can listen for mouse clicks only, without being bothered by thousands of mouse motion events.) The adapter class for MouseListener is MouseAdapter. If you care about only one or two of the methods in MouseListener, you can subclass the adapter and override only the methods that you are interested in. For an object to listen for mouse events, it is necessary to call the method Window.addWindowListener() with the class that implements the interface as the parameter.

public abstract void mouseEntered(MouseEvent e)

The mouseEntered() method is called when the mouse first enters the bounding area of the component.

This method is the Java 1.1 equivalent of Component.mouseEnter() in the Java 1.0 event model.

public abstract void mouseExited(MouseEvent e)

The mouseExited() method is called when the mouse leaves the bounding area of the component.

This method is the Java 1.1 equivalent of Component.mouseExit() in the Java 1.0 event model.

public abstract void mousePressed(MouseEvent e)

The mousePressed() method is called each time the user presses a mouse button within the component's space.

This method is the Java 1.1 equivalent of Component.mouseDown() in the Java 1.0 event model.

public abstract void mouseReleased(MouseEvent e)

The mouseReleased() method is called when the user releases the mouse button after a mouse press. The user does not have to be over the original component any more; the original component (i.e., the component in which the mouse was pressed) is the source of the event.

This method is the Java 1.1 equivalent of Component.mouseUp() in the Java 1.0 event model.

public abstract void mouseClicked(MouseEvent e)

The mouseClicked() method is called once each time the user clicks a mouse button; that is, once for each mouse press/mouse release combination.

MouseMotionListener and MouseMotionAdapter

The MouseMotionListener interface contains two methods that are called when a motion-oriented MouseEvent occurs; mouse motion events are generated when the user moves the mouse, whether or not a button is pressed. (Separate classes, MouseListener and MouseAdapter, are used to handle mouse clicks and entering/exiting components. This makes it easy to ignore mouse motion events, which are very frequent and can hurt performance. You should listen only for mouse motion events if you specifically need them.) MouseMotionAdapter is the adapter class for MouseMotionListener. If you care about only one of the methods in MouseMotionListener, you can subclass the adapter and override only the method that you are interested in. For an object to listen for mouse motion events, it is necessary to call Component.addMouseMotionListener() with the class that implements the interface as the parameter.

public abstract void mouseMoved(MouseEvent e)

The mouseMoved() method is called every time the mouse moves within the bounding area of the component, and no mouse button is pressed.

This method is the Java 1.1 equivalent of Component.mouseMove() in the Java 1.0 event model.

public abstract void mouseDragged(MouseEvent e)

The mouseDragged() method is called every time the mouse moves while a mouse button is pressed. The source of the MouseEvent is the component that was under the mouse when it was first pressed.

This method is the Java 1.1 equivalent of Component.mouseDrag() in the Java 1.0 event model.

TextListener

The TextListener interface contains the one method that is called when a TextEvent occurs. It has no adapter class. For an object to listen for a TextEvent, it is necessary to call addTextListener() with the class that implements the TextListener interface as the parameter. The addTextListener() method is implemented by the TextComponent class, and thus the TextField and TextArea components. Other components don't generate text events.

public abstract void textValueChanged(TextEvent e)

The textValueChanged() method is called when a text component's contents are modified, either by the user (by a keystroke) or programmatically (by the setText() method).

WindowListener and WindowAdapter

The WindowListener interface contains seven methods that are called when a WindowEvent occurs; window events are generated when something changes the visibility or status of a window. The adapter class for WindowListener is WindowAdapter. If you care about only one or two of the methods in WindowListener, you can subclass the adapter and override only the methods that you are interested in. For an object to listen for window events, it is necessary to call the method Window.addWindowListener() or Dialog.addWindowListener() with the class that implements the interface as the parameter.

public abstract void windowOpened(WindowEvent e)

The windowOpened() method is called when a Window is first opened.

public abstract void windowClosing(WindowEvent e)

The windowClosing() method is triggered whenever the user tries to close the Window.

public abstract void windowClosed(WindowEvent e)

The windowClosed() method is called after the Window has been closed.

public abstract void windowIconified(WindowEvent e)

The windowIconified() method is called whenever a user iconifies a Window.

public abstract void windowDeiconified(WindowEvent e)

The windowDeiconified() method is called when the user deiconifies the Window.

public abstract void windowActivated(WindowEvent e)

The windowActivated() method is called whenever a Window is brought to the front.

public abstract void windowDeactivated(WindowEvent e)

The windowDeactivated() method is called when the Window is sent away from the front, either through iconification, closing, or another window becoming active.

Using an event multicaster

Example 4.4 shows how to use AWTEventMulticaster to create a component that generates ItemEvents. The AWTEventMulticaster is used in the addItemListener() and removeItemListener() methods. When it comes time to generate the event in processEvent(), the itemStateChanged() method is called to notify anyone who might be interested. The item event is generated when a mouse button is clicked; we just count the number of clicks to determine whether an item was selected or deselected. Since we do not have any mouse listeners, we need to enable mouse events with enableEvents() in the constructor, as shown in the following example.

// Java 1.1 only
import java.awt.*;
import java.awt.event.*;
class ItemEventComponent extends Component implements ItemSelectable {
    boolean selected;
    int i = 0;
    ItemListener itemListener = null;
    ItemEventComponent () {
        enableEvents (AWTEvent.MOUSE_EVENT_MASK);
    }
    public Object[] getSelectedObjects() {
        Object o[] = new Object[1];
        o[0] = new Integer (i);
        return o;
    }
    public void addItemListener (ItemListener l) {
        itemListener = AWTEventMulticaster.add (itemListener, l);
    }
    public void removeItemListener (ItemListener l) {
        itemListener = AWTEventMulticaster.remove (itemListener, l);
    }
    public void processEvent (AWTEvent e) {
        if (e.getID() == MouseEvent.MOUSE_PRESSED) {
            if (itemListener != null) {
                selected = !selected;
                i++;
                itemListener.itemStateChanged (
                    new ItemEvent (this, ItemEvent.ITEM_STATE_CHANGED,
                        getSelectedObjects(),
                        (selected?ItemEvent.SELECTED:ItemEvent.DESELECTED)));
            }
        }
    }
}
public class ItemFrame extends Frame implements ItemListener {
    ItemFrame () {
        super ("Listening In");
        ItemEventComponent c = new ItemEventComponent ();
        add (c, "Center");
        c.addItemListener (this);
        c.setBackground (SystemColor.control);
        setSize (200, 200);
    }
    public void itemStateChanged (ItemEvent e) {
        Object[] o = e.getItemSelectable().getSelectedObjects();
        Integer i = (Integer)o[0];
        System.out.println (i);
    }
    public static void main (String args[]) {
        ItemFrame f = new ItemFrame();
        f.show();
    }
}

The ItemFrame displays just an ItemEventComponent and listens for its item events.

The EventQueue class lets you manage Java 1.1 events directly. You don't usually need to manage events yourself; the system takes care of event delivery behind the scene. However, should you need to, you can acquire the system's event queue by calling Toolkit.getSystemEventQueue(), peek into the event queue by calling peekEvent(), or post new events by calling postEvent(). All of these operations may be restricted by the SecurityManager. You should not remove the events from the queue (i.e., don't call getNextEvent()) unless you really mean to.Constructors

public EventQueue()

This constructor creates an EventQueue for those rare times when you need to manage your own queue of events. More frequently, you just work with the system event queue acquired through the Toolkit.

public synchronized AWTEvent peekEvent()

The peekEvent() method looks into the event queue and returns the first event, without removing that event. If you modify the event, your modifications are reflected in the event still on the queue. The returned object is an instance of AWTEvent. If the queue is empty, peekEvent() returns null.

public synchronized AWTEvent peekEvent(int id)

This peekEvent() method looks into the event queue for the first event of the specified type. id is one of the integer constants from an AWTEvent subclass or an integer constant of your own. If there are no events of the appropriate type on the queue, peekEvent() returns null.

Note that a few of the AWTEvent classes have both event types and subtypes; peekEvent() checks event types only and ignores the subtype. For example, to find an ItemEvent, you would call peekEvent(ITEM_STATE_CHANGED). However, a call to peekEvent(SELECTED) would return null, since SELECTED identifies an ItemEvent subtype.

public synchronized void postEvent(AWTEvent theEvent)

This version of postEvent() puts a new style (  Java1.1) event on the event queue.

public synchronized AWTEvent getNextEvent() throws InterruptedException

The getNextEvent() method removes an event from the queue. If the queue is empty, the call waits. The object returned is the item taken from the queue; it is either an Event or an AWTEvent. If the method call is interrupted, the method getNextEvent() throws an InterruptedException.