001 /* ActionEvent.java -- an action has been triggered 002 Copyright (C) 1999, 2002, 2005 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 039 package java.awt.event; 040 041 import java.awt.AWTEvent; 042 import java.awt.EventQueue; 043 044 /** 045 * This event is generated when an action on a component (such as a 046 * button press) occurs. 047 * 048 * @author Aaron M. Renn (arenn@urbanophile.com) 049 * @see ActionListener 050 * @since 1.1 051 * @status updated to 1.4 052 */ 053 public class ActionEvent extends AWTEvent 054 { 055 /** 056 * Compatible with JDK 1.1+. 057 */ 058 private static final long serialVersionUID = -7671078796273832149L; 059 060 /** Bit mask indicating the shift key was pressed. */ 061 public static final int SHIFT_MASK = InputEvent.SHIFT_MASK; 062 063 /** Bit mask indicating the control key was pressed. */ 064 public static final int CTRL_MASK = InputEvent.CTRL_MASK; 065 066 /** Bit mask indicating the that meta key was pressed. */ 067 public static final int META_MASK = InputEvent.META_MASK; 068 069 /** Bit mask indicating that the alt key was pressed. */ 070 public static final int ALT_MASK = InputEvent.ALT_MASK; 071 072 /** The first id number in the range of action id's. */ 073 public static final int ACTION_FIRST = 1001; 074 075 /** The last id number in the range of action id's. */ 076 public static final int ACTION_LAST = 1001; 077 078 /** An event id indicating that an action has occurred. */ 079 public static final int ACTION_PERFORMED = 1001; 080 081 /** 082 * A nonlocalized string that gives more specific details of the event cause. 083 * 084 * @see #getActionCommand() 085 * @serial the command for this event 086 */ 087 private final String actionCommand; 088 089 /** 090 * The bitmask of the modifiers that were pressed during the action. 091 * 092 * @see #getModifiers() 093 * @serial modifiers for this event 094 */ 095 private final int modifiers; 096 097 /** 098 * The timestamp of this event; usually the same as the underlying input 099 * event. 100 * 101 * @see #getWhen() 102 * @serial the timestamp of the event 103 * @since 1.4 104 */ 105 private final long when; 106 107 /** 108 * Initializes a new instance of <code>ActionEvent</code> with the 109 * specified source, id, and command. Note that an invalid id leads to 110 * unspecified results. 111 * 112 * @param source the event source 113 * @param id the event id 114 * @param command the command string for this action 115 * @throws IllegalArgumentException if source is null 116 */ 117 public ActionEvent(Object source, int id, String command) 118 { 119 this(source, id, command, EventQueue.getMostRecentEventTime(), 0); 120 } 121 122 /** 123 * Initializes a new instance of <code>ActionEvent</code> with the 124 * specified source, id, command, and modifiers. Note that an invalid id 125 * leads to unspecified results. 126 * 127 * @param source the event source 128 * @param id the event id 129 * @param command the command string for this action 130 * @param modifiers the bitwise or of modifier keys down during the action 131 * @throws IllegalArgumentException if source is null 132 */ 133 public ActionEvent(Object source, int id, String command, int modifiers) 134 { 135 this(source, id, command, EventQueue.getMostRecentEventTime(), modifiers); 136 } 137 138 /** 139 * Initializes a new instance of <code>ActionEvent</code> with the 140 * specified source, id, command, and modifiers, and timestamp. Note that 141 * an invalid id leads to unspecified results. 142 * 143 * @param source the event source 144 * @param id the event id 145 * @param command the command string for this action 146 * @param when the timestamp of the event 147 * @param modifiers the bitwise or of modifier keys down during the action 148 * @throws IllegalArgumentException if source is null 149 * @since 1.4 150 */ 151 public ActionEvent(Object source, int id, String command, long when, 152 int modifiers) 153 { 154 super(source, id); 155 actionCommand = command; 156 this.when = when; 157 this.modifiers = modifiers; 158 } 159 160 /** 161 * Returns the command string associated with this action. 162 * 163 * @return the command string associated with this action 164 */ 165 public String getActionCommand() 166 { 167 return actionCommand; 168 } 169 170 /** 171 * Gets the timestamp of when this action took place. Usually, this 172 * corresponds to the timestamp of the underlying InputEvent. 173 * 174 * @return the timestamp of this action 175 * @since 1.4 176 */ 177 public long getWhen() 178 { 179 return when; 180 } 181 182 /** 183 * Returns the keys held down during the action. This value will be a 184 * combination of the bit mask constants defined in this class, or 0 if no 185 * modifiers were pressed. 186 * 187 * @return the modifier bits 188 */ 189 public int getModifiers() 190 { 191 return modifiers; 192 } 193 194 /** 195 * Returns a string that identifies the action event. This is in the format 196 * <code>"ACTION_PERFORMED,cmd=" + getActionCommand() + ",when=" + getWhen() 197 * + ",modifiers=" + <modifier string></code>, where the modifier 198 * string is in the order "Meta", "Ctrl", "Alt", "Shift", "Alt Graph", and 199 * "Button1", separated by '+', according to the bits set in getModifiers(). 200 * 201 * @return a string identifying the event 202 */ 203 public String paramString() 204 { 205 StringBuffer s = new StringBuffer(id == ACTION_PERFORMED 206 ? "ACTION_PERFORMED,cmd=" 207 : "unknown type,cmd="); 208 s.append(actionCommand).append(",when=").append(when).append(",modifiers"); 209 int len = s.length(); 210 s.setLength(len + 1); 211 if ((modifiers & META_MASK) != 0) 212 s.append("+Meta"); 213 if ((modifiers & CTRL_MASK) != 0) 214 s.append("+Ctrl"); 215 if ((modifiers & ALT_MASK) != 0) 216 s.append("+Alt"); 217 if ((modifiers & SHIFT_MASK) != 0) 218 s.append("+Shift"); 219 if ((modifiers & InputEvent.ALT_GRAPH_MASK) != 0) 220 s.append("+Alt Graph"); 221 if ((modifiers & InputEvent.BUTTON1_MASK) != 0) 222 s.append("+Button1"); 223 s.setCharAt(len, '='); 224 return s.toString(); 225 } 226 } // class ActionEvent