Handling Events

In the previous chapter, you find out how to create Swing frames that include panels, labels, and buttons. However, the frames don't do anything other than sit there. They look good, but they're completely unresponsive. Click them all you want, but they don't do anything. They're kind of like teenagers.

In this chapter, you get those buttons to do something. Specifically, you find out how to write code that's executed when a user clicks a button. The technique you use to do that is called event listening, and it's one of the most important aspects of writing Swing programs. It may seem a little complicated at first, but after you get the swing of it (sorry), event listening makes perfect sense.

Examining Events

An event is an object that's generated when the user does something noteworthy with one of your user-interface components. For example, if the user clicks a button, drags the mouse over a label, or selects an item from a combo box, an event object is generated. This event object is then passed to a special method you create called an event listener. The event listener can examine the event object, determine exactly what type of event occurred, and respond accordingly. For example, if the user clicks a button, the event listener might write any data entered by the user via text fields to a file. If the user passes the mouse over a label, the event handler might change the text displayed by the label. And if the user selects an item from a combo box, the event handler might use the value that was selected to look up information in a database. The possibilities are endless!

There are several different types of event objects, represented by various classes that all inherit AWTEvent. Table 2-1 lists the most commonly used event classes. In addition, this table lists the listener interface that's used to create an object that can listen for the event and handle it when it is generated.

Now that you know the basic objects that are used for event handling, you have to actually wire them up to create a program that responds to events.

To write Java code that responds to events, you have to do the following:

1. Create a component that can generate events.

   You want to add buttons or other components that generate events to your frame so it displays components the user can interact with. (Strictly speaking, all Swing components can generate some events.

   Even a label generates a MouseEvent when the user moves the mouse over it. But a frame that consists of nothing but labels isn't very useful.)

   Usually, you declare the variable that refers to the event source as a private class field, outside of the constructor for the frame or any other method. For example

   private JButton button1;

   Then, in the constructor for the frame class, you can create the button. For example, here's code that creates a panel, creates a button, adds it to a panel, and then adds the panel to the frame:

   JPanel panel = new JPanel(); button1 = new JButton("Click me!"); panel.add(button1); this.add(panel);

   Note that this code appears in the constructor of the frame class, so in the last line this refers to the frame.

2. Create a class that implements the listener interface for the event you want to handle.

   For example, to handle action events, you should create a class that implements the ActionListener interface. As you see later in this chapter, you can do that in at least four ways. But one of the easiest is to simply add implements ActionListener to the definition of the frame class. Thus, the frame class declaration looks something like this:

   public class ClickMe extends JFrame implements ActionListener

   Later in this chapter, I tell you about other ways to implement the event listener interface.

3. Write the code for any methods defined by the listener.

   When you implement a listener interface, you must provide an implementation of each method defined by the interface. Most listener interfaces define just one method, corresponding to the type of event the interface listens for. For example, the ActionListener interface defines a method named actionPerformed. This method is called whenever an action event is created. Thus the code you place inside the actionPerformed method is executed when an action event occurs.

   For example, here's an actionPerformed method that responds to action events:

   public void actionPerformed(ActionEvent e) { if (e.getSource() == button1) button1.setText("You clicked!"); }

   Here this code changes the text displayed by button1 if the event source is button1.

4. Register the listener with the source.

   The final step is to register the event listener with the event source. Every component that serves as an event source provides a method that lets you register event listeners to listen for the event. For ActionEvent sources, the method is addActionListener. Here's a modification to the frame constructor code that creates the button1 button and registers the frame class as the action event listener:

   JPanel panel = new JPanel(); button1 = new JButton("Click me!"); button1.addActionListener(this); panel.add(button1); this.add(panel);

   Here you can specify this as the event listener because the frame class itself implements ActionListener.

The ClickMe Program

To see how all these elements work together in a complete program, Figure 2-1 shows three incarnations of a frame created by a program called ClickMe. This program displays a frame that has a single button that initially says Click Me! When the user clicks the button, the button's text changes to I've been clicked! (as shown in the second frame in the figure). Then, if the user clicks the button again, the text changes to I've been clicked 2 times! (as shown in the third frame). Thereafter, the count increases each time the button is clicked. Listing 2-1 shows the complete code for this program.

Figure 2-1: The ClickMe program in action.

Listing 2-1: The ClickMe Program

import javax.swing.*; import java.awt.event.*; → 2 public class ClickMe extends JFrame implements ActionListener → 5 { public static void main(String [] args) → 7 { new ClickMe(); } private JButton button1; → 12 public ClickMe() → 14 { this.setSize(200,100); this.setDefaultCloseOperation (JFrame.EXIT_ON_CLOSE); this.setTitle("I'm Listening"); JPanel panel1 = new JPanel(); button1 = new JButton("Click Me!"); → 21 button1.addActionListener(this); → 22 panel1.add(button1); this.add(panel1); this.setVisible(true); } private int clickCount = 0; → 29 public void actionPerformed(ActionEvent e) → 31 { if (e.getSource() == button1) → 33 { clickCount++; → 35 if (clickCount == 1) → 36 button1.setText("I've been clicked!"); else button1.setText("I've been clicked" + clickCount + " times!"); } } }

The following paragraphs point out some key lines of the program:

Open table as spreadsheet

Using Inner Classes to Listen for Events

As explained in Book III, Chapter 7, an inner class is a class that's nested within another class. Inner classes are commonly used for event listeners. That way the class that defines the frame doesn't also have to implement the event listener. Instead, it includes an inner class that handles the events.

Listing 2-2 shows a version of the ClickMe program that uses an inner class to handle the action event for the button.

Listing 2-2: The ClickMe2 Program with an Inner Class

import javax.swing.*; import java.awt.event.*; public class ClickMe2 extends JFrame → 4 { public static void main(String [] args) { new ClickMe2(); } private JButton button1; → 11 public ClickMe2() { this.setSize(200,100); this.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE); this.setTitle("I'm Listening"); ClickListener cl = new ClickListener(); → 20 JPanel panel1 = new JPanel(); button1 = new JButton("Click Me!"); button1.addActionListener(cl); → 24 panel1.add(button1); this.add(panel1); this.setVisible(true); } private class ClickListener implements ActionListener → 32 { private int clickCount = 0; → 34 public void actionPerformed(ActionEvent e) { if (e.getSource() == button1) → 38 { clickCount++; if (clickCount == 1) button1.setText("I've been clicked " else button1.setText("I've been clicked!"); + clickCount + " times!"); } } } }

This program works essentially the same as the program shown in Listing 2-1, so I won't review the basics. Instead, I just point out some highlights:

Open table as spreadsheet

Adding an Exit Button

In Book VI, Chapter 1, you find out how to create a frame that exits the application when the user clicks the frame's Exit button. To add an Exit button to your application, you must do three things:

1. Create the Exit button and add it to the frame.

   Usually, you actually add the Exit button to a panel that is in turn added to the frame.

2. Add an action event listener to the button.
3. Add code in the actionPerformed method of the action listener to quit the application when the user clicks the button.

   You normally do that by calling System.exit(0).

Suppose you want to change the ClickMe2 application that is shown in Listing 2-2 so that it has an Exit button, but the Exit button won't let the user quit unless he or she has clicked the ClickMe button at least once. First, you change Line 11 to declare an exitButton class field:

private JButton button1, exitButton;

Next, you add code to the constructor to create the button, register the event listener, and add the button to the panel:

exitButton = new JButton("Exit"); exitButton.addActionListener(cl); panel1.add(exitButton);

Finally, you modify the actionPerformed method of the ClickListener class to handle the Exit button:

public void actionPerformed(ActionEvent e) { if (e.getSource() == button1) { clickCount++; if (clickCount == 1) button1.setText("I've been clicked!"); else button1.setText("I've been clicked " + clickCount + " times!"); } else if (e.getSource() == exitButton) { if (clickCount > 0) System.exit(0); else { JOptionPane.showMessageDialog( ClickMe3.this, "You must click at least once!", "Not so fast, buddy", JOptionPane.ERROR_MESSAGE); } } }

Here an if statement is used to determine which button is clicked when the actionPerformed method is called. This step is necessary because the ClickHandler class is used to handle action events for both buttons. If the event source is the Exit button, another if statement checks to see if the clickCount variable is greater than zero. If it is, System.exit(0) is called to end the application. Otherwise JOptionPane is used to display an error message, and the application is not ended.

Catching the WindowClosing Event

Book VI, Chapter 1 shows you how to use the setDefaultCloseOperation method of the JFrame class to let the user quit the application by using the frame's Close button. However, if your application checks to see whether data has been saved (or other conditions have been met) before allowing the user to exit, this approach won't work. In that case, you want to set up the Close button so it works the same as your Exit button.

To do that, you need to add a listener that listens for window events to the frame. When the user clicks the Close button, the frame generates a windowClosing event which you can handle by registering a WindowListener with the frame itself. Then, in the windowClosing method of the WindowListener, you can just call the Exit button's doClick event. That triggers an action event for the Exit button as if the user clicked it. Thus the Close button is handled in exactly the same way as the Exit button.

The first step to setting up a window listener is getting rid of the default behavior that automatically exits the application when the user clicks the Close button. To do that, you must change the constant you use in the setDefaultCloseOperation from EXIT_ON_CLOSE to DO_NOTHING_ ON_CLOSE, like this:

this.setDefaultCloseOperation( JFrame.DO_NOTHING_ON_CLOSE);

This way the default action of the JFrame class is to completely ignore the Close button. Then you can install a window listener to handle the Close button any way you want.

Next, you can set up the WindowListener to listen for window events. One way to do that is to create an inner class that implements the WindowListener interface. Unfortunately, the WindowListener interface has a lot of methods, and you must provide an implementation for each method even if you don't want to do anything for that method. Thus your WindowListener looks something like this:

private class Closer implements WindowListener { public void windowClosing(WindowEvent e) { exitButton.doClick(); } public void windowActivated(WindowEvent e) {} public void windowClosed(WindowEvent e) {} public void windowDeactivated(WindowEvent e) {} public void windowDeiconified(WindowEvent e) {} public void windowIconified(WindowEvent e) {} public void windowOpened(WindowEvent e) {} }

Finally, you register the WindowListener with the frame by calling its addWindowListener method in the frame class constructor:

this.addWindowListener(new Closer());

Many of Java's event listener interfaces have corresponding adapter classes. They're listed in Table 2-3. Here's what the Closer class looks like if you extend WindowAdapter instead of implement WindowListener:

private class Closer extends WindowAdapter { public void windowClosing(WindowEvent e) { exitButton.doClick(); } }

That saves some code. However, you can save even more code by skipping the Closer class altogether, and handling the window closing event with an anonymous inner class instead. Then the statement in the frame constructor that registers the window event listener looks like this:

addWindowListener(new WindowAdapter() { public void windowClosing(WindowEvent e) { exitButton.doClick(); } });

Here the window listener is created as an anonymous inner class that extends WindowAdapter and defines the windowClosing method.

The ClickMe Program Revisited

Now that you've mulled over the various techniques for creating an Exit button and handling the Close button, Listing 2-3 presents a third version of the ClickMe program that adds all these features so you can see how they work together. This version of the program adds an Exit button, but does not allow the user to quit until he or she has clicked the ClickMe button at least once. And it treats the Close button as if the user had clicked Exit.

Listing 2-3: The ClickMe Application with an Exit Button

import javax.swing.*; import java.awt.event.*; public class ClickMe3 extends JFrame { public static void main(String [] args) { new ClickMe3(); } private JButton button1, exitButton; → 11 public ClickMe3() { this.setSize(275,100); this.setTitle("I'm Listening"); this.setDefaultCloseOperation( → 17 JFrame.DO_NOTHING_ON_CLOSE); ClickListener cl = new ClickListener(); JPanel panel1 = new JPanel(); addWindowListener(new WindowAdapter() → 24 { public void windowClosing(WindowEvent e) { exitButton.doClick(); → 28 } }); button1 = new JButton("Click Me!"); button1.addActionListener(cl); panel1.add(button1); exitButton = new JButton("Exit"); → 36 exitButton.addActionListener(cl); panel1.add(exitButton); this.add(panel1); this.setVisible(true); } private class ClickListener implements ActionListener { private int clickCount = 0; public void actionPerformed(ActionEvent e) { if (e.getSource() == button1) { clickCount++; if (clickCount == 1) button1.setText("I've been clicked!"); else button1.setText("I've been clicked " + clickCount + " times!"); } else if (e.getSource() == exitButton) →61 { if (clickCount > 0) System.exit(0); else { JOptionPane.showMessageDialog( ClickMe3.this, "You must click at least once!", "Not so fast, buddy", JOptionPane.ERROR_MESSAGE); } } } } }

The following paragraphs draw your attention to the key sections of this program:

Open table as spreadsheet