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