 |
Chapter 4 Events |
 |
|
Chapter 4 Events |
|
Now it's time to discuss the new event model that is implemented by the 1.1 release of the JDK. Although this model can seem much more complex (it does have many more pieces), it is really much simpler and more efficient. The new event model does away with the process of searching for components that are interested in an event--deliverEvent(), postEvent(), handleEvent()--and all that. The new model requires objects be registered to receive events. Then, only those objects that are registered are told when the event actually happens.
This new model is called "delegation"; it implements the Observer-Observable design pattern with events. It is important in many respects. In addition to being much more efficient, it allows for a much cleaner separation between GUI components and event handling. It is important that any object, not just a Component, can receive events. Therefore, you can separate your event-handling code from your GUI code. One set of classes can implement the user interface; another set of classes can respond to the events generated by the interface. This means that if you have designed a good interface, you can reuse it in different applications by changing the event processing. The delegation model is essential to JavaBeans, which allows interaction between Java and other platforms, like OpenDoc or ActiveX. To allow such interaction, it was essential to separate the source of an event from the recipient.[1]
[1] For more information about JavaBeans, see http://splash.javasoft.com/beans/.
The delegation model has several other important ramifications. First, event handlers no longer need to worry about whether or not they have completely dealt with an event; they do what they need to, and return. Second, events can be broadcast to multiple recipients; any number of classes can be registered to receive an event. In the old model, broadcasting was possible only in a very limited sense, if at all. An event handler could declare that it hadn't completely processed an event, thus letting its container receive the event when it was done, or an event handler could generate a new event and deliver it to some other component. In any case, developers had to plan how to deliver events to other recipients. In Java 1.1, that's no longer necessary. An event will be delivered to every object that is registered as a listener for that event, regardless of what other objects do with the event. Any listener can mark an event "consumed," so it will be ignored by the peer or (if they care) other listeners.
Finally, the 1.1 event model includes the idea of an event queue. Instead of having to override handleEvent() to see all events, you can peek into the system's event queue by using the EventQueue class. The details of this class are discussed at the end of this chapter.
In Java 1.1, each component is an event source that can generate certain types of events, which are all subclasses of AWTEvent. Objects that are interested in an event are called listeners. Each event type corresponds to a listener interface that specifies the methods that are called when the event occurs. To receive an event, an object must implement the appropriate listener interface and must be registered with the event's source, by a call to an "add listener" method of the component that generates the event. Who calls the "add listener" method can vary; it is probably the best design for the component to register any listeners for the events that it generates, but it is also possible for the event handler to register itself, or for some third object to handle registration (for example, one object could call the constructor for a component, then call the constructor for an event handler, then register the event handler as a listener for the component's events).
This sounds complicated, but it really isn't that bad. It will help to think in concrete terms. A TextField object can generate action events, which in Java 1.1 are of the class ActionEvent. Let's say we have an object of class TextActionHandler that is called myHandler that is interested in receiving action events from a text field named inputBuffer. This means that our object must implement the ActionListener interface, and this in turn, means that it must include an actionPerformed() method, which is called when an action event occurs. Now, we have to register our object's interest in action events generated by inputBuffer; to do so, we need a call to inputBuffer.addActionListener(myHandler). This call would probably be made by the object that is creating the TextField but could also be made by our event handler itself. The code might be as simple as this:
...
public void init(){
...
inputBuffer = new TextField();
myHandler = new TextActionHandler();
inputBuffer.addActionListener(myHandler); // register the handler for the
// buffer's events
add (inputBuffer); // add the input buffer to the display
...
}
Once our object has been registered, myHandler.actionPerformed() will be called whenever a user does anything in the text field that generates an action event, like typing a carriage return. In a way, actionPerformed() is very similar to the action() method of the old event model--except that it is not tied to the Component hierarchy; it is part of an interface that can be implemented by any object that cares about events.
Of course, there are many other kinds of events. Figure 4.4 shows the event hierarchy for Java 1.1. Figure 4.5 shows the different listener interfaces, which are all subinterfaces of EventListener, along with the related adapter classes.
Some of the listener interfaces are constructed to deal with multiple events. For instance, the MouseListener interface declares five methods to handle different kinds of mouse events: mouse down, mouse up, click (both down and up), mouse enter, and mouse exit. Strictly speaking, this means that an object interested in mouse events must implement MouseListener and must therefore implement five methods to deal with all possible mouse actions. This sounds like a waste of the programmer's effort; most of the time, you're only interested in one or two of these events. Why should you have to implement all five methods? Fortunately, you don't. The java.awt.event package also includes a set of adapter classes, which are shorthands that make it easier to write event handlers. The adapter class for any listener interface provides a null implementation of all the methods in that interface. For example, the MouseAdapter class provides stub implementations of the methods mouseEntered(), mouseExited(), mousePressed(), mouseReleased(), and mouseClicked(). If you want to write an event-handling class that deals with mouse clicks only, you can declare that your class extends MouseAdapter. It then inherits all five of these methods, and your only programming task is to override the single method you care about: mouseClicked().
A particularly convenient way to use the adapters is to write an anonymous inner class. For example, the following code deals with the MOUSE_PRESSED event without creating a separate listener class:
![[Graphic: Figure 4-4]](figs/jawt0405.gif)
![[Graphic: Figure 4-5]](figs/jawt0406.gif)
addMouseListener (new MouseAdapter() {
public void mousePressed (MouseEvent e) {
// do what's needed to handle the event
System.out.println ("Clicked at: " + e.getPoint());
}
});
This code creates a MouseAdapter, overrides its mousePressed() method, and registers the resulting unnamed object as a listener for mouse events. Its mousePressed() method is called when MOUSE_PRESSED events occur. You can also use the adapter classes to implement something similar to a callback. For example, you could override mousePressed() to call one of your own methods, which would then be called whenever a MOUSE_PRESSED event occurs.
There are adapter classes for most of the listener interfaces; the only exceptions are the listener interfaces that contain only one method (for example, there's no ActionAdapter to go with ActionListener). When the listener interface contains only one method, an adapter class is superfluous. Event handlers may as well implement the listener interface directly, because they will have to override the only method in the interface; creating a dummy class with the interface method stubbed out doesn't accomplish anything. The different adapter classes are discussed with their related EventListener interfaces.
With all these adapter classes, listener interfaces, and event classes, it's easy to get confused. Here's a quick summary of the different pieces involved and the roles they play:
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.
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.
The id field of AWTEvent is protected and is accessible through the getID() method. It serves as the identifier of the event type, such as the ACTION_PERFORMED type of ActionEvent or the MOUSE_MOVE type of Event. With the delegation event model, it is usually not necessary to look at the event id unless you are looking in the event queue; just register the appropriate event listener.
The constants of AWTEvent are used in conjunction with the internal method Component.eventEnabled(). They are used to help the program determine what style of event handling (true/false--containment or listening--delegation) the program uses and which events a component processes. If you want to process 1.1 events without providing a listener, you need to set the mask for the type of event you want to receive. Look in Chapter 5, Components, for more information on the use of these constants:
public final static long ACTION_EVENT_MASK
public final static long ADJUSTMENT_EVENT_MASK
public final static long COMPONENT_EVENT_MASK
public final static long CONTAINER_EVENT_MASK
public final static long FOCUS_EVENT_MASK
public final static long ITEM_EVENT_MASK
public final static long KEY_EVENT_MASK
public final static long MOUSE_EVENT_MASK
public final static long MOUSE_MOTION_EVENT_MASK
public final static long TEXT_EVENT_MASK
public final static long WINDOW_EVENT_MASK
In addition to the mask constants, the constant RESERVED_ID_MAX is the largest event ID reserved for "official" events. You may use ID numbers greater than this value to create your own events, without risk of conflicting with standard events.
public final static long RESERVED_ID_MAX
Since AWTEvent is an abstract class, you cannot call the constructors directly. They are automatically called when an instance of a child class is created.
The first constructor creates an AWTEvent from the parameters of a 1.0 Event. The event.target and event.id are passed along to the second constructor.
This constructor creates an AWTEvent with the given source; the source is the object generating the event. The id field serves as the identifier of the event type. It is protected and is accessible through the getID() method. With the delegation event model, it is usually not necessary to look at the event id unless you are looking in the event queue or in the processEvent() method of a component; just register the appropriate event listener.
The getID() method returns the id from the constructor, thus identifying the event type.
The consume() method is called to tell an event that it has been handled. An event that has been marked "consumed" is still delivered to the source component's peer and to all other registered listeners. However, the peer will ignore the event; other listeners may also choose to ignore it, but that's up to them. It isn't possible for a listener to "unconsume" an event that has already been marked "consumed."
Noncomponent events cannot be consumed. Only keyboard and mouse event types can be flagged as consumed. Marking an event "consumed" is useful if you are capturing keyboard input and need to reject a character; if you call consume(), the key event never makes it to the peer, and the keystroke isn't displayed. In Java 1.0, you would achieve the same effect by writing an event handler (e.g., keyDown()) that returns true.
You can assume that an event won't be delivered to the peer until all listeners have had a chance to consume it. However, you should not make any other assumptions about the order in which listeners are called.
The isConsumed() method returns whether the event has been consumed. If the event has been consumed, either by default or through consume(), this method returns true; otherwise, it returns false.
When you call the toString() method of an AWTEvent, the paramString() method is called in turn to build the string to display. Since you are most frequently dealing with children of AWTEvent, the children need only to override paramString() to add their specific information.
The toString() method of AWTEvent returns a string with the name of the event, specific information about the event, and the source. In the method MouseAdapter.mouseReleased(), printing the parameter would result in something like the following:
java.awt.event.MouseEvent[MOUSE_RELEASED,(69,107),mods=0,clickCount=1] on panel1
The COMPONENT_FIRST and COMPONENT_LAST constants hold the endpoints of the range of identifiers for ComponentEvent types.
The COMPONENT_HIDDEN constant identifies component events that occur because a component was hidden. The interface method ComponentListener.componentHidden() handles this event.
The COMPONENT_MOVED constant identifies component events that occur because a component has moved. The ComponentListener.componentMoved() interface method handles this event.
The COMPONENT_RESIZED constant identifies component events that occur because a component has changed size. The interface method ComponentListener.componentResized() handles this event.
The COMPONENT_SHOWN constant identifies component events that occur because a component has been shown (i.e., made visible). The interface method ComponentListener.componentShown() handles this event.
This constructor creates a ComponentEvent 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 last four constants above. However, nothing stops you from creating your own id for your event types.
The getComponent() method returns the source of the event--that is, the component initiating the event.
When you call the toString() method of an AWTEvent, the paramString() method is called in turn to build the string to display. At the ComponentEvent level, paramString() adds a string containing the event id (if available) and the bounding rectangle for the source (if appropriate). For example:
java.awt.event.ComponentEvent[COMPONENT_RESIZED (0, 0, 100x100)] on button0
The ContainerEvent class includes events that result from specific container operations. Constants
The CONTAINER_FIRST and CONTAINER_LAST constants hold the endpoints of the range of identifiers for ContainerEvent types.
The COMPONENT_ADDED constant identifies container events that occur because a component has been added to the container. The interface method ContainerListener.componentAdded() handles this event. Listening for this event is useful if a common listener should be attached to all components added to a container.
The COMPONENT_REMOVED constant identifies container events that occur because a component has been removed from the container. The interface method ContainerListener.componentRemoved() handles this event.
The constructor creates a ContainerEvent with the given source (the container generating the event), to which the given child has been added or removed. The id field serves as the identifier of the event type. If system generated, the id will be one of the constants described previously. However, nothing stops you from creating your own id for your event types.
The getContainer() method returns the container that generated the event.
The getComponent() method returns the component that was added to or removed from the container.
When you call the toString() method of an AWTEvent, the paramString() method is in turn called to build the string to display. At the ContainerEvent level, paramString() adds a string containing the event id (if available) along with the name of the child.
The FocusEvent class contains the events that are generated when a component gets or loses focus. These may be either temporary or permanent focus changes. A temporary focus change is the result of something else happening, like a window appearing in front of you. Once the window is removed, focus is restored. A permanent focus change is usually the result of focus traversal, using the keyboard or the mouse: for example, you clicked in a text field to type in it, or used Tab to move to the next component. More programmatically, permanent focus changes are the result of calls to Component.requestFocus(). Constants
The FOCUS_FIRST and FOCUS_LAST constants hold the endpoints of the range of identifiers for FocusEvent types.
The FOCUS_GAINED constant identifies focus events that occur because a component gains input focus. The FocusListener.focusGained() interface method handles this event.
The FOCUS_LOST constant identifies focus events that occur because a component loses input focus. The FocusListener.focusLost() interface method handles this event.
This constructor creates a FocusEvent 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 two constants described previously. However, nothing stops you from creating your own id for your event types. The temporary parameter is true if this event represents a temporary focus change.
This constructor creates a FocusEvent by calling the first constructor with the temporary parameter set to false; that is, it creates an event for a permanent focus change.
The isTemporary() method returns true if the focus event describes a temporary focus change, false if the event describes a permanent focus change. Once set by the constructor, the setting is permanent.
When you call the toString() method of an AWTEvent, the paramString() method is in turn called to build the string to display. At the FocusEvent level, paramString() adds a string showing the event id (if available) and whether or not it is temporary.
The WindowEvent class encapsulates the window-oriented events. Constants
The WINDOW_FIRST and WINDOW_LAST constants hold the endpoints of the range of identifiers for WindowEvent types.
The WINDOW_ICONIFIED constant identifies window events that occur because the user iconifies a window. The WindowListener.windowIconified() interface method handles this event.
The WINDOW_DEICONIFIED constant identifies window events that occur because the user de-iconifies a window. The interface method WindowListener.windowDeiconified() handles this event.
The WINDOW_OPENED constant identifies window events that occur the first time a Frame or Dialog is made visible with show(). The interface method WindowListener.windowOpened() handles this event.
The WINDOW_CLOSING constant identifies window events that occur because the user wants to close a window. This is similar to the familiar event Event.WINDOW_DESTROY dealt with under 1.0 with frames. The WindowListener.windowClosing() interface method handles this event.
The WINDOW_CLOSED constant identifies window events that occur because a Frame or Dialog has finally closed, after hide() or destroy(). This comes after WINDOW_CLOSING, which happens when the user wants the window to close. The WindowListener.windowClosed() interface method handles this event.
NOTE:
If there is a call to System.exit() in the windowClosing() listener, the window will not be around to call windowClosed(), nor will other listeners know.
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.
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.
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.
The getWindow() method returns the Window that generated the event.
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
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
The PAINT_FIRST and PAINT_LAST constants hold the endpoints of the range of identifiers for PaintEvent types.
The PAINT constant identifies paint events that occur because a component needs to be repainted. Override the Component.paint() method to handle this event.
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.
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.
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.
The setUpdateRect() method changes the area of the PaintEvent's source component that needs repainting.
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
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.
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.
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.
The isAltDown() method checks to see if ALT_MASK is set. If so, isAltDown() returns true; otherwise, it returns false.
The isControlDown() method checks to see if CONTROL_MASK is set. If so, isControlDown() returns true; otherwise, it returns false.
The isMetaDown() method checks to see if META_MASK is set. If so, the method isMetaDown() returns true; otherwise, it returns false.
The isShiftDown() method checks to see if SHIFT_MASK is set. If so, the method isShiftDown() returns true; otherwise, it returns false.
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");
}
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());
This class overrides the AWTEvent.consume() method to make it public. Anyone, not just a subclass, can mark an InputEvent as consumed.
This class overrides the AWTEvent.isconsumed() method to make it public. Anyone can find out if an InputEvent has been consumed.
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.
| VK_ENTER | VK_0 | VK_A | VK_F1 | VK_ACCEPT |
| VK_BACK_SPACE | VK_1 | VK_B | VK_F2 | VK_CONVERT |
| VK_TAB | VK_2 | VK_C | VK_F3 | VK_FINAL |
| VK_CANCEL | VK_3 | VK_D | VK_F4 | VK_KANA |
| VK_CLEAR | VK_4 | VK_E | VK_F5 | VK_KANJI |
| VK_SHIFT | VK_5 | VK_F | VK_F6 | VK_MODECHANGE |
| VK_CONTROL | VK_6 | VK_G | VK_F7 | VK_NONCONVERT |
| VK_ALT | VK_7 | VK_H | VK_F8 | |
| VK_PAUSE | VK_8 | VK_I | VK_F9 | |
| VK_CAPS_LOCK | VK_9 | VK_J | VK_F10 | |
| VK_ESCAPE | VK_NUMPAD0 | VK_K | VK_F11 | |
| VK_SPACE | VK_NUMPAD1 | VK_L | VK_F12 | |
| VK_PAGE_UP | VK_NUMPAD2 | VK_M | VK_DELETE | |
| VK_PAGE_DOWN | VK_NUMPAD3 | VK_N | VK_NUM_LOCK | |
| VK_END | VK_NUMPAD4 | VK_O | VK_SCROLL_LOCK | |
| VK_HOME | VK_NUMPAD5 | VK_P | VK_PRINTSCREEN | |
| VK_LEFT | VK_NUMPAD6 | VK_Q | VK_INSERT | |
| VK_UP | VK_NUMPAD7 | VK_R | VK_HELP | |
| VK_RIGHT | VK_NUMPAD8 | VK_S | VK_META | |
| VK_DOWN | VK_NUMPAD9 | VK_T | VK_BACK_QUOTE | |
| VK_COMMA | VK_MULTIPLY | VK_U | VK_QUOTE | |
| VK_PERIOD | VK_ADD | VK_V | VK_OPEN_BRACKET | |
| VK_SLASH | VK_SEPARATER[1] | VK_W | VK_CLOSE_BRACKET | |
| VK_SEMICOLON | VK_SUBTRACT | VK_X | ||
| VK_EQUALS | VK_DECIMAL | VK_Y | ||
| VK_BACK_SLASH | VK_DIVIDE | VK_Z | ||
|
Footnotes:
| ||||
When a KEY_TYPED event happens, there is no keycode. If you ask for it, the getKeyCode() method returns VK_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.
The KEY_FIRST and KEY_LAST constants hold the endpoints of the range of identifiers for KeyEvent types.
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.
The KEY_RELEASED constant identifies key events that occur because a keyboard key has been released. The KeyListener.keyReleased() interface method handles this event.
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.
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.
The getKeyChar() method retrieves the Unicode character associated with the key in this KeyEvent. If there is no character, CHAR_UNDEFINED is returned.
The setKeyChar() method allows you to change the character for the KeyEvent. You could use this method to convert characters to uppercase.
The getKeyCode() method retrieves the virtual keycode (i.e., one of the constants in Table 4.4) of this KeyEvent.
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.
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.
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.
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.
| Property | Default | Property | Default |
|---|---|---|---|
| AWT.accept | Accept | AWT.f8 | F8 |
| AWT.add | NumPad + | AWT.f9 | F9 |
| AWT.alt | Alt | AWT.help | Help |
| AWT.backQuote | Back Quote | AWT.home | Home |
| AWT.backSpace | Backspace | AWT.insert | Insert |
| AWT.cancel | Cancel | AWT.kana | Kana |
| AWT.capsLock | Caps Lock | AWT.kanji | Kanji |
| AWT.clear | Clear | AWT.left | Left |
| AWT.control | Control | AWT.meta | Meta |
| AWT.decimal | NumPad . | AWT.modechange | Mode Change |
| AWT.delete | Delete | AWT.multiply | NumPad * |
| AWT.divide | NumPad / | AWT.noconvert | No Convert |
| AWT.down | Down | AWT.numLock | Num Lock |
| AWT.end | End | AWT.numpad | NumPad |
| AWT.enter | Enter | AWT.pause | Pause |
| AWT.escape | Escape | AWT.pgdn | Page Down |
| AWT.final | Final | AWT.pgup | Page Up |
| AWT.f1 | F1 | AWT.printScreen | Print Screen |
| AWT.f10 | F10 | AWT.quote | Quote |
| AWT.f11 | F11 | AWT.right | Right |
| AWT.f12 | F12 | AWT.scrollLock | Scroll Lock |
| AWT.f2 | F2 | AWT.separator | NumPad , |
| AWT.f3 | F3 | AWT.shift | Shift |
| AWT.f4 | F4 | AWT.space | Space |
| AWT.f5 | F5 | AWT.subtract | NumPad - |
| AWT.f6 | F6 | AWT.tab | Tab |
| AWT.f7 | F7 | AWT.unknown | Unknown keyCode |
| AWT.up | Up |
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.
| Property | Default |
|---|---|
| AWT.alt | Alt |
| AWT.control | Ctrl |
| AWT.meta | Meta |
| AWT.shift | Shift |
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
The MouseEvent class is a subclass of InputEvent for dealing with mouse events. Constants
The MOUSE_FIRST and MOUSE_LAST constants hold the endpoints of the range of identifiers for MouseEvent types.
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.
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.
The MOUSE_ENTERED constant identifies mouse events that occur when the mouse first enters a component. The MouseListener.mouseEntered() interface method handles this event.
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.
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.
The MOUSE_PRESSED constant identifies mouse events that occur because a mouse button has been pressed. The MouseListener.mousePressed() interface method handles this event.
The MOUSE_RELEASED constant identifies mouse events that occur because a mouse button has been released. The MouseListener.mouseReleased() interface method handles this event.
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?)
The getX() method returns the current x coordinate of the event relative to the source.
The getY() method returns the current y coordinate of the event relative to the source.
The getPoint() method returns the current x and y coordinates of the event relative to the event source.
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.
The getClickCount() method retrieves the current clickCount setting for the event.
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);
}
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
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
The ACTION_FIRST and ACTION_LAST constants hold the endpoints of the range of identifiers for ActionEvent types.
The ACTION_PERFORMED constant represents when a user activates a component. The ActionListener.actionPerformed() interface method handles this event.
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().
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.
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.
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.
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.
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
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
The ADJUSTMENT_FIRST and ADJUSTMENT_LAST constants hold the endpoints of the range of identifiers for AdjustmentEvent types.
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.
UNIT_DECREMENT identifies adjustment events that occur because the user selects the increment arrow.
UNIT_INCREMENT identifies adjustment events that occur because the user selects the decrement arrow.
BLOCK_DECREMENT identifies adjustment events that occur because the user selects the block decrement area, between the decrement arrow and the slider.
BLOCK_INCREMENT identifies adjustment events that occur because the user selects the block increment area, between the increment arrow and the slider.
TRACK identifies adjustment events that occur because the user selects the slider and drags it. Multiple adjustment events of this subtype usually occur consecutively.
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.
The getAdjustable() method retrieves the Adjustable object associated with this event--that is, the event's source.
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.
The getValue() method retrieves the value parameter from the constructor. It represents the current setting of the adjustable object.
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
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
The ITEM_FIRST and ITEM_LAST constants hold the endpoints of the range of identifiers for ItemEvent types.
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.
SELECTED indicates that the user selected the item.
DESELECTED indicates that the user deselected the item.
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.
The getItemSelectable() method retrieves the ItemSelectable object associated with this event--that is, the event's source.
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.
The getStateChange() method returns the stateChange parameter from the constructor and, if system generated, is either SELECTED or DESELECTED.
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
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
The TEXT_FIRST and TEXT_LAST constants hold the endpoints of the range of identifiers for TextEvent types.
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.
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.
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).
Java 1.1 has 11 event listener interfaces, which specify the methods a class must implement to receive different kinds of events. For example, the ActionListener interface defines the single method that is called when an ActionEvent occurs. These interfaces replace the various event-handling methods of Java 1.0: action() is now the actionPerformed() method of the ActionListener interface, mouseUp() is now the mouseReleased() method of the MouseListener interface, and so on. Most of the listener interfaces have a corresponding adapter class, which is an abstract class that provides a null implementation of all the methods in the interface. (Although an adapter class has no abstract methods, it is declared abstract to remind you that it must be subclassed.) Rather than implementing a listener interface directly, you have the option of extending an adapter class and overriding only the methods you care about. (Much more complex adapters are possible, but the adapters supplied with AWT are very simple.) The adapters are available for the listener interfaces with multiple methods. (If there is only one method in the listener interface, there is no need for an adapter.)
This section describes Java 1.1's listener interfaces and adapter classes. It's worth noting here that Java 1.1 does not allow you to modify the original event when you're writing an event handler.
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.
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.
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.
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.
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.
The componentResized() method is called when a component is resized (for example, by a call to Component.setSize()).
The componentMoved() method is called when a component is moved (for example, by a call to Component.setLocation()).
The componentShown() method is called when a component is shown (for example, by a call to Component.show()).
The componentHidden() method is called when a component is hidden (for example, by a call to Component.hide()).
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.
The componentAdded() method is called when a component is added to a container (for example, by a call to Container.add()).
The componentRemoved() method is called when a component is removed from a container (for example, by a call to Container.remove()).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
The mouseClicked() method is called once each time the user clicks a mouse button; that is, once for each mouse press/mouse release combination.
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.
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.
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.
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.
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).
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.
The windowOpened() method is called when a Window is first opened.
The windowClosing() method is triggered whenever the user tries to close the Window.
The windowClosed() method is called after the Window has been closed.
The windowIconified() method is called whenever a user iconifies a Window.
The windowDeiconified() method is called when the user deiconifies the Window.
The windowActivated() method is called whenever a Window is brought to the front.
The windowDeactivated() method is called when the Window is sent away from the front, either through iconification, closing, or another window becoming active.
The AWTEventMulticaster class is used by AWT to manage the listener queues for the different events, and for sending events to all interested listeners when they occur (multicasting). Ordinarily, you have no need to work with this class or know about its existence. However, if you wish to create your own components that have their own set of listeners, you can use the class instead of implementing your own event-delivery system. See "Constructor methods" in this section for more on how to use the AWTEventMulticaster.
AWTEventMulticaster looks like a strange beast, and to some extent, it is. It contains methods to add and remove every possible kind of listener and implements all of the listener interfaces (11 as of Java 1.1). Because it implements all the listener interfaces, you can pass an event multicaster as an argument wherever you expect any kind of listener. However, unlike a class you might implement to listen for a specific kind of event, the multicaster includes machinery for maintaining chains of listeners. This explains the rather odd signatures for the add() and remove() methods. Let's look at one in particular:
public static ActionListener add(ActionListener first, ActionListener second)
This method takes two ActionListeners and returns another ActionListener. The returned listener is actually an event multicaster that contains the two listeners given as arguments in a linked list. However, because it implements the ActionListener interface, it is just as much an ActionListener as any class you might write; the fact that it contains two (or more) listeners inside it is irrelevant. Furthermore, both arguments can also be event multicasters, containing arbitrarily long chains of action listeners; in this case, the returned listener combines the two chains. Most often, you will use add to add a single listener to a chain that you're building, like this:
actionListenerChain=AWTEventMulticaster.add(actionListenerChain,
newActionListener);
actionListenerChain is an ActionListener--but it is also a multicaster holding a chain of action listeners. To start a chain, use null for the first argument. You rarely need to call the AWTEventMulticaster constructor. add() is a static method, so you can use it with either argument set to null to start the chain.
Now that you can maintain chains of listeners, how do you use them? Simple; just deliver your event to the appropriate method in the chain. The multicaster takes care of sending the event to all the listeners it contains:
actionListenerChain.actionPerformed(new ActionEvent(...));
The a and b event listeners each consist of a chain of EventListeners.
The constructor is protected. It creates an AWTEventMulticaster instance from the two chains of listeners. An instance is automatically created for you when you add your second listener by calling an add() method.
These methods implement all of the listener interfaces. Rather than repeating all the descriptions, the methods are just listed.
These methods broadcast the event given as an argument to all the listeners.
There is an add() method for every listener interface. Again, I've listed them with a single description.
These methods combine the listener sets together; they are called by the "add listener" methods of the various components. Usually, the first parameter is the initial listener chain, and the second parameter is the listener to add. However, nothing forces that. The combined set of listeners is returned.
The addInternal() method is a support routine for the various add() methods. The combined set of listeners is returned.
Again, there are remove() methods for every listener type, and I've economized on the descriptions.
These methods remove oldListener from the list of listeners, list. They are called by the "remove listener" methods of the different components. If oldListener is not found in the list, nothing happens. All these methods return the new list of listeners.
The removeInternal() method is a support routine for the various remove() methods. It removes oldListener from the list of listeners, list. Nothing happens if oldListener is not found in the list. The new set of listeners is returned.
This remove() method removes oldListener from the AWTEventMulticaster. It is a support routine for removeInternal().
The saveInternal() method is a support method for serialization.
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
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.
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.
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.
This version of postEvent() puts a new style ( Java1.1) event on the event queue.
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.
|
 |
|
| The Event Class |  |
Components |
| This HTML Help has been published using the chm2web software. |