The Java Tutorials have been written for JDK 8. Examples and practices described in this page don't take advantage of improvements introduced in later releases and might use technology no longer available.
See Java Language Changes for a summary of updated language features in Java SE 9 and subsequent releases.
See JDK Release Notes for information about new features, enhancements, and removed or deprecated options for all JDK releases.
This section explains how to implement three kinds of window-related event handlers: WindowListener
, WindowFocusListener
, and WindowStateListener
. All three listeners handle WindowEvent
objects. 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 activity or state has occurred. A window is considered as a "focus owner", if this window receives keyboard input.
The following window activities or states can precede a window event:
The WindowListener
interface defines methods that 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 are WindowFocusListener
and WindowStateListener
. WindowFocusListener
contains methods to detect when the window becomes the focus owner or it loses the focus owner status. 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.
While you can use the WindowListener
methods to detect some window states, such as iconification, there are two reasons why a WindowStateListener
might be preferable: it has only one method for you to implement, and it provides support for maximization.
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.
Window listeners are commonly used to implement custom window-closing behavior. For example, a window listener is used to save data before closing the window, or to exit the program when the last window closes.
A user does not 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. To specify different behavior, use the setDefaultCloseOperation
method of the JFrame
or JDialog
classes. To implement a window-closing handler, use the setDefaultCloseOperation(WindowConstants.DO_NOTHING_ON_CLOSE)
method to enable the window listener to provide all window-closing duties. See
Responding to Window-Closing Events for details on how to use setDefaultCloseOperation
.
System.exit(int)
. See
AWT Threading Issues for more information.
Window listeners are also commonly used to stop threads and release resources when a window is iconified, and to start up again when the window is deiconified. This avoids 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
.
windowStateChanged
method in WindowStateListener
class gives the same information that you get using the windowIconified
and windowDeiconified
methods in WindowListener
class. Window-activation and window-gained-focus events are also reported.Here is the demo's window event handling code:
public class WindowEventDemo extends JFrame implements WindowListener, WindowFocusListener, WindowStateListener { ... static WindowEventDemo frame = new WindowEventDemo("WindowEventDemo"); JTextArea display; ... private void addComponentsToPane() { display = new JTextArea(); display.setEditable(false); JScrollPane scrollPane = new JScrollPane(display); scrollPane.setPreferredSize(new Dimension(500, 450)); getContentPane().add(scrollPane, BorderLayout.CENTER); addWindowListener(this); addWindowFocusListener(this); addWindowStateListener(this); checkWM(); } public WindowEventDemo(String name) { super(name); } //Some window managers don't support all window states. public void checkWM() { Toolkit tk = frame.getToolkit(); if (!(tk.isFrameStateSupported(Frame.ICONIFIED))) { displayMessage( "Your window manager doesn't support ICONIFIED."); } else displayMessage( "Your window manager supports ICONIFIED."); if (!(tk.isFrameStateSupported(Frame.MAXIMIZED_VERT))) { displayMessage( "Your window manager doesn't support MAXIMIZED_VERT."); } else displayMessage( "Your window manager supports MAXIMIZED_VERT."); if (!(tk.isFrameStateSupported(Frame.MAXIMIZED_HORIZ))) { displayMessage( "Your window manager doesn't support MAXIMIZED_HORIZ."); } else displayMessage( "Your window manager supports 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 (frame.isDisplayable()) { alreadyDisposed = true; frame.dispose(); } } }; Timer timer = new Timer(500, task); //fire every half second timer.setInitialDelay(2000); //first delay 2 seconds timer.setRepeats(false); 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); displayMessage(msg); } String convertStateToString(int state) { if (state == Frame.NORMAL) { return "NORMAL"; } String strState = " "; if ((state & Frame.ICONIFIED) != 0) { strState += "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) { strState += "MAXIMIZED_BOTH"; } else { if ((state & Frame.MAXIMIZED_VERT) != 0) { strState += "MAXIMIZED_VERT"; } if ((state & Frame.MAXIMIZED_HORIZ) != 0) { strState += "MAXIMIZED_HORIZ"; } if (" ".equals(strState)){ strState = "UNKNOWN"; } } return strState.trim(); } }
WindowEvent
class. Their methods are listed in the following tables:
WindowAdapter
class.
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 for the listened-to window to 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, the windowGainedFocus and windowLostFocus methods to determine when a window gains or loses the focus are preferred. |
The WindowFocusListener Interface
Method | Purpose |
---|---|
windowGainedFocus(WindowEvent) windowLostFocus(WindowEvent) |
Called just after the listened-to window gains or loses the focus, respectively. |
The WindowStateListener Interface
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:
|
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. |
int getOldState() int getNewState() |
For WINDOW_STATE_CHANGED events, these methods return the previous or new state of the window as a bitwise mask. |
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. |