1 /* InputEvent.java -- common superclass of component input events 2 Copyright (C) 1999, 2002 Free Software Foundation, Inc. 3 4 This file is part of GNU Classpath. 5 6 GNU Classpath is free software; you can redistribute it and/or modify 7 it under the terms of the GNU General Public License as published by 8 the Free Software Foundation; either version 2, or (at your option) 9 any later version. 10 11 GNU Classpath is distributed in the hope that it will be useful, but 12 WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 General Public License for more details. 15 16 You should have received a copy of the GNU General Public License 17 along with GNU Classpath; see the file COPYING. If not, write to the 18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 19 02111-1307 USA. 20 21 Linking this library statically or dynamically with other modules is 22 making a combined work based on this library. Thus, the terms and 23 conditions of the GNU General Public License cover the whole 24 combination. 25 26 As a special exception, the copyright holders of this library give you 27 permission to link this library with independent modules to produce an 28 executable, regardless of the license terms of these independent 29 modules, and to copy and distribute the resulting executable under 30 terms of your choice, provided that you also meet, for each linked 31 independent module, the terms and conditions of the license of that 32 module. An independent module is a module which is not derived from 33 or based on this library. If you modify this library, you may extend 34 this exception to your version of the library, but you are not 35 obligated to do so. If you do not wish to do so, delete this 36 exception statement from your version. */ 37 38 39 package java.awt.event; 40 41 import java.awt.Component; 42 import gnu.java.awt.EventModifier; 43 44 /** 45 * This is the common superclass for all component input classes. These are 46 * passed to listeners before the component, so that listeners can consume 47 * the event before it does its default behavior. 48 * 49 * @author Aaron M. Renn <arenn@urbanophile.com> 50 * @see KeyEvent 51 * @see KeyAdapter 52 * @see MouseEvent 53 * @see MouseAdapter 54 * @see MouseMotionAdapter 55 * @see MouseWheelEvent 56 * @since 1.1 57 * @status updated to 1.4 58 */ 59 public abstract class InputEvent extends ComponentEvent 60 { 61 /** 62 * Compatible with JDK 1.1+. 63 */ 64 private static final long serialVersionUID = -2482525981698309786L; 65 66 /** 67 * This is the bit mask which indicates the shift key is down. It is 68 * recommended that SHIFT_DOWN_MASK be used instead. 69 * 70 * @see #SHIFT_DOWN_MASK 71 */ 72 public static final int SHIFT_MASK = 1; 73 74 /** 75 * This is the bit mask which indicates the control key is down. It is 76 * recommended that CTRL_DOWN_MASK be used instead. 77 * 78 * @see #CTRL_DOWN_MASK 79 */ 80 public static final int CTRL_MASK = 2; 81 82 /** 83 * This is the bit mask which indicates the meta key is down. It is 84 * recommended that META_DOWN_MASK be used instead. 85 * 86 * @see #META_DOWN_MASK 87 */ 88 public static final int META_MASK = 4; 89 90 /** 91 * This is the bit mask which indicates the alt key is down. It is 92 * recommended that ALT_DOWN_MASK be used instead. 93 * 94 * @see #ALT_DOWN_MASK 95 */ 96 public static final int ALT_MASK = 8; 97 98 /** 99 * This is the bit mask which indicates the alt-graph modifier is in effect. 100 * It is recommended that ALT_GRAPH_DOWN_MASK be used instead. 101 * 102 * @see #ALT_GRAPH_DOWN_MASK 103 */ 104 public static final int ALT_GRAPH_MASK = 0x20; 105 106 /** 107 * This bit mask indicates mouse button one is down. It is recommended that 108 * BUTTON1_DOWN_MASK be used instead. 109 * 110 * @see #BUTTON1_DOWN_MASK 111 */ 112 public static final int BUTTON1_MASK = 0x10; 113 114 /** 115 * This bit mask indicates mouse button two is down. It is recommended that 116 * BUTTON2_DOWN_MASK be used instead. 117 * 118 * @see #BUTTON2_DOWN_MASK 119 */ 120 public static final int BUTTON2_MASK = 8; 121 122 /** 123 * This bit mask indicates mouse button three is down. It is recommended 124 * that BUTTON3_DOWN_MASK be used instead. 125 * 126 * @see #BUTTON3_DOWN_MASK 127 */ 128 public static final int BUTTON3_MASK = 4; 129 130 /** 131 * The SHIFT key extended modifier. 132 * 133 * @since 1.4 134 */ 135 public static final int SHIFT_DOWN_MASK = 0x0040; 136 137 /** 138 * The CTRL key extended modifier. 139 * 140 * @since 1.4 141 */ 142 public static final int CTRL_DOWN_MASK = 0x0080; 143 144 /** 145 * The META key extended modifier. 146 * 147 * @since 1.4 148 */ 149 public static final int META_DOWN_MASK = 0x0100; 150 151 /** 152 * The ALT key extended modifier. 153 * 154 * @since 1.4 155 */ 156 public static final int ALT_DOWN_MASK = 0x0200; 157 158 /** 159 * The mouse button1 key extended modifier. 160 * 161 * @since 1.4 162 */ 163 public static final int BUTTON1_DOWN_MASK = 0x0400; 164 165 /** 166 * The mouse button2 extended modifier. 167 * 168 * @since 1.4 169 */ 170 public static final int BUTTON2_DOWN_MASK = 0x0800; 171 172 /** 173 * The mouse button3 extended modifier. 174 * 175 * @since 1.4 176 */ 177 public static final int BUTTON3_DOWN_MASK = 0x1000; 178 179 /** 180 * The ALT_GRAPH key extended modifier. 181 * 182 * @since 1.4 183 */ 184 public static final int ALT_GRAPH_DOWN_MASK = 0x2000; 185 186 /** The mask to convert new to old, package visible for use in subclasses. */ 187 static final int CONVERT_MASK 188 = EventModifier.NEW_MASK & ~(BUTTON2_DOWN_MASK | BUTTON3_DOWN_MASK); 189 190 /** 191 * The timestamp when this event occurred. 192 * 193 * @see #getWhen() 194 * @serial the timestamp 195 */ 196 private final long when; 197 198 /** 199 * The modifiers in effect for this event. Package visible for use by 200 * subclasses. The old style (bitmask 0x3f) should not be mixed with the 201 * new style (bitmasks 0xffffffc0). 202 * 203 * @see #getModifiers() 204 * @see MouseEvent 205 * @serial the modifier state, stored in the new style 206 */ 207 int modifiers; 208 209 /** 210 * Initializes a new instance of <code>InputEvent</code> with the specified 211 * source, id, timestamp, and modifiers. Note that an invalid id leads to 212 * unspecified results. 213 * 214 * @param source the source of the event 215 * @param id the event id 216 * @param when the timestamp when the event occurred 217 * @param modifiers the modifiers in effect for this event, old or new style 218 * @throws IllegalArgumentException if source is null 219 */ InputEvent(Component source, int id, long when, int modifiers)220 InputEvent(Component source, int id, long when, int modifiers) 221 { 222 super(source, id); 223 this.when = when; 224 this.modifiers = EventModifier.extend(modifiers); 225 } 226 227 /** 228 * This method tests whether or not the shift key was down during the event. 229 * 230 * @return true if the shift key is down 231 */ isShiftDown()232 public boolean isShiftDown() 233 { 234 return (modifiers & SHIFT_DOWN_MASK) != 0; 235 } 236 237 /** 238 * This method tests whether or not the control key was down during the 239 * event. 240 * 241 * @return true if the control key is down 242 */ isControlDown()243 public boolean isControlDown() 244 { 245 return (modifiers & CTRL_DOWN_MASK) != 0; 246 } 247 248 /** 249 * This method tests whether or not the meta key was down during the event. 250 * 251 * @return true if the meta key is down 252 */ isMetaDown()253 public boolean isMetaDown() 254 { 255 return (modifiers & META_DOWN_MASK) != 0; 256 } 257 258 /** 259 * This method tests whether or not the alt key was down during the event. 260 * 261 * @return true if the alt key is down 262 */ isAltDown()263 public boolean isAltDown() 264 { 265 return (modifiers & ALT_DOWN_MASK) != 0; 266 } 267 268 /** 269 * This method tests whether or not the alt-graph modifier was in effect 270 * during the event. 271 * 272 * @return true if the alt-graph modifier is down 273 */ isAltGraphDown()274 public boolean isAltGraphDown() 275 { 276 return (modifiers & ALT_GRAPH_DOWN_MASK) != 0; 277 } 278 279 /** 280 * This method returns the timestamp when this event occurred. 281 * 282 * @return the timestamp when this event occurred 283 */ getWhen()284 public long getWhen() 285 { 286 return when; 287 } 288 289 /** 290 * This method returns the old-style modifiers in effect for this event. 291 * Note that this is ambiguous between button2 and alt, and between 292 * button3 and meta. Also, code which generated these modifiers tends to 293 * only list the modifier that just changed, even if others were down at 294 * the time. Consider using getModifiersEx instead. This will be a union 295 * of the bit masks defined in this class that are applicable to the event. 296 * 297 * @return the modifiers in effect for this event 298 * @see #getModifiersEx() 299 */ getModifiers()300 public int getModifiers() 301 { 302 return EventModifier.revert(modifiers); 303 } 304 305 /** 306 * Returns the extended modifiers (new-style) for this event. This represents 307 * the state of all modal keys and mouse buttons at the time of the event, 308 * and does not suffer from the problems mentioned in getModifiers. 309 * 310 * <p>For an example of checking multiple modifiers, this code will return 311 * true only if SHIFT and BUTTON1 were pressed and CTRL was not: 312 * <pre> 313 * int onmask = InputEvent.SHIFT_DOWN_MASK | InputEvent.BUTTON1_DOWN_MASK; 314 * int offmask = InputEvent.CTRL_DOWN_MASK; 315 * return (event.getModifiersEx() & (onmask | offmask)) == onmask; 316 * </pre> 317 * 318 * @return the bitwise or of all modifiers pressed during the event 319 * @since 1.4 320 */ getModifiersEx()321 public int getModifiersEx() 322 { 323 return modifiers; 324 } 325 326 /** 327 * Consumes this event. A consumed event is not processed further by the AWT 328 * system. 329 */ consume()330 public void consume() 331 { 332 consumed = true; 333 } 334 335 /** 336 * This method tests whether or not this event has been consumed. 337 * 338 * @return true if this event has been consumed 339 */ isConsumed()340 public boolean isConsumed() 341 { 342 return consumed; 343 } 344 345 /** 346 * Convert the extended modifier bitmask into a String, such as "Shift" or 347 * "Ctrl+Button1". 348 * 349 * XXX Sun claims this can be localized via the awt.properties file - how 350 * do we implement that? 351 * 352 * @return a string representation of the modifiers in this bitmask 353 * @since 1.4 354 */ getModifiersExText(int modifiers)355 public static String getModifiersExText(int modifiers) 356 { 357 modifiers &= EventModifier.NEW_MASK; 358 if (modifiers == 0) 359 return ""; 360 StringBuffer s = new StringBuffer(); 361 if ((modifiers & META_DOWN_MASK) != 0) 362 s.append("Meta+"); 363 if ((modifiers & CTRL_DOWN_MASK) != 0) 364 s.append("Ctrl+"); 365 if ((modifiers & ALT_DOWN_MASK) != 0) 366 s.append("Alt+"); 367 if ((modifiers & SHIFT_DOWN_MASK) != 0) 368 s.append("Shift+"); 369 if ((modifiers & ALT_GRAPH_DOWN_MASK) != 0) 370 s.append("Alt Graph+"); 371 if ((modifiers & BUTTON1_DOWN_MASK) != 0) 372 s.append("Button1+"); 373 if ((modifiers & BUTTON2_DOWN_MASK) != 0) 374 s.append("Button2+"); 375 if ((modifiers & BUTTON3_DOWN_MASK) != 0) 376 s.append("Button3+"); 377 return s.substring(0, s.length() - 1); 378 } 379 } // class InputEvent 380