The JavaTM Tutorial

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Trail: Creating a GUI with JFC/Swing
Lesson: Writing Event Listeners

## How to Write Window Listeners

> This section explains how to implement three kinds of window-related event handlers: `WindowListener`, `WindowFocusListener`, and `WindowStateListener`. All three handle `WindowEvent`s. The methods in all three event handlers are implemented by the abstract `WindowAdapter` class.

> When the appropriate listener has been registered on a window (such as a frame or dialog), window events are fired just after the window is opened, closed, iconified, deiconified, activated, deactivated, maximized, restored to normal, or gains or loses the focus. 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 is a frame or a dialog that either is the focused window, or owns the focused window; deactivation is the opposite. Maximizing the window means increasing its size to the maximum allowable, either in the vertical direction, the horizontal direction, or both.

> The `WindowListener` interface defines methods to handle most window events, such as the events for opening and closing the window, activation and deactivation of the window, and iconification and deiconification of the window.

> The other two window listener interfaces, `WindowFocusListener` and `WindowStateListener`, were introduced in release 1.4. `WindowFocusListener` contains methods to detect when the window has gained or lost the focus. `WindowStateListener` has a single method to detect a change to the state of the window, such as when the window is iconified, deiconified, maximized, or restored to normal.

> > Version note: Prior to release 1.4, focus-gained and focus-lost events were inferred by using the `WindowListener` methods `windowActivated` and `windowDeactivated`. This approach did not work with windows that were not frames or dialogs, because such windows never received those events. To determine a window's iconification, the `ComponentListener` methods `componentHidden` and `componentShown` were used. As of release 1.4, the methods defined in `WindowFocusListener` and `WindowStateListener` are preferred.

> While you can use the `WindowListener` methods to detect some window state, such as iconification, there are a couple reasons why a `WindowStateListener` might be preferable: it has only one method for you to implement, and it provides support for maximization.

> > Note: Not all window managers support all window states. The 1.4 `java.awt.Toolkit` method `isFrameStateSupported(int)` can be used to determine whether a particular window state is supported by a particular window manager. The WindowEventDemo example, described later in this section, shows how this method can be used.

> A common use of window listeners is implementing custom window-closing behavior. For example, you might use a window listener to save data before closing the window, or to exit the program when the last window closes.

> You don't necessarily need to implement a window listener to specify what a window should do when the user closes it. By default, when the user closes a window the window becomes invisible. You can specify different behavior — disposing of the window, for example — using the `JFrame` or `JDialog` `setDefaultCloseOperation` method. If you decide to implement a window-closing handler, then you might want to use `setDefaultCloseOperation(WindowConstants.DO_NOTHING_ON_CLOSE)` to specify that your window listener takes care of all window-closing duties. See Responding to Window-Closing Events for details on how to use `setDefaultCloseOperation`.

> > Version note: As of release 1.4, when the last displayable window within the Java virtual machine (VM) is disposed of, the VM may terminate. In previous releases, such as 1.3, the VM remained running even if all windows were disposed of. Note, however, that there can be a delay before the program exits automatically, and that under some circumstances the program might keep running. It is quicker and safer to explicitly exit the program using `System.exit(int)`. See AWT Threading Issues for more information.

> 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.

> The following example demonstrates window events. A non-editable text area reports all window events that are fired by its window. This demo implements all methods in the `WindowListener`, `WindowFocusListener`, and `WindowStateListener` interfaces. You can find the demo's code in `WindowEventDemo.java`.

> #### [PENDING: screenshot forthcoming]

> > Try this:
> > 1. Run WindowEventDemo using JavaTM Web Start. Or, to compile and run the example yourself, consult the example index.
> > 2. When the window appears, several messages are already displayed. One line reports whether your window manager supports MAXIMIZED_BOTH. If your window manager does not support other window states, this is also reported. Next, several lines are displayed reporting that the window's window listener has received window-opened, activated, and gained-focus events. All the messages displayed in the window are also sent to standard output.
> > 3. Click another window. You'll see "window lost focus" and "window deactivated" messages. If this window were not a frame or a dialog, it wouldn't receive the activated or deactivated events.
> > 4. Click the WindowEventDemo window. You'll see "window activated" and "window gained focus" messages.
> > 5. Iconify the window, using the window controls. Two iconification messages are displayed, one from the window listener and the other from the window state listener, though you won't see them until you deiconify the window, unless you are looking at standard output. Window-deactivation and window-lost-focus events are also reported.
> > 6. Deiconify the window. Two deiconification messages are displayed, one from the window listener and the other from the window state listener. The `windowStateChanged` method in `WindowStateListener` gives the same information that you get using the `windowIconified` and `windowDeiconified` methods in `WindowListener`. Window-activation and window-gained-focus events are also reported.
> > 7. Maximize the window, if your look and feel provides a way to do this. Note that some look and feels running on some window managers, such as the Java look and feel on dtwm, provide a way to maximize the window, but no events are reported. This is because dtwm mimics maximization by resizing the window, but it is not a true maximization event. Some look and feels provide a way to maximize the window in the vertical or horizontal direction only. Experiment with your window controls to see what options are available.
> > 8. Close the window, using the window controls. A window closing message is displayed. Once the window has closed, a window closed message is sent to standard output.

> Here is the demo's window event handling code:

> >     public class WindowEventDemo ... implements WindowListener,
> >                                                 WindowFocusListener,
> >                                                 WindowStateListener {
> >         static JFrame frame;
> >         JTextArea display;

> >         public WindowEventDemo() {
> >             ...
> >             frame.addWindowListener(this);
> >             frame.addWindowFocusListener(this);
> >             frame.addWindowStateListener(this);

> >             checkWM();
> >         }

> >         //Some window managers don't support all window states.
> >         //For example, dtwm doesn't support true maximization,
> >         //but mimics it by resizing the window to be the size
> >         //of the screen.  In this case the window does not fire
> >         //the MAXIMIZED_ constants on the window's state listener.
> >         //Microsoft Windows supports MAXIMIZED_BOTH, but not
> >         //MAXIMIZED_VERT or MAXIMIZED_HORIZ.
> >         public void checkWM() {
> >             Toolkit tk = frame.getToolkit();
> >             if (!(tk.isFrameStateSupported(Frame.ICONIFIED))) {
> >                 displayMessage(
> >                    "Your window manager doesn't support ICONIFIED.");
> >             }
> >             if (!(tk.isFrameStateSupported(Frame.MAXIMIZED_VERT))) {
> >                 displayMessage(
> >                    "Your window manager doesn't support MAXIMIZED_VERT.");
> >             }
> >             if (!(tk.isFrameStateSupported(Frame.MAXIMIZED_HORIZ))) {
> >                 displayMessage(
> >                    "Your window manager doesn't support MAXIMIZED_HORIZ.");
> >             }
> >             if (!(tk.isFrameStateSupported(Frame.MAXIMIZED_BOTH))) {
> >                 displayMessage(
> >                    "Your window manager doesn't support MAXIMIZED_BOTH.");
> >             } else {
> >                 displayMessage(
> >                    "Your window manager supports MAXIMIZED_BOTH.");
> >             }
> >         }

> >         public void windowClosing(WindowEvent e) {
> >             displayMessage("WindowListener method called: windowClosing.");

> >             //A pause so user can see the message before
> >             //the window actually closes.
> >             ActionListener task = new ActionListener() {
> >                 boolean alreadyDisposed = false;
> >                 public void actionPerformed(ActionEvent e) {
> >                     if (!alreadyDisposed) {
> >                         alreadyDisposed = true;
> >                         frame.dispose();
> >                     } else { //make sure the program exits
> >                         System.exit(0);
> >                     }
> >                 }
> >             };
> >             Timer timer = new Timer(500, task); //fire every half second
> >             timer.setInitialDelay(2000);        //first delay 2 seconds
> >             timer.start();
> >         }

> >         public void windowClosed(WindowEvent e) {
> >             //This will only be seen on standard output.
> >             displayMessage("WindowListener method called: windowClosed.");
> >         }

> >         public void windowOpened(WindowEvent e) {
> >             displayMessage("WindowListener method called: windowOpened.");
> >         }

> >         public void windowIconified(WindowEvent e) {
> >             displayMessage("WindowListener method called: windowIconified.");
> >         }

> >         public void windowDeiconified(WindowEvent e) {
> >             displayMessage("WindowListener method called: windowDeiconified.");
> >         }

> >         public void windowActivated(WindowEvent e) {
> >             displayMessage("WindowListener method called: windowActivated.");
> >         }

> >         public void windowDeactivated(WindowEvent e) {
> >             displayMessage("WindowListener method called: windowDeactivated.");
> >         }

> >         public void windowGainedFocus(WindowEvent e) {
> >             displayMessage("WindowFocusListener method called: windowGainedFocus.");
> >         }

> >         public void windowLostFocus(WindowEvent e) {
> >             displayMessage("WindowFocusListener method called: windowLostFocus.");
> >         }

> >         public void windowStateChanged(WindowEvent e) {
> >             displayStateMessage(
> >               "WindowStateListener method called: windowStateChanged.", e);
> >         }

> >         void displayMessage(String msg) {
> >             display.append(msg + newline);
> >             System.out.println(msg);
> >         }

> >         void displayStateMessage(String prefix, WindowEvent e) {
> >             int state = e.getNewState();
> >             int oldState = e.getOldState();
> >             String msg = prefix
> >                        + newline + space
> >                        + "New state: "
> >                        + convertStateToString(state)
> >                        + newline + space
> >                        + "Old state: "
> >                        + convertStateToString(oldState);
> >             display.append(msg + newline);
> >             System.out.println(msg);
> >         }

> >         String convertStateToString(int state) {
> >             if (state == Frame.NORMAL) {
> >                 return "NORMAL";
> >             }
> >             if ((state & Frame.ICONIFIED) != 0) {
> >                 return "ICONIFIED";
> >             }
> >             //MAXIMIZED_BOTH is a concatenation of two bits, so
> >             //we need to test for an exact match.
> >             if ((state & Frame.MAXIMIZED_BOTH) == Frame.MAXIMIZED_BOTH) {
> >                 return "MAXIMIZED_BOTH";
> >             }
> >             if ((state & Frame.MAXIMIZED_VERT) != 0) {
> >                 return "MAXIMIZED_VERT";
> >             }
> >             if ((state & Frame.MAXIMIZED_HORIZ) != 0) {
> >                 return "MAXIMIZED_HORIZ";
> >             }
> >             return "UNKNOWN";
> >         }

> >         public static void main(String[] args) {
> >             ...
> >             //Create and set up the window.
> >             frame = new JFrame("WindowEventDemo");
> >             frame.setDefaultCloseOperation(JFrame.DO_NOTHING_ON_CLOSE);
> >             ...
> >         }
> >     }

### The Window Listener API

> The following tables list the methods in the three window listener interfaces and the methods in the `WindowEvent` class. The methods from all three interfaces are available through the `WindowAdapter` class. The window listener API falls into four categories:
> - The WindowListener Interface
> - The WindowFocusListener Interface
> - The WindowStateListener Interface
> - The WindowEvent Class

> The WindowListener Interface

> Method | Purpose
> --- | ---
> `windowOpened(WindowEvent)` | Called just after the listened-to window has been shown for the first time.
> `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.
> `windowClosed(WindowEvent)` | Called just after the listened-to window has closed.
> `windowIconified(WindowEvent)` `windowDeiconified(WindowEvent)` | Called just after the listened-to window is iconified or deiconified, respectively.
> `windowActivated(WindowEvent)` `windowDeactivated(WindowEvent)` | Called just after the listened-to window is activated or deactivated, respectively. These methods are not sent to windows that are not frames or dialogs. For this reason, we prefer the 1.4 `windowGainedFocus` and `windowLostFocus` methods to determine when a window gains or loses the focus.

> The WindowFocusListener Interface

> This interface was introduced in release 1.4.

> Method | Purpose
> --- | ---
> `windowGainedFocus(WindowEvent)` `windowLostFocus(WindowEvent)` | Called just after the listened-to window gains or loses the focus, respectively.

> The WindowStateListener Interface

> This interface was introduced in release 1.4.

> Method | Purpose
> --- | ---
> `windowStateChanged(WindowEvent)` | Called just after the listened-to window's state is changed by being iconified, deiconified, maximized, or returned to normal. The state is available through the `WindowEvent` as a bitwise mask. The possible values, defined in `java.awt.Frame`, are: NORMAL. Indicates that no state bits are set. ICONIFIED MAXIMIZED_HORIZ MAXIMIZED_VERT MAXIMIZED_BOTH. Concatenates `MAXIMIZED_HORIZ` and `MAXIMIZED_VERT`. A window manager may support `MAXIMIZED_BOTH`, while not supporting `MAXIMIZED_HORIZ` or `MAXIMIZED_VERT`. The `java.awt.Toolkit` method `isFrameStateSupported(int)` can be used to determine what states are supported by the window manager.

> The WindowEvent Class

> Method | Purpose
> --- | ---
> `Window getWindow()` | Returns the window that fired the event. You can use this instead of the `getSource` method.
> `Window getOppositeWindow()` | Returns the other window involved in this focus or activation change. For a `WINDOW_ACTIVATED` or `WINDOW_GAINED_FOCUS` event, this returns the window that lost activation or the focus. For a `WINDOW_DEACTIVATED` or `WINDOW_LOST_FOCUS` event, this returns the window that gained activation or the focus. For any other type of `WindowEvent` with a Java application in a different VM or context, or with no other window, `null` is returned. This method was introduced in release 1.4.
> `int getOldState()` `int getNewState()` | For `WINDOW_STATE_CHANGED` events these methods return the previous or new state of the window as a bitwise mask. These methods were introduced in release 1.4.

### Examples that Use Window Listeners

> The following table lists the examples that use window listeners.

> Example | Where Described | Notes
> --- | --- | ---
> `WindowEventDemo` | This section | Reports all window events that occur on one window to demonstrate the circumstances under which window events are fired.
> `SliderDemo` | How to Use Sliders | Listens for window iconify and deiconify events, so that it can stop the animation when the window isn't visible.
> `InternalFrameEventDemo` | How to Write an Internal Frame Listener | Reports all internal frame events that occur on one internal frame to demonstrate the circumstances under which internal frame events are fired. Internal frame events are similar to window events.
> `DialogDemo` | Text Component Features | `CustomDialog.java` uses `setDefaultCloseOperation` instead of a window listener to determine what action to take when the user closes the window.
> `Framework` | — | A demo that allows multiple windows to be created and destroyed.

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Copyright 1995-2004 Sun Microsystems, Inc. All rights reserved.