Up until now, your applets have responded to events generated by Java components like buttons, text fields, and list boxes. You've yet to examine how to respond to events generated by the most basic of a computer's controls, the mouse and the keyboard. Because virtually every computer has these important hardware controls, you can confidently take advantage of them in your applets to collect various types of input. In this chapter, you learn the secrets of mouse and keyboard handling in Java applets.
In order to understand how to respond to various types of events, you need to know more about Java's Event class, an object of which is passed to any event-handling method. When you want to respond to a Java button control, for example, you override the action() method, whose first argument is an Event object. You then examine the target field of the Event object to determine whether it was the button control that generated the event. The Event class, however, defines many constants and data fields that provide information about the event represented by the object.
First, the Event class defines constants for all of the
events to which an event-handling method can respond. In this
chapter, you'll learn about some of these constants, which include
MOUSE_DOWN, MOUSE_UP, and KEY_PRESS.
The class also defines constants for special keys, such as f1,
PGUP, PGDN, HOME, and so on. Finally,
the Event class defines the data fields shown in Table
25.1. How you use these data fields depends on the type of event
represented by the Event object.
| Field | Description |
| Object arg | Event-specific information. With a button event, for example, this field is the button's label. |
| int clickCount | The click count for mouse events. A value of 1 means a single click, and 2 means a double-click. |
| int id | The event's type, such as MOUSE_DOWN, MOUSE_MOVE, KEY_PRESS, etc. |
| int key | The key for a key-related event. For a KEY_PRESS event, for example, this would be the key that was pressed. |
| int modifiers | The key modifiers, including the shift and control keys. The Event class defines constants such as SHIFT_MASK and CTRL_MASK. |
| Object target | The type of object-such as Button, TextField, and so on-that generated the event. |
| long when | The event's time stamp. |
| int x | The X coordinate associated with the event, usually used with mouse events to indicate the mouse's position at the time of the event. |
| int y | The Y coordinate associated with the event, usually used with mouse events to indicate the mouse's position at the time of the event. |
Most people use their computer's mouse darn near as much as its keyboard. I can vouch for this from first-hand experience, because my only bout with RSI (repetitive strain injury) came not from typing furiously all day, but from maneuvering my mouse to mark paragraphs, highlight words, click buttons, make list selections, bring up menus, and any number of other mousely tasks. I'm not looking for your sympathy, though. My point is that the mouse is one of the most important input devices attached to your computer. To write complete applets, you're going to have to master responding to mouse events in your Java programs.
Luckily, responding to mouse input is a simple matter. Because responding to the events generated by the mouse are such an important and common task in modern programming, Java's classes already include special methods for responding to these events. Exactly what events are you expected to handle? A mouse generates six types of event messages that you can capture in your applets. These events are listed below, along with their descriptions and the method that handles them:
In the sections that follow, you'll learn more about the most commonly used of these mouse events.
Without a doubt, the most commonly used mouse event in Java programs (and any other program written for a graphical user interface) is the MOUSE_DOWN event, which is generated whenever the user clicks within an applet. It's the MOUSE_DOWN event, for example, that lets Java know when an on-screen button component has been clicked. You don't have to worry about clicks on on-screen buttons (usually), because they're handled by Java. However, you can respond to MOUSE_DOWN events in your applets in order to accomplish other input tasks.
Java provides a couple of methods by which you can respond to mouse events. The easiest way to capture a MOUSE_DOWN event is to override the applet's mouseDown() method. Java automatically calls mouseDown() whenever the MOUSE_DOWN event is generated, which makes responding to this event easier than melting butter with a blowtorch. The mouseDown() method's signature looks like this:
public boolean mouseDown(Event evt, int x, int y)
The arguments passed to the function are an Event object and the X,Y coordinates of the mouse event. Although Java has already extracted the X,Y mouse coordinates for you, you can also get them from the Event object by examining the values stored in the x and y data fields, as described in Table 25.1. (Because Java has already extracted the coordinates for you, though, it makes more sense to use the x and y parameters sent to the function.) What you do with these coordinates depends, of course, on your applet. In the next section, you'll see how to use the coordinates to display graphics on the screen.
| NOTE |
Although most of Java's event-handling methods automatically receive as arguments the basic information you need about a specific event (such as the coordinates of a mouse click), you can extract whatever additional information you need from the Event object, which is always the first parameter in a message-handling method. |
As I was describing the mouseDown() method in the previous section, I felt an example coming on. And, sure enough, here it is. The applet in Listing 25.1 responds to mouse clicks by printing the word "Click!" wherever the user clicks in the applet. It does this by storing the coordinates of the mouse click in the applet's coordX and coordY data fields. The paint() method then uses these coordinates to display the word. Figure 25.1 shows MouseApplet running under Appletviewer.
Figure 25.1 : The MouseApplet applet responds to mouse clicks.
Listing 25.1 MouseApplet.java: Using Mouse Clicks in an Applet.
import java.awt.*;
import java.applet.*;
public class MouseApplet extends Applet
{
int coordX, coordY;
public void init()
{
coordX = -1;
coordY = -1;
Font font =
new Font("TimesRoman", Font.BOLD, 24);
setFont(font);
resize(400, 300);
}
public void paint(Graphics g)
{
if (coordX != -1)
g.drawString("Click!", coordX, coordY);
}
public boolean mouseDown(Event evt, int x, int y)
{
coordX = x;
coordY = y;
repaint();
return true;
}
}
Tell Java that the applet uses the classes in the awt package.
Tell Java that the applet uses the classes in the applet package.
Derive the MouseApplet class from Java's Applet class.
Declare the class's data fields.
Override the init() method.
Initialize the click coordinates.
Create and set the font for the applet.
Size the applet.
Override the paint() method.
If the user has selected a coordinate...
Draw the word Click! at the selected coordinate.
Override the mouseDown() method.
Save the mouse click's coordinates.
Force Java to repaint the applet.
Tell Java that the event was handled.
| NOTE |
When you run MouseApplet, you'll discover that the applet window gets erased each time the paint() method is called. That's why only one "Click!" ever appears in the window. |
Although mouse clicks are the most common type of mouse event to which your applet may want to respond, tracking the mouse pointer's movement can also be useful. Drawing programs, for example, enable you to draw shapes by tracking the movement of the mouse and displaying the results on the screen.
Unlike mouse clicks, though, which are rare, only occurring when the user presses a mouse button, MOUSE_MOVE events come flooding into your applet by the hundreds as the user moves the mouse around the screen. Each one of these events can be handled in the mouseMove() method, whose signature looks like this:
public boolean mouseMove(Event evt, int x, int y)
Yep. Except for its name, the mouseMove() method looks exactly like the mouseDown() method, receiving as arguments an Event object and the X,Y coordinates at which the event occurred.
Responding to mouse movement isn't something you have to do often in your applets. Still, it's a handy tool to have on your belt. You might, for example, need to track mouse movement when writing a game applet that uses the mouse as input. A more common use is in graphics programs that enable you to draw on the screen. Listing 25.2 is just such an applet.
When you run MouseApplet2 with Appletviewer, you see a blank window. Click the mouse in the window to choose a starting point and then move the mouse around the window. Wherever the mouse pointer goes, it leaves a black line behind (Figure 25.2). Although this is a very simple drawing program, it gives you some idea of how you might use a mouse to accomplish other similar tasks.
Figure 25.2 : This applet draws by tracking the movement of the mouse.
Listing 25.2 MouseApplet2.java: An Applet That Tracks Mouse Movement.
import java.awt.*;
import java.applet.*;
public class MouseApplet2 extends Applet
{
Point startPoint;
Point points[];
int numPoints;
boolean drawing;
public void init()
{
startPoint = new Point(0, 0);
points = new Point[1000];
numPoints = 0;
drawing = false;
resize(400, 300);
}
public void paint(Graphics g)
{
int oldX = startPoint.x;
int oldY = startPoint.y;
for (int x=0; x<numPoints; ++x)
{
g.drawLine(oldX, oldY, points[x].x, points[x].y);
oldX = points[x].x;
oldY = points[x].y;
}
}
public boolean mouseDown(Event evt, int x, int y)
{
drawing = true;
startPoint.x = x;
startPoint.y = y;
return true;
}
public boolean mouseMove(Event evt, int x, int y)
{
if ((drawing) && (numPoints < 1000))
{
points[numPoints] = new Point(x, y);
++numPoints;
repaint();
}
return true;
}
}
Tell Java that the applet uses the classes in the awt package.
Tell Java that the applet uses the classes in the applet package.
Derive the MouseApplet2 class from Java's Applet class.
Declare the class's data fields.
Override the init() method.
Initialize the starting point.
Create an array for storing the coordinates of line segments.
Create and set the font for the applet.
Set point count to zero.
Set drawing flag off.
Size the applet.
Override the paint() method.
Initialize the drawing's starting point.
Cycle through each element in the points[] array.
Draw a line segment.
Save ending point as the starting point for the next line.
Override the mouseDown() method.
Set the flag in order to allow drawing to begin.
Save the mouse click's coordinates.
Tell Java that the event was handled.
Override the mouseMove() method.
if it's okay to add another line segment...
Create a new point and save the mouse's coordinates.
Increment the point counter.
Force Java to repaint the applet.
Tell Java that the event was handled.
The keyboard has been around even longer than the mouse and has been the primary interface between humans and their computers for decades. Given the keyboard's importance, obviously there may be times when you'll want to handle the keyboard events at a lower level than you can with something like a TextField control. Java responds to two basic key events, which are represented by the KEY_PRESS and KEY_RELEASE constants. As you'll soon see, Java defines methods that make it just as easy to respond to the keyboard as it is to respond to the mouse.
Whenever the user presses a key when an applet is active, Java sends the applet a KEY_PRESS event. In your applet, you can respond to this event by overriding the keyDown() method, whose signature looks like this:
public boolean keyDown(Event evt, int key)
As you can see, this method receives two arguments, which are an Event object and an integer representing the key that was pressed. This integer is actually the ASCII representation of the character represented by the key. In order to use this value in your programs, however, you must first cast it to a char value, like this:
char c = (char)key;
Some of the keys on your keyboard issue commands rather than generate
characters. These keys include all the F keys, as well as keys
like Shift, Ctrl, Page Up, Page Down, and so on. In order to make
these types of keys easier to handle in your applets, Java's Event
class defines a set of constants that represent these key's values.
Table 25.2 lists these constants.
| Constant | Key |
| DOWN | The down arrow key. |
| END | The End key. |
| f1 | The f1 key. |
| f2 | The f2 key. |
| f3 | The f3 key. |
| f4 | The f4 key. |
| f5 | The f5 key. |
| f6 | The f6 key. |
| f7 | The f7 key. |
| f8 | The f8 key. |
| f9 | The f9 key. |
| f10 | The f10 key. |
| f11 | The f11 key. |
| f12 | The f12 key. |
| HOME | The Home key. |
| LEFT | The left arrow key. |
| PGDN | The Page Down key. |
| PGUP | The Page Up key. |
| RIGHT | The right arrow key. |
| UP | The up arrow key. |
The Event class also defines a number of constants for modifier keys that the user might press along with the basic key. These constants include ALT_MASK, SHIFT_MASK, and CTRL_MASK, which represent the Alt, Shift, and Ctrl (or Control) keys on your keyboard. The SHIFT_MASK and CTRL_MASK constants are used in the Event class's methods shiftDown() and controlDown(), each which of returns a boolean value indicating whether the modifier key is pressed. (There currently is no altDown() method.) You can also examine the Event object's modifiers field to determine whether a particular modifier key was pressed. For example, if you wanted to check for the Alt key, you might use a line of Java code like this:
boolean altPressed = (evt.modifiers & Event.ALT_MASK) != 0;
By ANDing the mask with the value in the modifiers field, you end up with a non-zero value if the Alt key was pressed and a 0 if it wasn't. You convert this result to a boolean value by comparing the result with 0.
Although capturing key presses is a fairly simple process, there's nothing like an example applet to put the theoretical stuff to the test. Listing 25.3 is an applet called KeyApplet that displays whatever key the user presses. Figure 25.3 shows the applet running under Appletviewer.
Figure 25.3 : This applet displays the last character typed.
| NOTE |
If you run KeyApplet under a browser like Netscape Navigator, click on the applet with your mouse before you start typing. This ensures that the applet has the focus and will receive the key presses. |
Listing 25.3 KeyApplet.java: An Applet That Captures Key Presses.
import java.awt.*;
import java.applet.*;
public class KeyApplet extends Applet
{
int keyPressed;
public void init()
{
keyPressed = -1;
Font font =
new Font("TimesRoman", Font.BOLD, 144);
setFont(font);
resize(200, 200);
}
public void paint(Graphics g)
{
String str = "";
if (keyPressed != -1)
{
str += (char)keyPressed;
g.drawString(str, 40, 150);
}
}
public boolean keyDown(Event evt, int key)
{
keyPressed = key;
repaint();
return true;
}
}
Tell Java that the applet uses the classes in the awt package.
Tell Java that the applet uses the classes in the applet package.
Derive the KeyApplet class from Java's Applet class.
Declare the class's data field.
Override the init() method.
Initialize keyPressed to indicate no valid key received yet.
Create and set the font for the applet.
Size the applet.
Override the paint() method.
Create the empty display string.
Draw the character on the screen.
Override the keyDown() method.
Save the key that was pressed.
Force Java to redraw the applet.
Tell Java that the event was handled.
All of the events received by your applet are processed by the handleEvent() method, which the Applet class inherits from the Component class. When this method is not overridden in your applet, the default implementation is responsible for calling the many methods that respond to events. Listing 25.4 shows how the handleEvent() method is implemented in the Component class. By examining this listing, you can easily see why you only have to override methods like mouseDown() to respond to events. In the next section, you see how to customize handleEvent() in your own programs.
Listing 25.4 LST25_4.TXT: The Default Implementation of handleEvent( ).
public boolean handleEvent(Event evt) {
switch (evt.id) {
case Event.MOUSE_ENTER:
return mouseEnter(evt, evt.x, evt.y);
case Event.MOUSE_EXIT:
return mouseExit(evt, evt.x, evt.y);
case Event.MOUSE_MOVE:
return mouseMove(evt, evt.x, evt.y);
case Event.MOUSE_DOWN:
return mouseDown(evt, evt.x, evt.y);
case Event.MOUSE_DRAG:
return mouseDrag(evt, evt.x, evt.y);
case Event.MOUSE_UP:
return mouseUp(evt, evt.x, evt.y);
case Event.KEY_PRESS:
case Event.KEY_ACTION:
return keyDown(evt, evt.key);
case Event.KEY_RELEASE:
case Event.KEY_ACTION_RELEASE:
return keyUp(evt, evt.key);
case Event.ACTION_EVENT:
return action(evt, evt.arg);
case Event.GOT_FOCUS:
return gotFocus(evt, evt.arg);
case Event.LOST_FOCUS:
return lostFocus(evt, evt.arg);
}
return false;
}
Although the default implementation of handleEvent() calls special methods that you can override in your applet for each event, you might want to group all your event handling in one method to conserve on overhead, change the way an applet responds to a particular event, or even create your own events. To accomplish any of these tasks (or any others you might come up with), you can forget the individual event-handling methods and override handleEvent() instead.
In your version of handleEvent(), you must examine the Event object's id field in order to determine which event is being processed. You can just ignore events in which you're not interested. However, be sure to return false whenever you ignore a message, so that Java knows that it should pass the event on up the object hierarchy. Listing 25.5 is a rewritten version of the MouseApplet2 applet, called MouseApplet3. This version overrides the handleEvent() method in order to respond to events.
Listing 25.5 MouseApplet3.java: Using the handleEvent( ) Method.
import java.awt.*;
import java.applet.*;
public class MouseApplet3 extends Applet
{
Point startPoint;
Point points[];
int numPoints;
boolean drawing;
public void init()
{
startPoint = new Point(0, 0);
points = new Point[1000];
numPoints = 0;
drawing = false;
resize(400, 300);
}
public void paint(Graphics g)
{
int oldX = startPoint.x;
int oldY = startPoint.y;
for (int x=0; x<numPoints; ++x)
{
g.drawLine(oldX, oldY, points[x].x, points[x].y);
oldX = points[x].x;
oldY = points[x].y;
}
}
public boolean handleEvent(Event evt)
{
switch(evt.id)
{
case Event.MOUSE_DOWN:
drawing = true;
startPoint.x = evt.x;
startPoint.y = evt.y;
return true;
case Event.MOUSE_MOVE:
if ((drawing) && (numPoints < 1000))
{
points[numPoints] = new Point(evt.x, evt.y);
++numPoints;
repaint();
}
return true;
default:
return false;
}
}
}
Because the keyboard and the mouse are two of the most important devices for accepting input from the user, it's important that you know how to handle these devices in your applets. Maybe most of your applets will work fine by leaving such details up to Java or maybe you'll want to have more control over the devices than the default behavior allows. You can capture most messages received by a Java applet by overloading the appropriate event handlers, such as mouseDown() and keyDown(). However, if you want to step back even further in your event-handling code, you can override the handleEvent() method, which receives all events sent to an applet.
