1 /*
2 * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.awt.event;
27
28 import java.awt.Window;
29 import java.lang.annotation.Native;
30 import sun.awt.AppContext;
31 import sun.awt.SunToolkit;
32
33 /**
34 * A low-level event that indicates that a window has changed its status. This
35 * low-level event is generated by a Window object when it is opened, closed,
36 * activated, deactivated, iconified, or deiconified, or when focus is
37 * transfered into or out of the Window.
38 * <P>
39 * The event is passed to every <code>WindowListener</code>
40 * or <code>WindowAdapter</code> object which registered to receive such
41 * events using the window's <code>addWindowListener</code> method.
42 * (<code>WindowAdapter</code> objects implement the
43 * <code>WindowListener</code> interface.) Each such listener object
44 * gets this <code>WindowEvent</code> when the event occurs.
45 * <p>
46 * An unspecified behavior will be caused if the {@code id} parameter
47 * of any particular {@code WindowEvent} instance is not
48 * in the range from {@code WINDOW_FIRST} to {@code WINDOW_LAST}.
49 *
50 * @author Carl Quinn
51 * @author Amy Fowler
52 *
53 * @see WindowAdapter
54 * @see WindowListener
55 * @see <a href="http://docs.oracle.com/javase/tutorial/uiswing/events/windowlistener.html">Tutorial: Writing a Window Listener</a>
56 *
57 * @since JDK1.1
58 */
59 public class WindowEvent extends ComponentEvent {
60
61 /**
62 * The first number in the range of ids used for window events.
63 */
64 public static final int WINDOW_FIRST = 200;
65
66 /**
67 * The window opened event. This event is delivered only
68 * the first time a window is made visible.
69 */
70 @Native public static final int WINDOW_OPENED = WINDOW_FIRST; // 200
71
72 /**
73 * The "window is closing" event. This event is delivered when
74 * the user attempts to close the window from the window's system menu.
75 * If the program does not explicitly hide or dispose the window
76 * while processing this event, the window close operation will be
77 * cancelled.
78 */
79 @Native public static final int WINDOW_CLOSING = 1 + WINDOW_FIRST; //Event.WINDOW_DESTROY
80
81 /**
82 * The window closed event. This event is delivered after the displayable
83 * window has been closed as the result of a call to dispose.
84 * @see java.awt.Component#isDisplayable
85 * @see Window#dispose
86 */
87 @Native public static final int WINDOW_CLOSED = 2 + WINDOW_FIRST;
88
89 /**
90 * The window iconified event. This event is delivered when
91 * the window has been changed from a normal to a minimized state.
92 * For many platforms, a minimized window is displayed as
93 * the icon specified in the window's iconImage property.
94 * @see java.awt.Frame#setIconImage
95 */
96 @Native public static final int WINDOW_ICONIFIED = 3 + WINDOW_FIRST; //Event.WINDOW_ICONIFY
97
98 /**
99 * The window deiconified event type. This event is delivered when
100 * the window has been changed from a minimized to a normal state.
101 */
102 @Native public static final int WINDOW_DEICONIFIED = 4 + WINDOW_FIRST; //Event.WINDOW_DEICONIFY
103
104 /**
105 * The window-activated event type. This event is delivered when the Window
106 * becomes the active Window. Only a Frame or a Dialog can be the active
107 * Window. The native windowing system may denote the active Window or its
108 * children with special decorations, such as a highlighted title bar. The
109 * active Window is always either the focused Window, or the first Frame or
110 * Dialog that is an owner of the focused Window.
111 */
112 @Native public static final int WINDOW_ACTIVATED = 5 + WINDOW_FIRST;
113
114 /**
115 * The window-deactivated event type. This event is delivered when the
116 * Window is no longer the active Window. Only a Frame or a Dialog can be
117 * the active Window. The native windowing system may denote the active
118 * Window or its children with special decorations, such as a highlighted
119 * title bar. The active Window is always either the focused Window, or the
120 * first Frame or Dialog that is an owner of the focused Window.
121 */
122 @Native public static final int WINDOW_DEACTIVATED = 6 + WINDOW_FIRST;
123
124 /**
125 * The window-gained-focus event type. This event is delivered when the
126 * Window becomes the focused Window, which means that the Window, or one
127 * of its subcomponents, will receive keyboard events.
128 */
129 @Native public static final int WINDOW_GAINED_FOCUS = 7 + WINDOW_FIRST;
130
131 /**
132 * The window-lost-focus event type. This event is delivered when a Window
133 * is no longer the focused Window, which means keyboard events will no
134 * longer be delivered to the Window or any of its subcomponents.
135 */
136 @Native public static final int WINDOW_LOST_FOCUS = 8 + WINDOW_FIRST;
137
138 /**
139 * The window-state-changed event type. This event is delivered
140 * when a Window's state is changed by virtue of it being
141 * iconified, maximized etc.
142 * @since 1.4
143 */
144 @Native public static final int WINDOW_STATE_CHANGED = 9 + WINDOW_FIRST;
145
146 /**
147 * The last number in the range of ids used for window events.
148 */
149 public static final int WINDOW_LAST = WINDOW_STATE_CHANGED;
150
151 /**
152 * The other Window involved in this focus or activation change. For a
153 * WINDOW_ACTIVATED or WINDOW_GAINED_FOCUS event, this is the Window that
154 * lost activation or focus. For a WINDOW_DEACTIVATED or WINDOW_LOST_FOCUS
155 * event, this is the Window that gained activation or focus. For any other
156 * type of WindowEvent, or if the focus or activation change occurs with a
157 * native application, a Java application in a different VM, or with no
158 * other Window, null is returned.
159 *
160 * @see #getOppositeWindow
161 * @since 1.4
162 */
163 transient Window opposite;
164
165 /**
166 * TBS
167 */
168 int oldState;
169 int newState;
170
171
172 /*
173 * JDK 1.1 serialVersionUID
174 */
175 private static final long serialVersionUID = -1567959133147912127L;
176
177
178 /**
179 * Constructs a <code>WindowEvent</code> object.
180 * <p>This method throws an
181 * <code>IllegalArgumentException</code> if <code>source</code>
182 * is <code>null</code>.
183 *
184 * @param source The <code>Window</code> object
185 * that originated the event
186 * @param id An integer indicating the type of event.
187 * For information on allowable values, see
188 * the class description for {@link WindowEvent}
189 * @param opposite The other window involved in the focus or activation
190 * change, or <code>null</code>
191 * @param oldState Previous state of the window for window state change event.
192 * See {@code #getOldState()} for allowable values
193 * @param newState New state of the window for window state change event.
194 * See {@code #getNewState()} for allowable values
195 * @throws IllegalArgumentException if <code>source</code> is null
196 * @see #getWindow()
197 * @see #getID()
198 * @see #getOppositeWindow()
199 * @see #getOldState()
200 * @see #getNewState()
201 * @since 1.4
202 */
203 public WindowEvent(Window source, int id, Window opposite,
204 int oldState, int newState)
205 {
206 super(source, id);
207 this.opposite = opposite;
208 this.oldState = oldState;
209 this.newState = newState;
210 }
211
212 /**
213 * Constructs a <code>WindowEvent</code> object with the
214 * specified opposite <code>Window</code>. The opposite
215 * <code>Window</code> is the other <code>Window</code>
216 * involved in this focus or activation change.
217 * For a <code>WINDOW_ACTIVATED</code> or
218 * <code>WINDOW_GAINED_FOCUS</code> event, this is the
219 * <code>Window</code> that lost activation or focus.
220 * For a <code>WINDOW_DEACTIVATED</code> or
221 * <code>WINDOW_LOST_FOCUS</code> event, this is the
222 * <code>Window</code> that gained activation or focus.
223 * If this focus change occurs with a native application, with a
224 * Java application in a different VM, or with no other
225 * <code>Window</code>, then the opposite Window is <code>null</code>.
226 * <p>This method throws an
227 * <code>IllegalArgumentException</code> if <code>source</code>
228 * is <code>null</code>.
229 *
230 * @param source The <code>Window</code> object that
231 * originated the event
232 * @param id An integer indicating the type of event.
233 * For information on allowable values, see
234 * the class description for {@link WindowEvent}.
235 * It is expected that this constructor will not
236 * be used for other then
237 * {@code WINDOW_ACTIVATED},{@code WINDOW_DEACTIVATED},
238 * {@code WINDOW_GAINED_FOCUS}, or {@code WINDOW_LOST_FOCUS}.
239 * {@code WindowEvent} types,
240 * because the opposite <code>Window</code> of other event types
241 * will always be {@code null}.
242 * @param opposite The other <code>Window</code> involved in the
243 * focus or activation change, or <code>null</code>
244 * @throws IllegalArgumentException if <code>source</code> is null
245 * @see #getWindow()
246 * @see #getID()
247 * @see #getOppositeWindow()
248 * @since 1.4
249 */
250 public WindowEvent(Window source, int id, Window opposite) {
251 this(source, id, opposite, 0, 0);
252 }
253
254 /**
255 * Constructs a <code>WindowEvent</code> object with the specified
256 * previous and new window states.
257 * <p>This method throws an
258 * <code>IllegalArgumentException</code> if <code>source</code>
259 * is <code>null</code>.
260 *
261 * @param source The <code>Window</code> object
262 * that originated the event
263 * @param id An integer indicating the type of event.
264 * For information on allowable values, see
265 * the class description for {@link WindowEvent}.
266 * It is expected that this constructor will not
267 * be used for other then
268 * {@code WINDOW_STATE_CHANGED}
269 * {@code WindowEvent}
270 * types, because the previous and new window
271 * states are meaningless for other event types.
272 * @param oldState An integer representing the previous window state.
273 * See {@code #getOldState()} for allowable values
274 * @param newState An integer representing the new window state.
275 * See {@code #getNewState()} for allowable values
276 * @throws IllegalArgumentException if <code>source</code> is null
277 * @see #getWindow()
278 * @see #getID()
279 * @see #getOldState()
280 * @see #getNewState()
281 * @since 1.4
282 */
283 public WindowEvent(Window source, int id, int oldState, int newState) {
284 this(source, id, null, oldState, newState);
285 }
286
287 /**
288 * Constructs a <code>WindowEvent</code> object.
289 * <p>This method throws an
290 * <code>IllegalArgumentException</code> if <code>source</code>
291 * is <code>null</code>.
292 *
293 * @param source The <code>Window</code> object that originated the event
294 * @param id An integer indicating the type of event.
295 * For information on allowable values, see
296 * the class description for {@link WindowEvent}.
297 * @throws IllegalArgumentException if <code>source</code> is null
298 * @see #getWindow()
299 * @see #getID()
300 */
301 public WindowEvent(Window source, int id) {
302 this(source, id, null, 0, 0);
303 }
304
305 /**
306 * Returns the originator of the event.
307 *
308 * @return the Window object that originated the event
309 */
310 public Window getWindow() {
311 return (source instanceof Window) ? (Window)source : null;
312 }
313
314 /**
315 * Returns the other Window involved in this focus or activation change.
316 * For a WINDOW_ACTIVATED or WINDOW_GAINED_FOCUS event, this is the Window
317 * that lost activation or focus. For a WINDOW_DEACTIVATED or
318 * WINDOW_LOST_FOCUS event, this is the Window that gained activation or
319 * focus. For any other type of WindowEvent, or if the focus or activation
320 * change occurs with a native application, with a Java application in a
321 * different VM or context, or with no other Window, null is returned.
322 *
323 * @return the other Window involved in the focus or activation change, or
324 * null
325 * @since 1.4
326 */
327 public Window getOppositeWindow() {
328 if (opposite == null) {
329 return null;
330 }
331
332 return (SunToolkit.targetToAppContext(opposite) ==
333 AppContext.getAppContext())
334 ? opposite
335 : null;
336 }
337
338 /**
339 * For <code>WINDOW_STATE_CHANGED</code> events returns the
340 * previous state of the window. The state is
341 * represented as a bitwise mask.
342 * <ul>
343 * <li><code>NORMAL</code>
344 * <br>Indicates that no state bits are set.
345 * <li><code>ICONIFIED</code>
346 * <li><code>MAXIMIZED_HORIZ</code>
347 * <li><code>MAXIMIZED_VERT</code>
348 * <li><code>MAXIMIZED_BOTH</code>
349 * <br>Concatenates <code>MAXIMIZED_HORIZ</code>
350 * and <code>MAXIMIZED_VERT</code>.
351 * </ul>
352 *
353 * @return a bitwise mask of the previous window state
354 * @see java.awt.Frame#getExtendedState()
355 * @since 1.4
356 */
357 public int getOldState() {
358 return oldState;
359 }
360
361 /**
362 * For <code>WINDOW_STATE_CHANGED</code> events returns the
363 * new state of the window. The state is
364 * represented as a bitwise mask.
365 * <ul>
366 * <li><code>NORMAL</code>
367 * <br>Indicates that no state bits are set.
368 * <li><code>ICONIFIED</code>
369 * <li><code>MAXIMIZED_HORIZ</code>
370 * <li><code>MAXIMIZED_VERT</code>
371 * <li><code>MAXIMIZED_BOTH</code>
372 * <br>Concatenates <code>MAXIMIZED_HORIZ</code>
373 * and <code>MAXIMIZED_VERT</code>.
374 * </ul>
375 *
376 * @return a bitwise mask of the new window state
377 * @see java.awt.Frame#getExtendedState()
378 * @since 1.4
379 */
380 public int getNewState() {
381 return newState;
382 }
383
384 /**
385 * Returns a parameter string identifying this event.
386 * This method is useful for event-logging and for debugging.
387 *
388 * @return a string identifying the event and its attributes
389 */
390 public String paramString() {
391 String typeStr;
392 switch(id) {
393 case WINDOW_OPENED:
394 typeStr = "WINDOW_OPENED";
395 break;
396 case WINDOW_CLOSING:
397 typeStr = "WINDOW_CLOSING";
398 break;
399 case WINDOW_CLOSED:
400 typeStr = "WINDOW_CLOSED";
401 break;
402 case WINDOW_ICONIFIED:
403 typeStr = "WINDOW_ICONIFIED";
404 break;
405 case WINDOW_DEICONIFIED:
406 typeStr = "WINDOW_DEICONIFIED";
407 break;
408 case WINDOW_ACTIVATED:
409 typeStr = "WINDOW_ACTIVATED";
410 break;
411 case WINDOW_DEACTIVATED:
412 typeStr = "WINDOW_DEACTIVATED";
413 break;
414 case WINDOW_GAINED_FOCUS:
415 typeStr = "WINDOW_GAINED_FOCUS";
416 break;
417 case WINDOW_LOST_FOCUS:
418 typeStr = "WINDOW_LOST_FOCUS";
419 break;
420 case WINDOW_STATE_CHANGED:
421 typeStr = "WINDOW_STATE_CHANGED";
422 break;
423 default:
424 typeStr = "unknown type";
425 }
426 typeStr += ",opposite=" + getOppositeWindow()
427 + ",oldState=" + oldState + ",newState=" + newState;
428
429 return typeStr;
430 }
431 }