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