Identifying the Target

All events occur within a Java Component. The program decides which component gets the event by starting at the outermost level and working in. In Figure 4.1, assume that the user clicks at the location (156, 70) within the enclosing Frame's coordinate space. This action results in a call to the Frame's deliverEvent() method, which determines which component within the frame should receive the event and calls that component's deliverEvent() method. In this case, the process continues until it reaches the Button labeled Blood, which occupies the rectangular space from (135, 60) to (181, 80). Blood doesn't contain any internal components, so it must be the component for which the event is intended. Therefore, an action event is delivered to Blood, with its coordinates translated to fit within the button's coordinate space--that is, the button receives an action event with the coordinates (21, 10). If the user clicked at the location (47, 96) within the Frame's coordinate space, the Frame itself would be the target of the event because there is no other component at this location.

To reach Blood, the event follows the component/container hierarchy shown in Figure 4.2.

Dealing With Events

Once deliverEvent() identifies a target, it calls that target's handleEvent() method (in this case, the handleEvent() method of Blood) to deliver the event for processing. If Blood has not overridden handleEvent(), its default implementation would call Blood's action() method. If Blood has not overridden action(), its default implementation (which is inherited from Component) is executed and does nothing. For your program to respond to the event, you would have to provide your own implementation of action() or handleEvent().

handleEvent() plays a particularly important role in the overall scheme. It is really a dispatcher, which looks at the type of event and calls an appropriate method to do the actual work: action() for action events, mouseUp() for mouse up events, and so on. Table 4.1 shows the event-handler methods you would have to override when using the default handleEvent() implementation. If you create your own handleEvent(), either to handle an event without a default handler or to process events differently, it is best to leave these naming conventions in place. Whenever you override an event-handler method, it is a good idea to call the overridden method to ensure that you don't lose any functionality. All of the event handler methods return a boolean, which determines whether there is any further event processing; this is described in the next section, "Passing the Buck."

Passing the Buck

In actuality, deliverEvent() does not call handleEvent() directly. It calls the postEvent() method of the target component. In turn, postEvent() manages the calls to handleEvent(). postEvent() provides this additional level of indirection to monitor the return value of handleEvent(). If the event handler returns true, the handler has dealt with the event completely. All processing has been completed, and the system can move on to the next event. If the event handler returns false, the handler has not completely processed the event, and postEvent() will contact the component's Container to finish processing the event. Using the screen in Figure 4.1 as the basis, Example 4.1 traces the calls through deliverEvent(), postEvent(), and handleEvent(). The action starts when the user clicks on the Blood button at coordinates (156, 70). In short, Java dives into the depths of the screen's component hierarchy to find the target of the event (by way of the method deliverEvent()). Once it locates the target, it tries to find something to deal with the event by working its way back out (by way of postEvent(), handleEvent(), and the convenience methods). As you can see, there's a lot of overhead, even in this relatively simple example. When we discuss the Java 1.1 event model, you will see that it has much less overhead, primarily because it doesn't need to go looking for a component to process each event.

DeliverEvent.deliverEvent (Event e) called
    DeliverEvent.locate (e.x, e.y)
    Finds Panel1
    Translate Event Coordinates for Panel1
    Panel1.deliverEvent (Event e)
        Panel1.locate (e.x, e.y)
        Finds Panel3
        Translate Event Coordinates for Panel3
        Panel3.deliverEvent (Event e)
            Panel3.locate (e.x, e.y)
            Finds Blood
            Translate Event Coordinates for Blood
            Blood.deliverEvent (Event e)
                Blood.postEvent (Event e)
                    Blood.handleEvent (Event e)
                        Blood.mouseDown   (Event e, e.x, e.y)
                            returns false
                        return false
                    Get parent Container Panel3
                    Translate Event Coordinates for Panel3
                    Panel3.postEvent (Event e)
                        Panel3.handleEvent (Event e)
                            Component.mouseDown (Event e, e.x, e.y)
                                returns false
                            return false
                        Get parent Container Panel1
                        Translate Event Coordinates for Panel1
                        Panel1.postEvent (Event e)
                            Panel1.handleEvent (Event e)
                                Component.action (Event e, e.x, e.y)
                                    return false
                                return false
                            Get parent Container DeliverEvent
                            Translate Event Coordinates for DeliverEvent
                            DeliverEvent.postEvent (Event e)
                                DeliverEvent.handleEvent
                                    DeliverEvent.action (Event e, e.x, e.y)
                                        return true
                                    return true
                                return true
                            return true
                        return true
                    return true
                return true
            return true
        return true
    return true

Overriding handleEvent()

In many programs, you only need to override convenience methods like action() and mouseUp(); you usually don't need to override handleEvent(), which is the high level event handler that calls the convenience methods. However, convenience methods don't exist for all event types. To act upon an event that doesn't have a convenience method (for example, LIST_SELECT), you need to override handleEvent() itself. Unfortunately, this presents a problem. Unlike the convenience methods, for which the default versions don't take any action, handleEvent() does quite a lot: as we've seen, it's the dispatcher that calls the convenience methods. Therefore, when you override handleEvent(), either you should reimplement all the features of the method you are overriding (a very bad idea), or you must make sure that the original handleEvent()is still executed to ensure that the remaining events get handled properly. The simplest way for you to do this is for your new handleEvent() method to act on any events that it is interested in and return true if it has handled those events completely. If the incoming event is not an event that your handleEvent() is interested in, you should call super.handleEvent() and return its return value. The following code shows how you might override handleEvent() to deal with a LIST_SELECT event:

public boolean handleEvent (Event e) {
    if (e.id == Event.LIST_SELECT) {   // take care of LIST_SELECT
        System.out.println ("Selected item: " + e.arg);
        return true;    // LIST_SELECT handled completely; no further action
    } else {   // make sure we call the overridden method to ensure
                // that other events are handled correctly
        return super.handleEvent (e);
    }
}

Basic Event Handlers

The convenience event handlers like mouseDown(), keyUp(), and lostFocus() are all implemented by the Component class. The default versions of these methods do nothing and return false. Because these methods do nothing by default, when overriding them you do not have to ensure that the overridden method gets called. This simplifies the programming task, since your method only needs to return false if it has not completely processed the event. However, if you start to subclass nonstandard components (for example, if someone has created a fancy AudioButton, and you're subclassing that, rather than the standard Button), you probably should explicitly call the overridden method. For example, if you are overriding mouseDown(), you should include a call to super.mouseDown(), just as we called super.handleEvent() in the previous example. This call is "good housekeeping"; most of the time, your program will work without it. However, your program will break as soon as someone changes the behavior of the AudioButton and adds some feature to its mouseDown() method. Calling the super class's event handler helps you write "bulletproof " code.

The code below overrides the mouseDown() method. I'm assuming that we're extending a standard component, rather than extending some custom component, and can therefore dispense with the call to super.mouseDown().

public boolean mouseDown (Event e, int x, int y) {
    System.out.println ("Coordinates: " + x + "-" + y);
    if ((x > 100) || (y < 100))
        return false;    // we're not interested in this event; pass it on
    else                 // we're interested;
        ...              // this is where event-specific processing goes
        return true;     // no further event processing
}

Here's a debugging hint: when overriding an event handler, make sure that the parameter types are correct--remember that each convenience method has different parameters. If your overriding method has parameters that don't match the original method, the program will still compile correctly. However, it won't work. Because the parameters don't match, your new method simply overloads the original, rather than overriding it. As a result, your method will never be called.