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