The event model is the name for the framework that turns a GUI interaction (mouse click, menu selection, button press, etc.) into a call for your code to process it. The event model can also be used for something unrelated to the GUI, like a timer going off. In other words, the event model is the design for connecting your code to any kind of asynchronous actions, called events, for handling.

The window manager can't directly call your event-handling routines because the run-time library doesn't even see your code until it is asked to run it. Therefore, at run-time the event model has to be told which of your routines handle events.

Java originally used inheritance to tie together your code and the event model. JDK 1.1 introduced a better approach called the delegation-based model. Some of the Java documentation still refers to “1.1-style events,” which is the current model. To get any events, your code has to begin by telling the window system, “send those events of yours to these methods of mine”. You connect the controls that generate events by registering a callback with your event-handling classes, as Figure 20-1 shows.

Figure 20-1. How events are passed in JDK 1.1

You register your handler code once at the beginning with the GUI object that will be generating events. After that, those events are fired (or sent) to you when they occur. In particular, your handler code is called and passed the event object as an argument.

If you do not completely understand callbacks, go back and read that section in Chapter 11. It is essential that you understand callbacks because they form the basis of the new event-handling model.

The events that are fired from the source to the listener are simply objects passed as arguments to a method call. An event object has several data fields holding information, such as where the event took place on the screen, a description of the event, the number of mouse clicks, the state of a checkbox, and so on. There is a general java.util.EventObject type and all AWT events are children of that, as Figure 20-2 shows.

Figure 20-2. The hierarchy of event objects in JDK 1.1

A JFrame, a subclass of the AWT class Frame, has a title string and a menu bar on which you can add several menus. Following is the code to put a JFrame on the screen from an application:

Compiling and executing this program results in a frame similar to Figure 20-3 to appear on the screen. Here, we just gave it the name on the title bar of “Example.”

Figure 20-3. The JFrame is a subclass of Frame, which is a subclass of Window

Since it is a Window, JFrame is capable of receiving events generated by Windows. Clicking a Window to close it generates an event. If you try this with the program we described, you'll notice that the JFrame goes away but your program stays active. You must press Control-C to exit the program because you need to write code to handle the “window closing” event. The code should quit the program when it is invoked.

Let's add an event handler to our JFrame that notices when the WindowClosing event takes place. That event will be delivered when you click to close a Window.

First, tell our JFrame that Window events are handled by an object that I call “mwh” here—a nice short name which is an abbreviation of “my window handler.” The code appears exactly as before, and we add the following line to the main() routine:

The callback for a Window event is registered by calling the AWT method addWindowListener. This is a method in the Window superclass of JFrame that takes as a parameter an interface called WindowListener. Your applet must declare an instance of a class that implements the WindowListener interface and that will be the event handler for this button. You still have to write that class, but assuming it has the name shown below, you can instantiate an object according to the following example:

The last step is to write the myCodeToHandleWinClose class that implements the java.awt.event.WindowListener interface and provides the promised methods. The class can be in a separate file or contained in the same one.

The windowClosing() method of the myCodeToHandleWinClose class is called whenever the Window “close” choice is made. Notice that it was necessary to provide declarations for all the routines in the interface. Since we are interested only in WindowClosing, there are empty bodies for the other methods. We'll show a way of simplifying this later in the chapter.

The WindowListener interface (like many of the SomethingListener interfaces) is declared in the java.awt.event package. There are other event and Listeners declared in the javax.swing.event package. The WindowListener interface promises that there will be half a dozen methods with specific names. The methods will be called for different Window events now that we have delegated the task to the object “mwh” that contains the methods.

One advantage of the Java event framework is that the GUI-related code is easily separated from the application logic code. This flows from good use of OOP: put everything in a class of its own and declare instances of the class as needed. In this way, encapsulation works for you. If you want to change what happens on window close, you just update the class that deals specifically with it. In a non-OOP implementation, it's too easy to mix everything together, making program maintenance and testing ten times harder than it should be. The same event framework is used for JavaBeans (component software), as well as the AWT.

Putting the whole thing together and into our JFrame example, the following code handles the window closing event:

Notice that the code inside the WindowClosing method calls System.exit() to quit the program. When you run this, you'll see the same frame as before, but when you click on the window to close it, the program will now exit gracefully. Well done! You have finished your first example of an event handler.

You may wonder what events exist, what interfaces deal with them, and what methods the Listener interfaces use. Table 20-1 summarizes the answers to all three questions. You should also review the javadoc pages for classes and interfaces in package java.awt.event. The source code for the interfaces and their methods can also be reviewed in the directory $JAVAHOME/src/java/awt/event.

The same framework is used by all the event handlers:

You can reduce the amount of code with inner classes. See ips for Slimming Down Handler Code on page 508.