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://java.sun.com/docs/books/tutorial/post1.0/ui/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
83 * the window has been closed as the result of a call to dispose.
84 */
85 @Native public static final int WINDOW_CLOSED = 2 + WINDOW_FIRST;
86
87 /**
88 * The window iconified event. This event is delivered when
89 * the window has been changed from a normal to a minimized state.
90 * For many platforms, a minimized window is displayed as
91 * the icon specified in the window's iconImage property.
92 * @see java.awt.Frame#setIconImage
93 */
94 @Native public static final int WINDOW_ICONIFIED = 3 + WINDOW_FIRST; //Event.WINDOW_ICONIFY
95
96 /**
97 * The window deiconified event type. This event is delivered when
98 * the window has been changed from a minimized to a normal state.
99 */
100 @Native public static final int WINDOW_DEICONIFIED = 4 + WINDOW_FIRST; //Event.WINDOW_DEICONIFY
101
102 /**
103 * The window-activated event type. This event is delivered when the Window
104 * becomes the active Window. Only a Frame or a Dialog can be the active
105 * Window. The native windowing system may denote the active Window or its
106 * children with special decorations, such as a highlighted title bar. The
107 * active Window is always either the focused Window, or the first Frame or
108 * Dialog that is an owner of the focused Window.
109 */
110 @Native public static final int WINDOW_ACTIVATED = 5 + WINDOW_FIRST;
111
112 /**
113 * The window-deactivated event type. This event is delivered when the
114 * Window is no longer the active Window. Only a Frame or a Dialog can be
115 * the active Window. The native windowing system may denote the active
116 * Window or its children with special decorations, such as a highlighted
117 * title bar. The active Window is always either the focused Window, or the
118 * first Frame or Dialog that is an owner of the focused Window.
119 */
120 @Native public static final int WINDOW_DEACTIVATED = 6 + WINDOW_FIRST;
121
122 /**
123 * The window-gained-focus event type. This event is delivered when the
124 * Window becomes the focused Window, which means that the Window, or one
125 * of its subcomponents, will receive keyboard events.
126 */
127 @Native public static final int WINDOW_GAINED_FOCUS = 7 + WINDOW_FIRST;
128
129 /**
130 * The window-lost-focus event type. This event is delivered when a Window
131 * is no longer the focused Window, which means keyboard events will no
132 * longer be delivered to the Window or any of its subcomponents.
133 */
134 @Native public static final int WINDOW_LOST_FOCUS = 8 + WINDOW_FIRST;
135
136 /**
137 * The window-state-changed event type. This event is delivered
138 * when a Window's state is changed by virtue of it being
139 * iconified, maximized etc.
140 * @since 1.4
141 */
142 @Native public static final int WINDOW_STATE_CHANGED = 9 + WINDOW_FIRST;
143
144 /**
145 * The last number in the range of ids used for window events.
146 */
147 public static final int WINDOW_LAST = WINDOW_STATE_CHANGED;
148
149 /**
150 * The other Window involved in this focus or activation change. For a
151 * WINDOW_ACTIVATED or WINDOW_GAINED_FOCUS event, this is the Window that
152 * lost activation or focus. For a WINDOW_DEACTIVATED or WINDOW_LOST_FOCUS
153 * event, this is the Window that gained activation or focus. For any other
154 * type of WindowEvent, or if the focus or activation change occurs with a
155 * native application, a Java application in a different VM, or with no
156 * other Window, null is returned.
157 *
158 * @see #getOppositeWindow
159 * @since 1.4
160 */
161 transient Window opposite;
162
163 /**
164 * TBS
165 */
166 int oldState;
167 int newState;
168
169
170 /*
171 * JDK 1.1 serialVersionUID
172 */
173 private static final long serialVersionUID = -1567959133147912127L;
174
175
176 /**
177 * Constructs a <code>WindowEvent</code> object.
178 * <p>This method throws an
179 * <code>IllegalArgumentException</code> if <code>source</code>
180 * is <code>null</code>.
181 *
182 * @param source The <code>Window</code> object
183 * that originated the event
184 * @param id An integer indicating the type of event.
185 * For information on allowable values, see
186 * the class description for {@link WindowEvent}
187 * @param opposite The other window involved in the focus or activation
188 * change, or <code>null</code>
189 * @param oldState Previous state of the window for window state change event.
190 * See {@code #getOldState()} for allowable values
191 * @param newState New state of the window for window state change event.
192 * See {@code #getNewState()} for allowable values
193 * @throws IllegalArgumentException if <code>source</code> is null
194 * @see #getWindow()
195 * @see #getID()
196 * @see #getOppositeWindow()
197 * @see #getOldState()
198 * @see #getNewState()
199 * @since 1.4
200 */
201 public WindowEvent(Window source, int id, Window opposite,
202 int oldState, int newState)
203 {
204 super(source, id);
205 this.opposite = opposite;
206 this.oldState = oldState;
207 this.newState = newState;
208 }
209
210 /**
211 * Constructs a <code>WindowEvent</code> object with the
212 * specified opposite <code>Window</code>. The opposite
213 * <code>Window</code> is the other <code>Window</code>
214 * involved in this focus or activation change.
215 * For a <code>WINDOW_ACTIVATED</code> or
216 * <code>WINDOW_GAINED_FOCUS</code> event, this is the
217 * <code>Window</code> that lost activation or focus.
218 * For a <code>WINDOW_DEACTIVATED</code> or
219 * <code>WINDOW_LOST_FOCUS</code> event, this is the
220 * <code>Window</code> that gained activation or focus.
221 * If this focus change occurs with a native application, with a
222 * Java application in a different VM, or with no other
223 * <code>Window</code>, then the opposite Window is <code>null</code>.
224 * <p>This method throws an
225 * <code>IllegalArgumentException</code> if <code>source</code>
226 * is <code>null</code>.
227 *
228 * @param source The <code>Window</code> object that
229 * originated the event
230 * @param id An integer indicating the type of event.
231 * For information on allowable values, see
232 * the class description for {@link WindowEvent}.
233 * It is expected that this constructor will not
234 * be used for other then
235 * {@code WINDOW_ACTIVATED},{@code WINDOW_DEACTIVATED},
236 * {@code WINDOW_GAINED_FOCUS}, or {@code WINDOW_LOST_FOCUS}.
237 * {@code WindowEvent} types,
238 * because the opposite <code>Window</code> of other event types
239 * will always be {@code null}.
240 * @param opposite The other <code>Window</code> involved in the
241 * focus or activation change, or <code>null</code>
242 * @throws IllegalArgumentException if <code>source</code> is null
243 * @see #getWindow()
244 * @see #getID()
245 * @see #getOppositeWindow()
246 * @since 1.4
247 */
248 public WindowEvent(Window source, int id, Window opposite) {
249 this(source, id, opposite, 0, 0);
250 }
251
252 /**
253 * Constructs a <code>WindowEvent</code> object with the specified
254 * previous and new window states.
255 * <p>This method throws an
256 * <code>IllegalArgumentException</code> if <code>source</code>
257 * is <code>null</code>.
258 *
259 * @param source The <code>Window</code> object
260 * that originated the event
261 * @param id An integer indicating the type of event.
262 * For information on allowable values, see
263 * the class description for {@link WindowEvent}.
264 * It is expected that this constructor will not
265 * be used for other then
266 * {@code WINDOW_STATE_CHANGED}
267 * {@code WindowEvent}
268 * types, because the previous and new window
269 * states are meaningless for other event types.
270 * @param oldState An integer representing the previous window state.
271 * See {@code #getOldState()} for allowable values
272 * @param newState An integer representing the new window state.
273 * See {@code #getNewState()} for allowable values
274 * @throws IllegalArgumentException if <code>source</code> is null
275 * @see #getWindow()
276 * @see #getID()
277 * @see #getOldState()
278 * @see #getNewState()
279 * @since 1.4
280 */
281 public WindowEvent(Window source, int id, int oldState, int newState) {
282 this(source, id, null, oldState, newState);
283 }
284
285 /**
286 * Constructs a <code>WindowEvent</code> object.
287 * <p>This method throws an
288 * <code>IllegalArgumentException</code> if <code>source</code>
289 * is <code>null</code>.
290 *
291 * @param source The <code>Window</code> object that originated the event
292 * @param id An integer indicating the type of event.
293 * For information on allowable values, see
294 * the class description for {@link WindowEvent}.
295 * @throws IllegalArgumentException if <code>source</code> is null
296 * @see #getWindow()
297 * @see #getID()
298 */
299 public WindowEvent(Window source, int id) {
300 this(source, id, null, 0, 0);
301 }
302
303 /**
304 * Returns the originator of the event.
305 *
306 * @return the Window object that originated the event
307 */
308 public Window getWindow() {
309 return (source instanceof Window) ? (Window)source : null;
310 }
311
312 /**
313 * Returns the other Window involved in this focus or activation change.
314 * For a WINDOW_ACTIVATED or WINDOW_GAINED_FOCUS event, this is the Window
315 * that lost activation or focus. For a WINDOW_DEACTIVATED or
316 * WINDOW_LOST_FOCUS event, this is the Window that gained activation or
317 * focus. For any other type of WindowEvent, or if the focus or activation
318 * change occurs with a native application, with a Java application in a
319 * different VM or context, or with no other Window, null is returned.
320 *
321 * @return the other Window involved in the focus or activation change, or
322 * null
323 * @since 1.4
324 */
325 public Window getOppositeWindow() {
326 if (opposite == null) {
327 return null;
328 }
329
330 return (SunToolkit.targetToAppContext(opposite) ==
331 AppContext.getAppContext())
332 ? opposite
333 : null;
334 }
335
336 /**
337 * For <code>WINDOW_STATE_CHANGED</code> events returns the
338 * previous state of the window. The state is
339 * represented as a bitwise mask.
340 * <ul>
341 * <li><code>NORMAL</code>
342 * <br>Indicates that no state bits are set.
343 * <li><code>ICONIFIED</code>
344 * <li><code>MAXIMIZED_HORIZ</code>
345 * <li><code>MAXIMIZED_VERT</code>
346 * <li><code>MAXIMIZED_BOTH</code>
347 * <br>Concatenates <code>MAXIMIZED_HORIZ</code>
348 * and <code>MAXIMIZED_VERT</code>.
349 * </ul>
350 *
351 * @return a bitwise mask of the previous window state
352 * @see java.awt.Frame#getExtendedState()
353 * @since 1.4
354 */
355 public int getOldState() {
356 return oldState;
357 }
358
359 /**
360 * For <code>WINDOW_STATE_CHANGED</code> events returns the
361 * new state of the window. The state is
362 * represented as a bitwise mask.
363 * <ul>
364 * <li><code>NORMAL</code>
365 * <br>Indicates that no state bits are set.
366 * <li><code>ICONIFIED</code>
367 * <li><code>MAXIMIZED_HORIZ</code>
368 * <li><code>MAXIMIZED_VERT</code>
369 * <li><code>MAXIMIZED_BOTH</code>
370 * <br>Concatenates <code>MAXIMIZED_HORIZ</code>
371 * and <code>MAXIMIZED_VERT</code>.
372 * </ul>
373 *
374 * @return a bitwise mask of the new window state
375 * @see java.awt.Frame#getExtendedState()
376 * @since 1.4
377 */
378 public int getNewState() {
379 return newState;
380 }
381
382 /**
383 * Returns a parameter string identifying this event.
384 * This method is useful for event-logging and for debugging.
385 *
386 * @return a string identifying the event and its attributes
387 */
388 public String paramString() {
389 String typeStr;
390 switch(id) {
391 case WINDOW_OPENED:
392 typeStr = "WINDOW_OPENED";
393 break;
394 case WINDOW_CLOSING:
395 typeStr = "WINDOW_CLOSING";
396 break;
397 case WINDOW_CLOSED:
398 typeStr = "WINDOW_CLOSED";
399 break;
400 case WINDOW_ICONIFIED:
401 typeStr = "WINDOW_ICONIFIED";
402 break;
403 case WINDOW_DEICONIFIED:
404 typeStr = "WINDOW_DEICONIFIED";
405 break;
406 case WINDOW_ACTIVATED:
407 typeStr = "WINDOW_ACTIVATED";
408 break;
409 case WINDOW_DEACTIVATED:
410 typeStr = "WINDOW_DEACTIVATED";
411 break;
412 case WINDOW_GAINED_FOCUS:
413 typeStr = "WINDOW_GAINED_FOCUS";
414 break;
415 case WINDOW_LOST_FOCUS:
416 typeStr = "WINDOW_LOST_FOCUS";
417 break;
418 case WINDOW_STATE_CHANGED:
419 typeStr = "WINDOW_STATE_CHANGED";
420 break;
421 default:
422 typeStr = "unknown type";
423 }
424 typeStr += ",opposite=" + getOppositeWindow()
425 + ",oldState=" + oldState + ",newState=" + newState;
426
427 return typeStr;
428 }
429 }