001/* InputEvent.java -- common superclass of component input events 002 Copyright (C) 1999, 2002, 2004, 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.awt.EventModifier; 042import gnu.java.lang.CPStringBuilder; 043 044import java.awt.Component; 045 046/** 047 * This is the common superclass for all component input classes. These are 048 * passed to listeners before the component, so that listeners can consume 049 * the event before it does its default behavior. 050 * 051 * @author Aaron M. Renn (arenn@urbanophile.com) 052 * @see KeyEvent 053 * @see KeyAdapter 054 * @see MouseEvent 055 * @see MouseAdapter 056 * @see MouseMotionAdapter 057 * @see MouseWheelEvent 058 * @since 1.1 059 * @status updated to 1.4 060 */ 061public abstract class InputEvent extends ComponentEvent 062{ 063 /** 064 * Compatible with JDK 1.1+. 065 */ 066 private static final long serialVersionUID = -2482525981698309786L; 067 068 /** 069 * This is the bit mask which indicates the shift key is down. It is 070 * recommended that SHIFT_DOWN_MASK be used instead. 071 * 072 * @see #SHIFT_DOWN_MASK 073 */ 074 public static final int SHIFT_MASK = 1; 075 076 /** 077 * This is the bit mask which indicates the control key is down. It is 078 * recommended that CTRL_DOWN_MASK be used instead. 079 * 080 * @see #CTRL_DOWN_MASK 081 */ 082 public static final int CTRL_MASK = 2; 083 084 /** 085 * This is the bit mask which indicates the meta key is down. It is 086 * recommended that META_DOWN_MASK be used instead. 087 * 088 * @see #META_DOWN_MASK 089 */ 090 public static final int META_MASK = 4; 091 092 /** 093 * This is the bit mask which indicates the alt key is down. It is 094 * recommended that ALT_DOWN_MASK be used instead. 095 * 096 * @see #ALT_DOWN_MASK 097 */ 098 public static final int ALT_MASK = 8; 099 100 /** 101 * This is the bit mask which indicates the alt-graph modifier is in effect. 102 * It is recommended that ALT_GRAPH_DOWN_MASK be used instead. 103 * 104 * @see #ALT_GRAPH_DOWN_MASK 105 */ 106 public static final int ALT_GRAPH_MASK = 0x20; 107 108 /** 109 * This bit mask indicates mouse button one is down. It is recommended that 110 * BUTTON1_DOWN_MASK be used instead. 111 * 112 * @see #BUTTON1_DOWN_MASK 113 */ 114 public static final int BUTTON1_MASK = 0x10; 115 116 /** 117 * This bit mask indicates mouse button two is down. It is recommended that 118 * BUTTON2_DOWN_MASK be used instead. 119 * 120 * @see #BUTTON2_DOWN_MASK 121 */ 122 public static final int BUTTON2_MASK = 8; 123 124 /** 125 * This bit mask indicates mouse button three is down. It is recommended 126 * that BUTTON3_DOWN_MASK be used instead. 127 * 128 * @see #BUTTON3_DOWN_MASK 129 */ 130 public static final int BUTTON3_MASK = 4; 131 132 /** 133 * The SHIFT key extended modifier. 134 * 135 * @since 1.4 136 */ 137 public static final int SHIFT_DOWN_MASK = 0x0040; 138 139 /** 140 * The CTRL key extended modifier. 141 * 142 * @since 1.4 143 */ 144 public static final int CTRL_DOWN_MASK = 0x0080; 145 146 /** 147 * The META key extended modifier. 148 * 149 * @since 1.4 150 */ 151 public static final int META_DOWN_MASK = 0x0100; 152 153 /** 154 * The ALT key extended modifier. 155 * 156 * @since 1.4 157 */ 158 public static final int ALT_DOWN_MASK = 0x0200; 159 160 /** 161 * The mouse button1 key extended modifier. 162 * 163 * @since 1.4 164 */ 165 public static final int BUTTON1_DOWN_MASK = 0x0400; 166 167 /** 168 * The mouse button2 extended modifier. 169 * 170 * @since 1.4 171 */ 172 public static final int BUTTON2_DOWN_MASK = 0x0800; 173 174 /** 175 * The mouse button3 extended modifier. 176 * 177 * @since 1.4 178 */ 179 public static final int BUTTON3_DOWN_MASK = 0x1000; 180 181 /** 182 * The ALT_GRAPH key extended modifier. 183 * 184 * @since 1.4 185 */ 186 public static final int ALT_GRAPH_DOWN_MASK = 0x2000; 187 188 /** The mask to convert new to old, package visible for use in subclasses. */ 189 static final int CONVERT_MASK 190 = EventModifier.NEW_MASK & ~(BUTTON2_DOWN_MASK | BUTTON3_DOWN_MASK); 191 192 /** 193 * The timestamp when this event occurred. 194 * 195 * @see #getWhen() 196 * @serial the timestamp 197 */ 198 private final long when; 199 200 /** 201 * The old-style modifiers in effect for this event. Package visible 202 * for use by subclasses. The old style (bitmask 0x3f) should not be 203 * mixed with the new style (bitmasks 0xffffffc0). 204 * 205 * @see #getModifiers() 206 * @see MouseEvent 207 * @serial the modifier state, stored in the old style 208 */ 209 int modifiers; 210 211 /** 212 * The new-style modifiers in effect for this event. Package visible 213 * for use by subclasses. The old style (bitmask 0x3f) should not be 214 * mixed with the new style (bitmasks 0xffffffc0). 215 * 216 * @see #getModifiersEx() 217 * @see MouseEvent 218 * @serial the modifier state, stored in the new style 219 */ 220 int modifiersEx; 221 222 /** 223 * Initializes a new instance of <code>InputEvent</code> with the specified 224 * source, id, timestamp, and modifiers. Note that an invalid id leads to 225 * unspecified results. 226 * 227 * @param source the source of the event 228 * @param id the event id 229 * @param when the timestamp when the event occurred 230 * @param modifiers the modifiers in effect for this event, old or new style 231 * @throws IllegalArgumentException if source is null 232 */ 233 InputEvent(Component source, int id, long when, int modifiers) 234 { 235 super(source, id); 236 this.when = when; 237 this.modifiers = modifiers & EventModifier.OLD_MASK; 238 this.modifiersEx = modifiers & EventModifier.NEW_MASK; 239 } 240 241 /** 242 * This method tests whether or not the shift key was down during the event. 243 * 244 * @return true if the shift key is down 245 */ 246 public boolean isShiftDown() 247 { 248 return ((modifiers & SHIFT_MASK) != 0) 249 || ((modifiersEx & SHIFT_DOWN_MASK) != 0); 250 } 251 252 /** 253 * This method tests whether or not the control key was down during the 254 * event. 255 * 256 * @return true if the control key is down 257 */ 258 public boolean isControlDown() 259 { 260 return ((modifiers & CTRL_MASK) != 0) 261 || ((modifiersEx & CTRL_DOWN_MASK) != 0); 262 } 263 264 /** 265 * This method tests whether or not the meta key was down during the event. 266 * 267 * @return true if the meta key is down 268 */ 269 public boolean isMetaDown() 270 { 271 return ((modifiers & META_MASK) != 0) 272 || ((modifiersEx & META_DOWN_MASK) != 0); 273 } 274 275 /** 276 * This method tests whether or not the alt key was down during the event. 277 * 278 * @return true if the alt key is down 279 */ 280 public boolean isAltDown() 281 { 282 return ((modifiers & ALT_MASK) != 0) 283 || ((modifiersEx & ALT_DOWN_MASK) != 0); 284 } 285 286 /** 287 * This method tests whether or not the alt-graph modifier was in effect 288 * during the event. 289 * 290 * @return true if the alt-graph modifier is down 291 */ 292 public boolean isAltGraphDown() 293 { 294 return ((modifiers & ALT_GRAPH_MASK) != 0) 295 || ((modifiersEx & ALT_GRAPH_DOWN_MASK) != 0); 296 } 297 298 /** 299 * This method returns the timestamp when this event occurred. 300 * 301 * @return the timestamp when this event occurred 302 */ 303 public long getWhen() 304 { 305 return when; 306 } 307 308 /** 309 * This method returns the old-style modifiers in effect for this event. 310 * Note that this is ambiguous between button2 and alt, and between 311 * button3 and meta. Also, code which generated these modifiers tends to 312 * only list the modifier that just changed, even if others were down at 313 * the time. Consider using getModifiersEx instead. This will be a union 314 * of the bit masks defined in this class that are applicable to the event. 315 * 316 * @return the modifiers in effect for this event 317 * @see #getModifiersEx() 318 */ 319 public int getModifiers() 320 { 321 return modifiers; 322 } 323 324 /** 325 * Returns the extended modifiers (new-style) for this event. This represents 326 * the state of all modal keys and mouse buttons at the time of the event, 327 * and does not suffer from the problems mentioned in getModifiers. 328 * 329 * <p>For an example of checking multiple modifiers, this code will return 330 * true only if SHIFT and BUTTON1 were pressed and CTRL was not: 331 * <pre> 332 * int onmask = InputEvent.SHIFT_DOWN_MASK | InputEvent.BUTTON1_DOWN_MASK; 333 * int offmask = InputEvent.CTRL_DOWN_MASK; 334 * return (event.getModifiersEx() & (onmask | offmask)) == onmask; 335 * </pre> 336 * 337 * @return the bitwise or of all modifiers pressed during the event 338 * @since 1.4 339 */ 340 public int getModifiersEx() 341 { 342 return modifiersEx; 343 } 344 345 /** 346 * Consumes this event. A consumed event is not processed further by the AWT 347 * system. 348 */ 349 public void consume() 350 { 351 consumed = true; 352 } 353 354 /** 355 * This method tests whether or not this event has been consumed. 356 * 357 * @return true if this event has been consumed 358 */ 359 public boolean isConsumed() 360 { 361 return consumed; 362 } 363 364 /** 365 * Convert the extended modifier bitmask into a String, such as "Shift" or 366 * "Ctrl+Button1". 367 * 368 * XXX Sun claims this can be localized via the awt.properties file - how 369 * do we implement that? 370 * 371 * @param modifiers the modifiers 372 * @return a string representation of the modifiers in this bitmask 373 * @since 1.4 374 */ 375 public static String getModifiersExText(int modifiers) 376 { 377 modifiers &= EventModifier.NEW_MASK; 378 if (modifiers == 0) 379 return ""; 380 CPStringBuilder s = new CPStringBuilder(); 381 if ((modifiers & META_DOWN_MASK) != 0) 382 s.append("Meta+"); 383 if ((modifiers & CTRL_DOWN_MASK) != 0) 384 s.append("Ctrl+"); 385 if ((modifiers & ALT_DOWN_MASK) != 0) 386 s.append("Alt+"); 387 if ((modifiers & SHIFT_DOWN_MASK) != 0) 388 s.append("Shift+"); 389 if ((modifiers & ALT_GRAPH_DOWN_MASK) != 0) 390 s.append("Alt Graph+"); 391 if ((modifiers & BUTTON1_DOWN_MASK) != 0) 392 s.append("Button1+"); 393 if ((modifiers & BUTTON2_DOWN_MASK) != 0) 394 s.append("Button2+"); 395 if ((modifiers & BUTTON3_DOWN_MASK) != 0) 396 s.append("Button3+"); 397 return s.substring(0, s.length() - 1); 398 } 399} // class InputEvent