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

    1   /*
    2    * Copyright (c) 1996, 2010, 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.AWTEvent;
   29   import java.awt.Event;
   30   
   31   /**
   32    * A semantic event which indicates that a component-defined action occurred.
   33    * This high-level event is generated by a component (such as a
   34    * <code>Button</code>) when
   35    * the component-specific action occurs (such as being pressed).
   36    * The event is passed to every <code>ActionListener</code> object
   37    * that registered to receive such events using the component's
   38    * <code>addActionListener</code> method.
   39    * <p>
   40    * <b>Note:</b> To invoke an <code>ActionEvent</code> on a
   41    * <code>Button</code> using the keyboard, use the Space bar.
   42    * <P>
   43    * The object that implements the <code>ActionListener</code> interface
   44    * gets this <code>ActionEvent</code> when the event occurs. The listener
   45    * is therefore spared the details of processing individual mouse movements
   46    * and mouse clicks, and can instead process a "meaningful" (semantic)
   47    * event like "button pressed".
   48    * <p>
   49    * An unspecified behavior will be caused if the {@code id} parameter
   50    * of any particular {@code ActionEvent} instance is not
   51    * in the range from {@code ACTION_FIRST} to {@code ACTION_LAST}.
   52    *
   53    * @see ActionListener
   54    * @see <a href="http://java.sun.com/docs/books/tutorial/uiswing/events/actionlistener.html">Tutorial: How to Write an Action Listener</a>
   55    *
   56    * @author Carl Quinn
   57    * @since 1.1
   58    */
   59   public class ActionEvent extends AWTEvent {
   60   
   61       /**
   62        * The shift modifier. An indicator that the shift key was held
   63        * down during the event.
   64        */
   65       public static final int SHIFT_MASK          = Event.SHIFT_MASK;
   66   
   67       /**
   68        * The control modifier. An indicator that the control key was held
   69        * down during the event.
   70        */
   71       public static final int CTRL_MASK           = Event.CTRL_MASK;
   72   
   73       /**
   74        * The meta modifier. An indicator that the meta key was held
   75        * down during the event.
   76        */
   77       public static final int META_MASK           = Event.META_MASK;
   78   
   79       /**
   80        * The alt modifier. An indicator that the alt key was held
   81        * down during the event.
   82        */
   83       public static final int ALT_MASK            = Event.ALT_MASK;
   84   
   85   
   86       /**
   87        * The first number in the range of ids used for action events.
   88        */
   89       public static final int ACTION_FIRST                = 1001;
   90   
   91       /**
   92        * The last number in the range of ids used for action events.
   93        */
   94       public static final int ACTION_LAST                 = 1001;
   95   
   96       /**
   97        * This event id indicates that a meaningful action occured.
   98        */
   99       public static final int ACTION_PERFORMED    = ACTION_FIRST; //Event.ACTION_EVENT
  100   
  101       /**
  102        * The nonlocalized string that gives more details
  103        * of what actually caused the event.
  104        * This information is very specific to the component
  105        * that fired it.
  106   
  107        * @serial
  108        * @see #getActionCommand
  109        */
  110       String actionCommand;
  111   
  112       /**
  113        * Timestamp of when this event occurred. Because an ActionEvent is a high-
  114        * level, semantic event, the timestamp is typically the same as an
  115        * underlying InputEvent.
  116        *
  117        * @serial
  118        * @see #getWhen
  119        */
  120       long when;
  121   
  122       /**
  123        * This represents the key modifier that was selected,
  124        * and is used to determine the state of the selected key.
  125        * If no modifier has been selected it will default to
  126        * zero.
  127        *
  128        * @serial
  129        * @see #getModifiers
  130        */
  131       int modifiers;
  132   
  133       /*
  134        * JDK 1.1 serialVersionUID
  135        */
  136       private static final long serialVersionUID = -7671078796273832149L;
  137   
  138       /**
  139        * Constructs an <code>ActionEvent</code> object.
  140        * <p>
  141        * This method throws an
  142        * <code>IllegalArgumentException</code> if <code>source</code>
  143        * is <code>null</code>.
  144        * A <code>null</code> <code>command</code> string is legal,
  145        * but not recommended.
  146        *
  147        * @param source  The object that originated the event
  148        * @param id      An integer that identifies the event.
  149        *                     For information on allowable values, see
  150        *                     the class description for {@link ActionEvent}
  151        * @param command A string that may specify a command (possibly one
  152        *                of several) associated with the event
  153        * @throws IllegalArgumentException if <code>source</code> is null
  154        * @see #getSource()
  155        * @see #getID()
  156        * @see #getActionCommand()
  157        */
  158       public ActionEvent(Object source, int id, String command) {
  159           this(source, id, command, 0);
  160       }
  161   
  162       /**
  163        * Constructs an <code>ActionEvent</code> object with modifier keys.
  164        * <p>
  165        * This method throws an
  166        * <code>IllegalArgumentException</code> if <code>source</code>
  167        * is <code>null</code>.
  168        * A <code>null</code> <code>command</code> string is legal,
  169        * but not recommended.
  170        *
  171        * @param source  The object that originated the event
  172        * @param id      An integer that identifies the event.
  173        *                     For information on allowable values, see
  174        *                     the class description for {@link ActionEvent}
  175        * @param command A string that may specify a command (possibly one
  176        *                of several) associated with the event
  177        * @param modifiers The modifier keys down during event
  178        *                  (shift, ctrl, alt, meta).
  179        *                  Passing negative parameter is not recommended.
  180        *                  Zero value means that no modifiers were passed
  181        * @throws IllegalArgumentException if <code>source</code> is null
  182        * @see #getSource()
  183        * @see #getID()
  184        * @see #getActionCommand()
  185        * @see #getModifiers()
  186        */
  187       public ActionEvent(Object source, int id, String command, int modifiers) {
  188           this(source, id, command, 0, modifiers);
  189       }
  190   
  191       /**
  192        * Constructs an <code>ActionEvent</code> object with the specified
  193        * modifier keys and timestamp.
  194        * <p>
  195        * This method throws an
  196        * <code>IllegalArgumentException</code> if <code>source</code>
  197        * is <code>null</code>.
  198        * A <code>null</code> <code>command</code> string is legal,
  199        * but not recommended.
  200        *
  201        * @param source    The object that originated the event
  202        * @param id      An integer that identifies the event.
  203        *                     For information on allowable values, see
  204        *                     the class description for {@link ActionEvent}
  205        * @param command A string that may specify a command (possibly one
  206        *                of several) associated with the event
  207        * @param modifiers The modifier keys down during event
  208        *                  (shift, ctrl, alt, meta).
  209        *                  Passing negative parameter is not recommended.
  210        *                  Zero value means that no modifiers were passed
  211        * @param when   A long that gives the time the event occurred.
  212        *               Passing negative or zero value
  213        *               is not recommended
  214        * @throws IllegalArgumentException if <code>source</code> is null
  215        * @see #getSource()
  216        * @see #getID()
  217        * @see #getActionCommand()
  218        * @see #getModifiers()
  219        * @see #getWhen()
  220        *
  221        * @since 1.4
  222        */
  223       public ActionEvent(Object source, int id, String command, long when,
  224                          int modifiers) {
  225           super(source, id);
  226           this.actionCommand = command;
  227           this.when = when;
  228           this.modifiers = modifiers;
  229       }
  230   
  231       /**
  232        * Returns the command string associated with this action.
  233        * This string allows a "modal" component to specify one of several
  234        * commands, depending on its state. For example, a single button might
  235        * toggle between "show details" and "hide details". The source object
  236        * and the event would be the same in each case, but the command string
  237        * would identify the intended action.
  238        * <p>
  239        * Note that if a <code>null</code> command string was passed
  240        * to the constructor for this <code>ActionEvent</code>, this
  241        * this method returns <code>null</code>.
  242        *
  243        * @return the string identifying the command for this event
  244        */
  245       public String getActionCommand() {
  246           return actionCommand;
  247       }
  248   
  249       /**
  250        * Returns the timestamp of when this event occurred. Because an
  251        * ActionEvent is a high-level, semantic event, the timestamp is typically
  252        * the same as an underlying InputEvent.
  253        *
  254        * @return this event's timestamp
  255        * @since 1.4
  256        */
  257       public long getWhen() {
  258           return when;
  259       }
  260   
  261       /**
  262        * Returns the modifier keys held down during this action event.
  263        *
  264        * @return the bitwise-or of the modifier constants
  265        */
  266       public int getModifiers() {
  267           return modifiers;
  268       }
  269   
  270       /**
  271        * Returns a parameter string identifying this action event.
  272        * This method is useful for event-logging and for debugging.
  273        *
  274        * @return a string identifying the event and its associated command
  275        */
  276       public String paramString() {
  277           String typeStr;
  278           switch(id) {
  279             case ACTION_PERFORMED:
  280                 typeStr = "ACTION_PERFORMED";
  281                 break;
  282             default:
  283                 typeStr = "unknown type";
  284           }
  285           return typeStr + ",cmd="+actionCommand+",when="+when+",modifiers="+
  286               KeyEvent.getKeyModifiersText(modifiers);
  287       }
  288   }

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