Home » openjdk-7 » java » awt » event » [javadoc | source]

    1   /*
    2    * Copyright (c) 1996, 2008, 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 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   }

Home » openjdk-7 » java » awt » event » [javadoc | source]