001 /*
002 * Copyright 1996-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt.event;
027
028 import java.awt.Window;
029 import sun.awt.AppContext;
030 import sun.awt.SunToolkit;
031
032 /**
033 * A low-level event that indicates that a window has changed its status. This
034 * low-level event is generated by a Window object when it is opened, closed,
035 * activated, deactivated, iconified, or deiconified, or when focus is
036 * transfered into or out of the Window.
037 * <P>
038 * The event is passed to every <code>WindowListener</code>
039 * or <code>WindowAdapter</code> object which registered to receive such
040 * events using the window's <code>addWindowListener</code> method.
041 * (<code>WindowAdapter</code> objects implement the
042 * <code>WindowListener</code> interface.) Each such listener object
043 * gets this <code>WindowEvent</code> when the event occurs.
044 *
045 * @author Carl Quinn
046 * @author Amy Fowler
047 * @version 1.45, 06/05/07
048 *
049 * @see WindowAdapter
050 * @see WindowListener
051 * @see <a href="http://java.sun.com/docs/books/tutorial/post1.0/ui/windowlistener.html">Tutorial: Writing a Window Listener</a>
052 *
053 * @since JDK1.1
054 */
055 public class WindowEvent extends ComponentEvent {
056
057 /**
058 * The first number in the range of ids used for window events.
059 */
060 public static final int WINDOW_FIRST = 200;
061
062 /**
063 * The window opened event. This event is delivered only
064 * the first time a window is made visible.
065 */
066 public static final int WINDOW_OPENED = WINDOW_FIRST; // 200
067
068 /**
069 * The "window is closing" event. This event is delivered when
070 * the user attempts to close the window from the window's system menu.
071 * If the program does not explicitly hide or dispose the window
072 * while processing this event, the window close operation will be
073 * cancelled.
074 */
075 public static final int WINDOW_CLOSING = 1 + WINDOW_FIRST; //Event.WINDOW_DESTROY
076
077 /**
078 * The window closed event. This event is delivered after
079 * the window has been closed as the result of a call to dispose.
080 */
081 public static final int WINDOW_CLOSED = 2 + WINDOW_FIRST;
082
083 /**
084 * The window iconified event. This event is delivered when
085 * the window has been changed from a normal to a minimized state.
086 * For many platforms, a minimized window is displayed as
087 * the icon specified in the window's iconImage property.
088 * @see java.awt.Frame#setIconImage
089 */
090 public static final int WINDOW_ICONIFIED = 3 + WINDOW_FIRST; //Event.WINDOW_ICONIFY
091
092 /**
093 * The window deiconified event type. This event is delivered when
094 * the window has been changed from a minimized to a normal state.
095 */
096 public static final int WINDOW_DEICONIFIED = 4 + WINDOW_FIRST; //Event.WINDOW_DEICONIFY
097
098 /**
099 * The window-activated event type. This event is delivered when the Window
100 * becomes the active Window. Only a Frame or a Dialog can be the active
101 * Window. The native windowing system may denote the active Window or its
102 * children with special decorations, such as a highlighted title bar. The
103 * active Window is always either the focused Window, or the first Frame or
104 * Dialog that is an owner of the focused Window.
105 */
106 public static final int WINDOW_ACTIVATED = 5 + WINDOW_FIRST;
107
108 /**
109 * The window-deactivated event type. This event is delivered when the
110 * Window is no longer the active Window. Only a Frame or a Dialog can be
111 * the active Window. The native windowing system may denote the active
112 * Window or its children with special decorations, such as a highlighted
113 * title bar. The active Window is always either the focused Window, or the
114 * first Frame or Dialog that is an owner of the focused Window.
115 */
116 public static final int WINDOW_DEACTIVATED = 6 + WINDOW_FIRST;
117
118 /**
119 * The window-gained-focus event type. This event is delivered when the
120 * Window becomes the focused Window, which means that the Window, or one
121 * of its subcomponents, will receive keyboard events.
122 */
123 public static final int WINDOW_GAINED_FOCUS = 7 + WINDOW_FIRST;
124
125 /**
126 * The window-lost-focus event type. This event is delivered when a Window
127 * is no longer the focused Window, which means keyboard events will no
128 * longer be delivered to the Window or any of its subcomponents.
129 */
130 public static final int WINDOW_LOST_FOCUS = 8 + WINDOW_FIRST;
131
132 /**
133 * The window-state-changed event type. This event is delivered
134 * when a Window's state is changed by virtue of it being
135 * iconified, maximized etc.
136 * @since 1.4
137 */
138 public static final int WINDOW_STATE_CHANGED = 9 + WINDOW_FIRST;
139
140 /**
141 * The last number in the range of ids used for window events.
142 */
143 public static final int WINDOW_LAST = WINDOW_STATE_CHANGED;
144
145 /**
146 * The other Window involved in this focus or activation change. For a
147 * WINDOW_ACTIVATED or WINDOW_GAINED_FOCUS event, this is the Window that
148 * lost activation or focus. For a WINDOW_DEACTIVATED or WINDOW_LOST_FOCUS
149 * event, this is the Window that gained activation or focus. For any other
150 * type of WindowEvent, or if the focus or activation change occurs with a
151 * native application, a Java application in a different VM, or with no
152 * other Window, null is returned.
153 *
154 * @see #getOppositeWindow
155 * @since 1.4
156 */
157 transient Window opposite;
158
159 /**
160 * TBS
161 */
162 int oldState;
163 int newState;
164
165 /*
166 * JDK 1.1 serialVersionUID
167 */
168 private static final long serialVersionUID = -1567959133147912127L;
169
170 /**
171 * Constructs a <code>WindowEvent</code> object.
172 * <p>Note that passing in an invalid <code>id</code> results in
173 * unspecified behavior. This method throws an
174 * <code>IllegalArgumentException</code> if <code>source</code>
175 * is <code>null</code>.
176 *
177 * @param source the <code>Window</code> object
178 * that originated the event
179 * @param id an integer indicating the type of event.
180 * @param opposite the other window involved in the focus or activation
181 * change, or <code>null</code>
182 * @param oldState previous state of the window for window state
183 * change event
184 * @param newState new state of the window for window state change event
185 * @throws IllegalArgumentException if <code>source</code> is null
186 * @since 1.4
187 */
188 public WindowEvent(Window source, int id, Window opposite,
189 int oldState, int newState) {
190 super (source, id);
191 this .opposite = opposite;
192 this .oldState = oldState;
193 this .newState = newState;
194 }
195
196 /**
197 * Constructs a <code>WindowEvent</code> object with the
198 * specified opposite <code>Window</code>. The opposite
199 * <code>Window</code> is the other <code>Window</code>
200 * involved in this focus or activation change.
201 * For a <code>WINDOW_ACTIVATED</code> or
202 * <code>WINDOW_GAINED_FOCUS</code> event, this is the
203 * <code>Window</code> that lost activation or focus.
204 * For a <code>WINDOW_DEACTIVATED</code> or
205 * <code>WINDOW_LOST_FOCUS</code> event, this is the
206 * <code>Window</code> that gained activation or focus.
207 * If this focus change occurs with a native application, with a
208 * Java application in a different VM, or with no other
209 * <code>Window</code>, then the opposite Window is <code>null</code>.
210 * <p>Note that passing in an invalid <code>id</code> results in
211 * unspecified behavior. This method throws an
212 * <code>IllegalArgumentException</code> if <code>source</code>
213 * is <code>null</code>.
214 *
215 * @param source the <code>Window</code> object that
216 * originated the event
217 * @param id <code>WINDOW_ACTIVATED</code>,
218 * <code>WINDOW_DEACTIVATED</code>,
219 * <code>WINDOW_GAINED_FOCUS</code>,
220 * or <code>WINDOW_LOST_FOCUS</code>. It is
221 * expected that this constructor will not be used for
222 * other <code>WindowEvent</code> types because the
223 * opposite <code>Window</code> of such events
224 * will always be <code>null</code>
225 * @param opposite the other <code>Window</code> involved in the
226 * focus or activation change, or <code>null</code>
227 * @throws IllegalArgumentException if <code>source</code> is null
228 * @since 1.4
229 */
230 public WindowEvent(Window source, int id, Window opposite) {
231 this (source, id, opposite, 0, 0);
232 }
233
234 /**
235 * Constructs a <code>WindowEvent</code> object with the specified
236 * previous and new window states.
237 * <p>Note that passing in an invalid <code>id</code> results in
238 * unspecified behavior. This method throws an
239 * <code>IllegalArgumentException</code> if <code>source</code>
240 * is <code>null</code>.
241 *
242 * @param source the <code>Window</code> object
243 * that originated the event
244 * @param id <code>WINDOW_STATE_CHANGED</code> event type.
245 * It is expected that this constructor will not
246 * be used for other <code>WindowEvent</code>
247 * types, because the previous and new window
248 * states are meaningless for other event types.
249 * @param oldState an integer representing the previous window state
250 * @param newState an integer representing the new window state
251 * @throws IllegalArgumentException if <code>source</code> is null
252 * @since 1.4
253 */
254 public WindowEvent(Window source, int id, int oldState, int newState) {
255 this (source, id, null, oldState, newState);
256 }
257
258 /**
259 * Constructs a <code>WindowEvent</code> object.
260 * <p>Note that passing in an invalid <code>id</code> results in
261 * unspecified behavior. This method throws an
262 * <code>IllegalArgumentException</code> if <code>source</code>
263 * is <code>null</code>.
264 *
265 * @param source the <code>Window</code> object that originated the event
266 * @param id an integer indicating the type of event
267 * @throws IllegalArgumentException if <code>source</code> is null
268 */
269 public WindowEvent(Window source, int id) {
270 this (source, id, null, 0, 0);
271 }
272
273 /**
274 * Returns the originator of the event.
275 *
276 * @return the Window object that originated the event
277 */
278 public Window getWindow() {
279 return (source instanceof Window) ? (Window) source : null;
280 }
281
282 /**
283 * Returns the other Window involved in this focus or activation change.
284 * For a WINDOW_ACTIVATED or WINDOW_GAINED_FOCUS event, this is the Window
285 * that lost activation or focus. For a WINDOW_DEACTIVATED or
286 * WINDOW_LOST_FOCUS event, this is the Window that gained activation or
287 * focus. For any other type of WindowEvent, or if the focus or activation
288 * change occurs with a native application, with a Java application in a
289 * different VM or context, or with no other Window, null is returned.
290 *
291 * @return the other Window involved in the focus or activation change, or
292 * null
293 * @since 1.4
294 */
295 public Window getOppositeWindow() {
296 if (opposite == null) {
297 return null;
298 }
299
300 return (SunToolkit.targetToAppContext(opposite) == AppContext
301 .getAppContext()) ? opposite : null;
302 }
303
304 /**
305 * For <code>WINDOW_STATE_CHANGED</code> events returns the
306 * previous state of the window. The state is
307 * represented as a bitwise mask.
308 * <ul>
309 * <li><code>NORMAL</code>
310 * <br>Indicates that no state bits are set.
311 * <li><code>ICONIFIED</code>
312 * <li><code>MAXIMIZED_HORIZ</code>
313 * <li><code>MAXIMIZED_VERT</code>
314 * <li><code>MAXIMIZED_BOTH</code>
315 * <br>Concatenates <code>MAXIMIZED_HORIZ</code>
316 * and <code>MAXIMIZED_VERT</code>.
317 * </ul>
318 *
319 * @return a bitwise mask of the previous window state
320 * @see java.awt.Frame#getExtendedState()
321 * @since 1.4
322 */
323 public int getOldState() {
324 return oldState;
325 }
326
327 /**
328 * For <code>WINDOW_STATE_CHANGED</code> events returns the
329 * new state of the window. The state is
330 * represented as a bitwise mask.
331 * <ul>
332 * <li><code>NORMAL</code>
333 * <br>Indicates that no state bits are set.
334 * <li><code>ICONIFIED</code>
335 * <li><code>MAXIMIZED_HORIZ</code>
336 * <li><code>MAXIMIZED_VERT</code>
337 * <li><code>MAXIMIZED_BOTH</code>
338 * <br>Concatenates <code>MAXIMIZED_HORIZ</code>
339 * and <code>MAXIMIZED_VERT</code>.
340 * </ul>
341 *
342 * @return a bitwise mask of the new window state
343 * @see java.awt.Frame#getExtendedState()
344 * @since 1.4
345 */
346 public int getNewState() {
347 return newState;
348 }
349
350 /**
351 * Returns a parameter string identifying this event.
352 * This method is useful for event-logging and for debugging.
353 *
354 * @return a string identifying the event and its attributes
355 */
356 public String paramString() {
357 String typeStr;
358 switch (id) {
359 case WINDOW_OPENED:
360 typeStr = "WINDOW_OPENED";
361 break;
362 case WINDOW_CLOSING:
363 typeStr = "WINDOW_CLOSING";
364 break;
365 case WINDOW_CLOSED:
366 typeStr = "WINDOW_CLOSED";
367 break;
368 case WINDOW_ICONIFIED:
369 typeStr = "WINDOW_ICONIFIED";
370 break;
371 case WINDOW_DEICONIFIED:
372 typeStr = "WINDOW_DEICONIFIED";
373 break;
374 case WINDOW_ACTIVATED:
375 typeStr = "WINDOW_ACTIVATED";
376 break;
377 case WINDOW_DEACTIVATED:
378 typeStr = "WINDOW_DEACTIVATED";
379 break;
380 case WINDOW_GAINED_FOCUS:
381 typeStr = "WINDOW_GAINED_FOCUS";
382 break;
383 case WINDOW_LOST_FOCUS:
384 typeStr = "WINDOW_LOST_FOCUS";
385 break;
386 case WINDOW_STATE_CHANGED:
387 typeStr = "WINDOW_STATE_CHANGED";
388 break;
389 default:
390 typeStr = "unknown type";
391 }
392 typeStr += ",opposite=" + getOppositeWindow() + ",oldState="
393 + oldState + ",newState=" + newState;
394
395 return typeStr;
396 }
397 }
|