Source for java.awt.event.WindowEvent

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