Keyboard events are events generated by a key press on the keyboard. Any time the user presses a key, a keyboard event is generated that can be trapped and handled by the applet with the input focus. Actually, a key press generates two events: a key down event and a key up event. You'll learn more about these two types soon.

Mouse events are generated by mouse clicks and movements. Every mouse click and mouse movement generates a corresponding mouse input event. Like key presses, mouse clicks actually come as a series of events: a mouse click down event and a mouse click up event. A mouse event is also specifically targeted at mouse dragging. Mouse dragging occurs when the mouse is moved with the button down. Applets that want to respond to mouse clicks and movement simply have to process these events and take action accordingly. You learn more about processing mouse events a little later in this lesson.

awt Event Handling

Before getting into the specific event handlers for keyboard and mouse events, let's look at how events are handled in a general sense in Java. The Java awt provides the Event class for encapsulating all types of events that can occur within the system. The Event class models a generic event and has constants defined within it to represent specific events. The Event class is used primarily by the handleEvent method of Component. The handleEvent method is the default event handler for all events, and is defined as follows:

public boolean handleEvent(Event evt)

Notice that handleEvent takes an Event object as its only parameter. handleEvent uses this Event object to determine what type of event has occurred. It then calls a more specific event handler method to deal with the specific event. For example, if a key is pressed, the Event object's id member variable is set to KEY_PRESS, which is a constant defining the key press event. handleEvent checks the value of id and, upon finding it equal to KEY_PRESS, calls the keyDown handler method. Listing 9.1 shows the key press handling portion of the handleEvent method in the 1.0 release of Java.

Listing 9.1. The key press portion of the handleEvent method.

public boolean handleEvent(Event evt) {
  switch (evt.id) {
    ...
  case Event.KEY_PRESS:
    return keyDown(evt, evt.key);
    ...
  }
  return false;
}

The handling of other system events is very similar to that of the KEY_PRESS event. You could easily override handleEvent to provide custom routing of event handlers, but it is rarely necessary. Although you might not ever need to intervene with the default event handling provided by handleEvent, it is nevertheless important to understand how it works.

Keyboard Events

Java keyboard events are generated when the user presses or releases a key. Two standard keyboard event handler methods are supported by the Component class: keyDown and keyUp. These two methods are defined as follows:

public boolean keyDown(Event evt, int key)
public boolean keyUp(Event evt, int key)

The keyDown method is called in response to the user pressing a key, and the keyUp method is called in response to the user releasing a key. Both methods are passed an Event object and an integer key value parameter. The key value parameter, key, specifies which key was pressed or released. The Event object parameter contains extra information relating to the keyboard event, such as whether the Shift key was held down when the key was pressed.

The Event object contains constants representing the different keys that can be specified in the key parameter. Table 9.1 shows a list of the more useful key constants.

Table 9.1. Useful key constants for games.

To check whether the key pressed or released is one of these keys, you override keyDown or keyUp and compare the value of key to one of the constants. Listing 9.2 contains an example of overriding keyDown to check for the user pressing one of the arrow keys.

Listing 9.2. Handling arrow key presses in the keyDown method.

public boolean keyDown(Event evt, int key) {
  switch (key) {
  case Event.LEFT:
    // left arrow key pressed
    break;
  case Event.RIGHT:
    // right arrow key pressed
    break;
  case Event.UP:
    // up arrow key pressed
    break;
  case Event.DOWN:
    // down arrow key pressed
    break;
  }
  return true;
}

This keyDown method shows that handling different key presses is as easy as providing a switch statement with case clauses for each key. Although the example here used the keyDown method for handling key presses, the keyUp method works in the same fashion.

If you need more details about the key that was pressed or released, you can use the Event object passed into the keyDown and keyUp methods. The typical usage of the Event object in regard to key processing is to check for modifier keys. Modifier keys are keys that can be pressed in conjunction with other input events, such as the Shift and Control keys. The following are the three methods in Event used to check the status of modifier keys:

public boolean shiftDown()
public boolean controlDown()
public boolean metaDown()

All of these methods return boolean values specifying whether or not the key in question is being held down. Checking the status of the modifier keys is necessary sometimes in applets that make heavy use of the mouse. For example, you might have a drawing applet that performs a different function if the Shift key is held down and the mouse is moved. You probably won't need the modifier keys in Java games, but it is still important to know how they work. Who knows, you might think of an interesting way to incorporate them into a game.

Mouse Events

Mouse events occur when the user moves the mouse or clicks the mouse button. A handful of methods exist for handling mouse events, such as the following methods:

public boolean mouseUp(Event evt, int x, int y)
public boolean mouseDown(Event evt, int x, int y)
public boolean mouseMove(Event evt, int x, int y)
public boolean mouseDrag(Event evt, int x, int y)
public boolean mouseEnter(Event evt, int x, int y)
public boolean mouseExit(Event evt, int x, int y)

All of these methods are passed an Event object and two integer parameters representing the X and Y position of the mouse pointer. The mouseUp and mouseDown methods are called when the user presses and releases the mouse button. The mouseMove method is called when the mouse is moved. The mouseDrag method is very similar to the mouseMove method-the only difference being that mouseDrag is called when the mouse is moved with the button held down. The mouseEnter and mouseExit methods are used to track when the mouse enters and exits the applet window.

You can use the x and y parameters passed into the mouse event handler methods to perform any processing based on the position of the mouse. The following code snippet contains an example of overriding the mouseMove method to output the mouse position to standard output:

public boolean mouseMove(Event evt, int x, int y) {
  System.out.println("Mouse position = (" + x + ", " + y + ")");
  return true;
}

Similar to the keyboard event handlers, you can use the Event object passed in the mouse event handlers to find out additional information such as the status of modifier keys.

Sample Applet: Flying Saucer

Now that you have a good idea of how to process user input events in Java, let's take a look at a sample applet that uses this newfound knowledge. The Flying Saucer applet uses the sprite classes and event handler methods to implement a user-controllable flying saucer. Figure 9.1 shows what Flying Saucer looks like. The complete source code, executable, and images for the Flying Saucer applet are included on the accompanying CD-ROM.

Figure 9.1 : The Flying Saucer sample applet.

The FlyingSaucer class models the applet itself and takes care of all the details related to setting up the sprite classes and handling the user input events. Similar to the other applet classes you've developed that use sprites, FlyingSaucer contains familiar support for the sprite classes. In fact, the only significantly new code in the FlyingSaucer class is the code for handling user input.

Before getting into the specifics of the user input handlers, however, take a look at two of the member variables defined in the FlyingSaucer class:

private Sprite theSaucer;
private int lastKey;

The theSaucer member variable is a Sprite object that holds the flying saucer sprite. It is necessary to keep up with this sprite outside of the sprite list because you need to be able to alter its position and velocity based on user input events. The lastKey member variable is used to hold the value of the last key pressed. This variable is used to provide finer control over the flying saucer, as you'll see later in this lesson.

The keyDown method handles all the details of supporting keyboard control of the saucer. Listing 9.3 shows the source code for the keyDown method.

Listing 9.3. The FlyingSaucer class's keyDown method.

public boolean keyDown(Event evt, int key) {
  // Change the saucer velocity based on the key pressed
  Point vel = theSaucer.getVelocity();
  switch (key) {
  case Event.LEFT:
    vel.x = -4;
    if (lastKey == Event.LEFT)
      vel.y = 0;
    break;
  case Event.RIGHT:
    vel.x = 4;
    if (lastKey == Event.RIGHT)
      vel.y = 0;
    break;
  case Event.UP:
    vel.y = -4;
    if (lastKey == Event.UP)
      vel.x = 0;
    break;
  case Event.DOWN:
    vel.y = 4;
    if (lastKey == Event.DOWN)
      vel.x = 0;
    break;
  default:
    vel.x = vel.y = 0;
  }
  theSaucer.setVelocity(vel);
  lastKey = key;
  return true;
}

The keyDown method first gets the current velocity of the saucer and checks to see which key was pressed. It then alters the saucer's velocity according to the directional arrow key pressed. The lastKey member variable is then checked to see whether this is a repeat key press. If so, the tangential velocity component is cleared. For example, if the left arrow key is held down, the Y velocity component is cleared. This has the result of causing the saucer to change from moving in a diagonal direction to moving in a pure X or Y direction if you hold a key down, which gives the keyboard controls a better feel. Try it out for yourself.

The mouseDown and mouseDrag methods are used to handle mouse input events and position the saucer at an absolute location:

public boolean mouseDown(Event evt, int x, int y) {
  theSaucer.setPosition(new Point(x - (saucerSize.width / 2),
    y - (saucerSize.height / 2)));
  return true;
}

public boolean mouseDrag(Event evt, int x, int y) {
  theSaucer.setPosition(new Point(x - (saucerSize.width / 2),
    y - (saucerSize.height / 2)));
  return true;
}

Both of these methods simply reposition the saucer at a location centered on the current mouse position, which enables you to click and drag the saucer around with the mouse. This might not be an ideal usage of the mouse in most game scenarios, but it shows how the mouse can be used to control a sprite, which can be useful.

Summary

In this lesson, you learned about Java events and the event-driven architecture necessary to support them. More specifically, you learned about Java input events, including the input devices capable of generating them and how they are handled by the Java awt library.

You saw examples of using the input event handler methods to capture and respond to keyboard and mouse events. You then finished up the lesson with a sample applet using the sprite classes that implements a user-controllable flying saucer supporting both keyboard and mouse input. This sample applet brought you yet another step closer to implementing a complete game. As a matter of fact, you're now ready to embark on your first complete Java game; the next lesson focuses on developing your first full-blown Java game, Traveling Gecko.

Q&A

Workshop

The Workshop section provides questions and exercises to help strengthen your grasp on the material you learned toChapter. Try to answer the questions and at least put some thought into the exercises before moving on to tomorrow's lesson. You'll find the answers to the questions in appendix A, "Quiz Answers."

Quiz

1. What is an event?
2. How do you determine whether the user is holding down the Shift key while moving the mouse?
3. How can you detect when the mouse has been moved outside the applet window?
4. How is the saucer controlled in the Flying Saucer applet?