Writing Event Listeners

How to Write a Window Listener

Window events are generated by a Window just after the window is opened, closed, iconified, deiconified, activated, or deactivated. Opening a window means showing it for the first time; closing it means removing the window from the screen. Iconifying it means substituting a small icon on the desktop for the window; deiconifying means the opposite. A window is activated if it or a component it contains has the keyboard focus; deactivation occurs when the window and all of its contents lose the keyboard focus.

[PENDING: smooth this out for Swing] The most common use of window listeners is closing windows. If a program doesn't handle window-closing events, then nothing happens when the user attempts to close a window. An application that features a single window might react to window-closing events from that window by exiting. Other programs usually react to window-closing events by disposing of the window or making it invisible. See How to Make Frames for an example of a handler for window-closing events.

---

Note: If you're using the Swing JFrame class, you might not need to write a window listener. See How to Make Frames for information on how the JFrame class provides automatic handling of window-closing events.

---

Another common use of window listeners is to stop threads and release resources when a window is iconified, and to start up again when the window is deiconified. This way, you can avoid unnecessarily using the processor or other resources. For example, when a window that contains animation is iconified, it should stop its animation thread and free any large buffers. When the window is deiconified, it can start the thread again and recreate the buffers.

[PENDING: really? Not in book] If you want to be notified when a window is made visible or hidden, then you should register a component listener on the window.

Window Event Methods

The WindowListener interface and its corresponding adapter class, WindowAdapter, contain these methods:

void windowOpened(WindowEvent)

Called just after the listened-to window has been shown for the first time.

void windowClosing(WindowEvent)

Called in response to a user request that the listened-to window be closed. To actually close the window, the listener should invoke the window's dispose or setVisible(false) method.

void windowClosed(WindowEvent)

Called just after the listened-to window has closed.

void windowIconified(WindowEvent)
void windowDeiconified(WindowEvent)

Called just after the listened-to window is iconified or deiconified, respectively.

void windowActivated(WindowEvent)
void windowDeactivated(WindowEvent)

Called just after the listened-to window is activated or deactivated, respectively.

Examples of Handling Window Events

The following applet demonstrates window events. By clicking the top button in the applet, you can bring up a small window. The controlling class listens for window events from the window, displaying a message whenever it detects a window event. You can find the applet's code in WindowEventDemo.java.

This is a picture of the applet's GUI. To run the applet, click the picture. The applet will appear in a new browser window.

---

Try this:

1. Bring up the Window Demo Window by clicking the applet's top button.
   The first time you click this button, you'll see a "Window opened" message in the applet's display area.
2. Click the window if it doesn't already have the focus.
   Do you see a "Window activated" message in the applet's display area?
3. Iconify the window, using the window controls.
   You'll see a "Window iconified" message in the applet's display area.
4. Deiconify the window.
   You'll see a "Window deiconified" message in the applet's display area.
5. Close the window, using the window controls.
   You'll see "Window closing" in the applet's display area. Because the window-closing event handler invokes setVisible(false) instead of dispose(), you won't see "Window closed".

---

Here is the applet's window event handling code:

public class WindowEventDemo ... implements WindowListener {
     ...//where initialization occurs:
        //Create but don't show window.
        window = new JFrame("Window Event Window");
        window.addWindowListener(this);
        window.getContentPane().add(
	    new JLabel("The applet listens to this window for window events."),
	    BorderLayout.CENTER);
        window.pack();
    }

    public void windowClosing(WindowEvent e) {
        window.setVisible(false);
        displayMessage("Window closing", e);
    }

    public void windowClosed(WindowEvent e) {
        displayMessage("Window closed", e);
    }

    public void windowOpened(WindowEvent e) {
        displayMessage("Window opened", e);
    }

    public void windowIconified(WindowEvent e) {
        displayMessage("Window iconified", e);
    }

    public void windowDeiconified(WindowEvent e) {
        displayMessage("Window deiconified", e);
    }

    public void windowActivated(WindowEvent e) {
        displayMessage("Window activated", e);
    }

    public void windowDeactivated(WindowEvent e) {
        displayMessage("Window deactivated", e);
    }

    void displayMessage(String prefix, WindowEvent e) {
        display.append(prefix
                       + ": "
                       + e.getWindow()
                       + newline); 
    }
    ...
}

Here are some of the source files that contain window listeners:

• ShowDocument.java
• ComponentEventDemo.java
• FlowWindow.java
• AnimatorApplicationTimer.java

The WindowEvent Class

Each window event method has a single parameter: a WindowEvent object.

Window getWindow()

Returns the window that generated the event. You can use this instead of the getSource method.

Writing Event Listeners