20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.awt.event;
27
28 import java.awt.Component;
29 import java.awt.GraphicsEnvironment;
30 import java.awt.Toolkit;
31 import java.io.IOException;
32 import java.io.ObjectInputStream;
33 import sun.awt.AWTAccessor;
34
35 /**
36 * An event which indicates that a keystroke occurred in a component.
37 * <p>
38 * This low-level event is generated by a component object (such as a text
39 * field) when a key is pressed, released, or typed.
40 * The event is passed to every <code>KeyListener</code>
41 * or <code>KeyAdapter</code> object which registered to receive such
42 * events using the component's <code>addKeyListener</code> method.
43 * (<code>KeyAdapter</code> objects implement the
44 * <code>KeyListener</code> interface.) Each such listener object
45 * gets this <code>KeyEvent</code> when the event occurs.
46 * <p>
47 * <em>"Key typed" events</em> are higher-level and generally do not depend on
48 * the platform or keyboard layout. They are generated when a Unicode character
49 * is entered, and are the preferred way to find out about character input.
50 * In the simplest case, a key typed event is produced by a single key press
51 * (e.g., 'a'). Often, however, characters are produced by series of key
52 * presses (e.g., 'shift' + 'a'), and the mapping from key pressed events to
53 * key typed events may be many-to-one or many-to-many. Key releases are not
54 * usually necessary to generate a key typed event, but there are some cases
55 * where the key typed event is not generated until a key is released (e.g.,
56 * entering ASCII sequences via the Alt-Numpad method in Windows).
57 * No key typed events are generated for keys that don't generate Unicode
58 * characters (e.g., action keys, modifier keys, etc.).
59 * <p>
60 * The getKeyChar method always returns a valid Unicode character or
61 * CHAR_UNDEFINED. Character input is reported by KEY_TYPED events:
62 * KEY_PRESSED and KEY_RELEASED events are not necessarily associated
63 * with character input. Therefore, the result of the getKeyChar method
64 * is guaranteed to be meaningful only for KEY_TYPED events.
65 * <p>
957 * @since 1.5
958 */
959 public static final int VK_BEGIN = 0xFF58;
960
961 /**
962 * This value is used to indicate that the keyCode is unknown.
963 * KEY_TYPED events do not have a keyCode value; this value
964 * is used instead.
965 */
966 public static final int VK_UNDEFINED = 0x0;
967
968 /**
969 * KEY_PRESSED and KEY_RELEASED events which do not map to a
970 * valid Unicode character use this for the keyChar value.
971 */
972 public static final char CHAR_UNDEFINED = 0xFFFF;
973
974 /**
975 * A constant indicating that the keyLocation is indeterminate
976 * or not relevant.
977 * <code>KEY_TYPED</code> events do not have a keyLocation; this value
978 * is used instead.
979 * @since 1.4
980 */
981 public static final int KEY_LOCATION_UNKNOWN = 0;
982
983 /**
984 * A constant indicating that the key pressed or released
985 * is not distinguished as the left or right version of a key,
986 * and did not originate on the numeric keypad (or did not
987 * originate with a virtual key corresponding to the numeric
988 * keypad).
989 * @since 1.4
990 */
991 public static final int KEY_LOCATION_STANDARD = 1;
992
993 /**
994 * A constant indicating that the key pressed or released is in
995 * the left key location (there is more than one possible location
996 * for this key). Example: the left shift key.
997 * @since 1.4
1011 * numeric keypad or with a virtual key corresponding to the
1012 * numeric keypad.
1013 * @since 1.4
1014 */
1015 public static final int KEY_LOCATION_NUMPAD = 4;
1016
1017 /**
1018 * The unique value assigned to each of the keys on the
1019 * keyboard. There is a common set of key codes that
1020 * can be fired by most keyboards.
1021 * The symbolic name for a key code should be used rather
1022 * than the code value itself.
1023 *
1024 * @serial
1025 * @see #getKeyCode()
1026 * @see #setKeyCode(int)
1027 */
1028 int keyCode;
1029
1030 /**
1031 * <code>keyChar</code> is a valid unicode character
1032 * that is fired by a key or a key combination on
1033 * a keyboard.
1034 *
1035 * @serial
1036 * @see #getKeyChar()
1037 * @see #setKeyChar(char)
1038 */
1039 char keyChar;
1040
1041 /**
1042 * The location of the key on the keyboard.
1043 *
1044 * Some keys occur more than once on a keyboard, e.g. the left and
1045 * right shift keys. Additionally, some keys occur on the numeric
1046 * keypad. This variable is used to distinguish such keys.
1047 *
1048 * The only legal values are <code>KEY_LOCATION_UNKNOWN</code>,
1049 * <code>KEY_LOCATION_STANDARD</code>, <code>KEY_LOCATION_LEFT</code>,
1050 * <code>KEY_LOCATION_RIGHT</code>, and <code>KEY_LOCATION_NUMPAD</code>.
1051 *
1052 * @serial
1053 * @see #getKeyLocation()
1054 */
1055 int keyLocation;
1056
1057 //set from native code.
1058 private transient long rawCode = 0;
1059 private transient long primaryLevelUnicode = 0;
1060 private transient long scancode = 0; // for MS Windows only
1061 private transient long extendedKeyCode = 0;
1062
1063 /*
1064 * JDK 1.1 serialVersionUID
1065 */
1066 private static final long serialVersionUID = -2352130953028126954L;
1067
1068 static {
1069 /* ensure that the necessary native libraries are loaded */
1070 NativeLibLoader.loadLibraries();
1098 * Initialize JNI field and method IDs for fields that may be
1099 * accessed from C.
1100 */
1101 private static native void initIDs();
1102
1103 /**
1104 * The original event source.
1105 *
1106 * Event source can be changed during processing, but in some cases
1107 * we need to be able to obtain original source.
1108 */
1109 private Component originalSource;
1110
1111 private KeyEvent(Component source, int id, long when, int modifiers,
1112 int keyCode, char keyChar, int keyLocation, boolean isProxyActive) {
1113 this(source, id, when, modifiers, keyCode, keyChar, keyLocation);
1114 this.isProxyActive = isProxyActive;
1115 }
1116
1117 /**
1118 * Constructs a <code>KeyEvent</code> object.
1119 * <p>This method throws an
1120 * <code>IllegalArgumentException</code> if <code>source</code>
1121 * is <code>null</code>.
1122 *
1123 * @param source The <code>Component</code> that originated the event
1124 * @param id An integer indicating the type of event.
1125 * For information on allowable values, see
1126 * the class description for {@link KeyEvent}
1127 * @param when A long integer that specifies the time the event
1128 * occurred.
1129 * Passing negative or zero value
1130 * is not recommended
1131 * @param modifiers The modifier keys down during event (shift, ctrl,
1132 * alt, meta).
1133 * Passing negative value
1134 * is not recommended.
1135 * Zero value means that no modifiers were passed.
1136 * Use either an extended _DOWN_MASK or old _MASK modifiers,
1137 * however do not mix models in the one event.
1138 * The extended modifiers are preferred for using
1139 * @param keyCode The integer code for an actual key, or VK_UNDEFINED
1140 * (for a key-typed event)
1141 * @param keyChar The Unicode character generated by this event, or
1142 * CHAR_UNDEFINED (for key-pressed and key-released
1143 * events which do not map to a valid Unicode character)
1144 * @param keyLocation Identifies the key location. The only legal
1145 * values are <code>KEY_LOCATION_UNKNOWN</code>,
1146 * <code>KEY_LOCATION_STANDARD</code>, <code>KEY_LOCATION_LEFT</code>,
1147 * <code>KEY_LOCATION_RIGHT</code>, and <code>KEY_LOCATION_NUMPAD</code>.
1148 * @throws IllegalArgumentException
1149 * if <code>id</code> is <code>KEY_TYPED</code> and
1150 * <code>keyChar</code> is <code>CHAR_UNDEFINED</code>;
1151 * or if <code>id</code> is <code>KEY_TYPED</code> and
1152 * <code>keyCode</code> is not <code>VK_UNDEFINED</code>;
1153 * or if <code>id</code> is <code>KEY_TYPED</code> and
1154 * <code>keyLocation</code> is not <code>KEY_LOCATION_UNKNOWN</code>;
1155 * or if <code>keyLocation</code> is not one of the legal
1156 * values enumerated above.
1157 * @throws IllegalArgumentException if <code>source</code> is null
1158 * @see #getSource()
1159 * @see #getID()
1160 * @see #getWhen()
1161 * @see #getModifiers()
1162 * @see #getKeyCode()
1163 * @see #getKeyChar()
1164 * @see #getKeyLocation()
1165 * @since 1.4
1166 */
1167 public KeyEvent(Component source, int id, long when, int modifiers,
1168 int keyCode, char keyChar, int keyLocation) {
1169 super(source, id, when, modifiers);
1170 if (id == KEY_TYPED) {
1171 if (keyChar == CHAR_UNDEFINED) {
1172 throw new IllegalArgumentException("invalid keyChar");
1173 }
1174 if (keyCode != VK_UNDEFINED) {
1175 throw new IllegalArgumentException("invalid keyCode");
1176 }
1177 if (keyLocation != KEY_LOCATION_UNKNOWN) {
1179 }
1180 }
1181
1182 this.keyCode = keyCode;
1183 this.keyChar = keyChar;
1184
1185 if ((keyLocation < KEY_LOCATION_UNKNOWN) ||
1186 (keyLocation > KEY_LOCATION_NUMPAD)) {
1187 throw new IllegalArgumentException("invalid keyLocation");
1188 }
1189 this.keyLocation = keyLocation;
1190 if ((getModifiers() != 0) && (getModifiersEx() == 0)) {
1191 setNewModifiers();
1192 } else if ((getModifiers() == 0) && (getModifiersEx() != 0)) {
1193 setOldModifiers();
1194 }
1195 originalSource = source;
1196 }
1197
1198 /**
1199 * Constructs a <code>KeyEvent</code> object.
1200 * <p> This method throws an
1201 * <code>IllegalArgumentException</code> if <code>source</code>
1202 * is <code>null</code>.
1203 *
1204 * @param source The <code>Component</code> that originated the event
1205 * @param id An integer indicating the type of event.
1206 * For information on allowable values, see
1207 * the class description for {@link KeyEvent}
1208 * @param when A long integer that specifies the time the event
1209 * occurred.
1210 * Passing negative or zero value
1211 * is not recommended
1212 * @param modifiers The modifier keys down during event (shift, ctrl,
1213 * alt, meta).
1214 * Passing negative value
1215 * is not recommended.
1216 * Zero value means that no modifiers were passed.
1217 * Use either an extended _DOWN_MASK or old _MASK modifiers,
1218 * however do not mix models in the one event.
1219 * The extended modifiers are preferred for using
1220 * @param keyCode The integer code for an actual key, or VK_UNDEFINED
1221 * (for a key-typed event)
1222 * @param keyChar The Unicode character generated by this event, or
1223 * CHAR_UNDEFINED (for key-pressed and key-released
1224 * events which do not map to a valid Unicode character)
1225 * @throws IllegalArgumentException if <code>id</code> is
1226 * <code>KEY_TYPED</code> and <code>keyChar</code> is
1227 * <code>CHAR_UNDEFINED</code>; or if <code>id</code> is
1228 * <code>KEY_TYPED</code> and <code>keyCode</code> is not
1229 * <code>VK_UNDEFINED</code>
1230 * @throws IllegalArgumentException if <code>source</code> is null
1231 * @see #getSource()
1232 * @see #getID()
1233 * @see #getWhen()
1234 * @see #getModifiers()
1235 * @see #getKeyCode()
1236 * @see #getKeyChar()
1237 */
1238 public KeyEvent(Component source, int id, long when, int modifiers,
1239 int keyCode, char keyChar) {
1240 this(source, id, when, modifiers, keyCode, keyChar,
1241 KEY_LOCATION_UNKNOWN);
1242 }
1243
1244 /**
1245 * @deprecated as of JDK1.1; use {@link #KeyEvent(Component, int, long, int, int, char)} instead
1246 * @param source The <code>Component</code> that originated the event
1247 * @param id An integer indicating the type of event.
1248 * For information on allowable values, see
1249 * the class description for {@link KeyEvent}
1250 * @param when A long integer that specifies the time the event
1251 * occurred.
1252 * Passing negative or zero value
1253 * is not recommended
1254 * @param modifiers The modifier keys down during event (shift, ctrl,
1255 * alt, meta).
1256 * Passing negative value
1257 * is not recommended.
1258 * Zero value means that no modifiers were passed.
1259 * Use either an extended _DOWN_MASK or old _MASK modifiers,
1260 * however do not mix models in the one event.
1261 * The extended modifiers are preferred for using
1262 * @param keyCode The integer code for an actual key, or VK_UNDEFINED
1263 * (for a key-typed event)
1264 */
1265 @Deprecated
1266 public KeyEvent(Component source, int id, long when, int modifiers,
1267 int keyCode) {
1268 this(source, id, when, modifiers, keyCode, (char)keyCode);
1269 }
1270
1271 /**
1272 * Returns the integer keyCode associated with the key in this event.
1273 *
1274 * @return the integer code for an actual key on the keyboard.
1275 * (For <code>KEY_TYPED</code> events, the keyCode is
1276 * <code>VK_UNDEFINED</code>.)
1277 */
1278 public int getKeyCode() {
1279 return keyCode;
1280 }
1281
1282 /**
1283 * Set the keyCode value to indicate a physical key.
1284 *
1285 * @param keyCode an integer corresponding to an actual key on the keyboard.
1286 */
1287 public void setKeyCode(int keyCode) {
1288 this.keyCode = keyCode;
1289 }
1290
1291 /**
1292 * Returns the character associated with the key in this event.
1293 * For example, the <code>KEY_TYPED</code> event for shift + "a"
1294 * returns the value for "A".
1295 * <p>
1296 * <code>KEY_PRESSED</code> and <code>KEY_RELEASED</code> events
1297 * are not intended for reporting of character input. Therefore,
1298 * the values returned by this method are guaranteed to be
1299 * meaningful only for <code>KEY_TYPED</code> events.
1300 *
1301 * @return the Unicode character defined for this key event.
1302 * If no valid Unicode character exists for this key event,
1303 * <code>CHAR_UNDEFINED</code> is returned.
1304 */
1305 public char getKeyChar() {
1306 return keyChar;
1307 }
1308
1309 /**
1310 * Set the keyChar value to indicate a logical character.
1311 *
1312 * @param keyChar a char corresponding to the combination of keystrokes
1313 * that make up this event.
1314 */
1315 public void setKeyChar(char keyChar) {
1316 this.keyChar = keyChar;
1317 }
1318
1319 /**
1320 * Set the modifiers to indicate additional keys that were held down
1321 * (e.g. shift, ctrl, alt, meta) defined as part of InputEvent.
1322 * <p>
1323 * NOTE: use of this method is not recommended, because many AWT
1324 * implementations do not recognize modifier changes. This is
1325 * especially true for <code>KEY_TYPED</code> events where the shift
1326 * modifier is changed.
1327 *
1328 * @param modifiers an integer combination of the modifier constants.
1329 * @see InputEvent
1330 * @deprecated as of JDK1.1.4
1331 */
1332 @Deprecated
1333 public void setModifiers(int modifiers) {
1334 this.modifiers = modifiers;
1335 if ((getModifiers() != 0) && (getModifiersEx() == 0)) {
1336 setNewModifiers();
1337 } else if ((getModifiers() == 0) && (getModifiersEx() != 0)) {
1338 setOldModifiers();
1339 }
1340 }
1341
1342 /**
1343 * Returns the location of the key that originated this key event.
1344 *
1345 * Some keys occur more than once on a keyboard, e.g. the left and
1346 * right shift keys. Additionally, some keys occur on the numeric
1347 * keypad. This provides a way of distinguishing such keys.
1348 *
1349 * @return the location of the key that was pressed or released.
1350 * Always returns <code>KEY_LOCATION_UNKNOWN</code> for
1351 * <code>KEY_TYPED</code> events.
1352 * @since 1.4
1353 */
1354 public int getKeyLocation() {
1355 return keyLocation;
1356 }
1357
1358 /**
1359 * Returns a String describing the keyCode, such as "HOME", "F1" or "A".
1360 * These strings can be localized by changing the awt.properties file.
1361 *
1362 * @param keyCode the key whose description is to be returned
1363 * @return a string containing a text description for a physical key,
1364 * identified by its keyCode
1365 */
1366 public static String getKeyText(int keyCode) {
1367 if (keyCode >= VK_0 && keyCode <= VK_9 ||
1368 keyCode >= VK_A && keyCode <= VK_Z) {
1369 return String.valueOf((char)keyCode);
1370 }
1371
1524 case VK_CUT: return Toolkit.getProperty("AWT.cut", "Cut");
1525 case VK_FIND: return Toolkit.getProperty("AWT.find", "Find");
1526 case VK_PROPS: return Toolkit.getProperty("AWT.props", "Props");
1527 case VK_STOP: return Toolkit.getProperty("AWT.stop", "Stop");
1528 }
1529
1530 if (keyCode >= VK_NUMPAD0 && keyCode <= VK_NUMPAD9) {
1531 String numpad = Toolkit.getProperty("AWT.numpad", "NumPad");
1532 char c = (char)(keyCode - VK_NUMPAD0 + '0');
1533 return numpad + "-" + c;
1534 }
1535
1536 if ((keyCode & 0x01000000) != 0) {
1537 return String.valueOf((char)(keyCode ^ 0x01000000 ));
1538 }
1539 String unknown = Toolkit.getProperty("AWT.unknown", "Unknown");
1540 return unknown + " keyCode: 0x" + Integer.toString(keyCode, 16);
1541 }
1542
1543 /**
1544 * Returns a <code>String</code> describing the modifier key(s),
1545 * such as "Shift", or "Ctrl+Shift". These strings can be
1546 * localized by changing the <code>awt.properties</code> file.
1547 * <p>
1548 * Note that <code>InputEvent.ALT_MASK</code> and
1549 * <code>InputEvent.BUTTON2_MASK</code> have the same value,
1550 * so the string "Alt" is returned for both modifiers. Likewise,
1551 * <code>InputEvent.META_MASK</code> and
1552 * <code>InputEvent.BUTTON3_MASK</code> have the same value,
1553 * so the string "Meta" is returned for both modifiers.
1554 *
1555 * @param modifiers the modifier mask to be processed
1556 * @return string a text description of the combination of modifier
1557 * keys that were held down during the event
1558 * @see InputEvent#getModifiersExText(int)
1559 */
1560 public static String getKeyModifiersText(int modifiers) {
1561 StringBuilder buf = new StringBuilder();
1562 if ((modifiers & InputEvent.META_MASK) != 0) {
1563 buf.append(Toolkit.getProperty("AWT.meta", "Meta"));
1564 buf.append("+");
1565 }
1566 if ((modifiers & InputEvent.CTRL_MASK) != 0) {
1567 buf.append(Toolkit.getProperty("AWT.control", "Ctrl"));
1568 buf.append("+");
1569 }
1570 if ((modifiers & InputEvent.ALT_MASK) != 0) {
1571 buf.append(Toolkit.getProperty("AWT.alt", "Alt"));
1572 buf.append("+");
1578 if ((modifiers & InputEvent.ALT_GRAPH_MASK) != 0) {
1579 buf.append(Toolkit.getProperty("AWT.altGraph", "Alt Graph"));
1580 buf.append("+");
1581 }
1582 if ((modifiers & InputEvent.BUTTON1_MASK) != 0) {
1583 buf.append(Toolkit.getProperty("AWT.button1", "Button1"));
1584 buf.append("+");
1585 }
1586 if (buf.length() > 0) {
1587 buf.setLength(buf.length()-1); // remove trailing '+'
1588 }
1589 return buf.toString();
1590 }
1591
1592
1593 /**
1594 * Returns whether the key in this event is an "action" key.
1595 * Typically an action key does not fire a unicode character and is
1596 * not a modifier key.
1597 *
1598 * @return <code>true</code> if the key is an "action" key,
1599 * <code>false</code> otherwise
1600 */
1601 public boolean isActionKey() {
1602 switch (keyCode) {
1603 case VK_HOME:
1604 case VK_END:
1605 case VK_PAGE_UP:
1606 case VK_PAGE_DOWN:
1607 case VK_UP:
1608 case VK_DOWN:
1609 case VK_LEFT:
1610 case VK_RIGHT:
1611 case VK_BEGIN:
1612
1613 case VK_KP_LEFT:
1614 case VK_KP_UP:
1615 case VK_KP_RIGHT:
1616 case VK_KP_DOWN:
1617
1618 case VK_F1:
1619 case VK_F2:
|
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.awt.event;
27
28 import java.awt.Component;
29 import java.awt.GraphicsEnvironment;
30 import java.awt.Toolkit;
31 import java.io.IOException;
32 import java.io.ObjectInputStream;
33 import sun.awt.AWTAccessor;
34
35 /**
36 * An event which indicates that a keystroke occurred in a component.
37 * <p>
38 * This low-level event is generated by a component object (such as a text
39 * field) when a key is pressed, released, or typed.
40 * The event is passed to every {@code KeyListener}
41 * or {@code KeyAdapter} object which registered to receive such
42 * events using the component's {@code addKeyListener} method.
43 * ({@code KeyAdapter} objects implement the
44 * {@code KeyListener} interface.) Each such listener object
45 * gets this {@code KeyEvent} when the event occurs.
46 * <p>
47 * <em>"Key typed" events</em> are higher-level and generally do not depend on
48 * the platform or keyboard layout. They are generated when a Unicode character
49 * is entered, and are the preferred way to find out about character input.
50 * In the simplest case, a key typed event is produced by a single key press
51 * (e.g., 'a'). Often, however, characters are produced by series of key
52 * presses (e.g., 'shift' + 'a'), and the mapping from key pressed events to
53 * key typed events may be many-to-one or many-to-many. Key releases are not
54 * usually necessary to generate a key typed event, but there are some cases
55 * where the key typed event is not generated until a key is released (e.g.,
56 * entering ASCII sequences via the Alt-Numpad method in Windows).
57 * No key typed events are generated for keys that don't generate Unicode
58 * characters (e.g., action keys, modifier keys, etc.).
59 * <p>
60 * The getKeyChar method always returns a valid Unicode character or
61 * CHAR_UNDEFINED. Character input is reported by KEY_TYPED events:
62 * KEY_PRESSED and KEY_RELEASED events are not necessarily associated
63 * with character input. Therefore, the result of the getKeyChar method
64 * is guaranteed to be meaningful only for KEY_TYPED events.
65 * <p>
957 * @since 1.5
958 */
959 public static final int VK_BEGIN = 0xFF58;
960
961 /**
962 * This value is used to indicate that the keyCode is unknown.
963 * KEY_TYPED events do not have a keyCode value; this value
964 * is used instead.
965 */
966 public static final int VK_UNDEFINED = 0x0;
967
968 /**
969 * KEY_PRESSED and KEY_RELEASED events which do not map to a
970 * valid Unicode character use this for the keyChar value.
971 */
972 public static final char CHAR_UNDEFINED = 0xFFFF;
973
974 /**
975 * A constant indicating that the keyLocation is indeterminate
976 * or not relevant.
977 * {@code KEY_TYPED} events do not have a keyLocation; this value
978 * is used instead.
979 * @since 1.4
980 */
981 public static final int KEY_LOCATION_UNKNOWN = 0;
982
983 /**
984 * A constant indicating that the key pressed or released
985 * is not distinguished as the left or right version of a key,
986 * and did not originate on the numeric keypad (or did not
987 * originate with a virtual key corresponding to the numeric
988 * keypad).
989 * @since 1.4
990 */
991 public static final int KEY_LOCATION_STANDARD = 1;
992
993 /**
994 * A constant indicating that the key pressed or released is in
995 * the left key location (there is more than one possible location
996 * for this key). Example: the left shift key.
997 * @since 1.4
1011 * numeric keypad or with a virtual key corresponding to the
1012 * numeric keypad.
1013 * @since 1.4
1014 */
1015 public static final int KEY_LOCATION_NUMPAD = 4;
1016
1017 /**
1018 * The unique value assigned to each of the keys on the
1019 * keyboard. There is a common set of key codes that
1020 * can be fired by most keyboards.
1021 * The symbolic name for a key code should be used rather
1022 * than the code value itself.
1023 *
1024 * @serial
1025 * @see #getKeyCode()
1026 * @see #setKeyCode(int)
1027 */
1028 int keyCode;
1029
1030 /**
1031 * {@code keyChar} is a valid unicode character
1032 * that is fired by a key or a key combination on
1033 * a keyboard.
1034 *
1035 * @serial
1036 * @see #getKeyChar()
1037 * @see #setKeyChar(char)
1038 */
1039 char keyChar;
1040
1041 /**
1042 * The location of the key on the keyboard.
1043 *
1044 * Some keys occur more than once on a keyboard, e.g. the left and
1045 * right shift keys. Additionally, some keys occur on the numeric
1046 * keypad. This variable is used to distinguish such keys.
1047 *
1048 * The only legal values are {@code KEY_LOCATION_UNKNOWN},
1049 * {@code KEY_LOCATION_STANDARD}, {@code KEY_LOCATION_LEFT},
1050 * {@code KEY_LOCATION_RIGHT}, and {@code KEY_LOCATION_NUMPAD}.
1051 *
1052 * @serial
1053 * @see #getKeyLocation()
1054 */
1055 int keyLocation;
1056
1057 //set from native code.
1058 private transient long rawCode = 0;
1059 private transient long primaryLevelUnicode = 0;
1060 private transient long scancode = 0; // for MS Windows only
1061 private transient long extendedKeyCode = 0;
1062
1063 /*
1064 * JDK 1.1 serialVersionUID
1065 */
1066 private static final long serialVersionUID = -2352130953028126954L;
1067
1068 static {
1069 /* ensure that the necessary native libraries are loaded */
1070 NativeLibLoader.loadLibraries();
1098 * Initialize JNI field and method IDs for fields that may be
1099 * accessed from C.
1100 */
1101 private static native void initIDs();
1102
1103 /**
1104 * The original event source.
1105 *
1106 * Event source can be changed during processing, but in some cases
1107 * we need to be able to obtain original source.
1108 */
1109 private Component originalSource;
1110
1111 private KeyEvent(Component source, int id, long when, int modifiers,
1112 int keyCode, char keyChar, int keyLocation, boolean isProxyActive) {
1113 this(source, id, when, modifiers, keyCode, keyChar, keyLocation);
1114 this.isProxyActive = isProxyActive;
1115 }
1116
1117 /**
1118 * Constructs a {@code KeyEvent} object.
1119 * <p>This method throws an
1120 * {@code IllegalArgumentException} if {@code source}
1121 * is {@code null}.
1122 *
1123 * @param source The {@code Component} that originated the event
1124 * @param id An integer indicating the type of event.
1125 * For information on allowable values, see
1126 * the class description for {@link KeyEvent}
1127 * @param when A long integer that specifies the time the event
1128 * occurred.
1129 * Passing negative or zero value
1130 * is not recommended
1131 * @param modifiers The modifier keys down during event (shift, ctrl,
1132 * alt, meta).
1133 * Passing negative value
1134 * is not recommended.
1135 * Zero value means that no modifiers were passed.
1136 * Use either an extended _DOWN_MASK or old _MASK modifiers,
1137 * however do not mix models in the one event.
1138 * The extended modifiers are preferred for using
1139 * @param keyCode The integer code for an actual key, or VK_UNDEFINED
1140 * (for a key-typed event)
1141 * @param keyChar The Unicode character generated by this event, or
1142 * CHAR_UNDEFINED (for key-pressed and key-released
1143 * events which do not map to a valid Unicode character)
1144 * @param keyLocation Identifies the key location. The only legal
1145 * values are {@code KEY_LOCATION_UNKNOWN},
1146 * {@code KEY_LOCATION_STANDARD}, {@code KEY_LOCATION_LEFT},
1147 * {@code KEY_LOCATION_RIGHT}, and {@code KEY_LOCATION_NUMPAD}.
1148 * @throws IllegalArgumentException
1149 * if {@code id} is {@code KEY_TYPED} and
1150 * {@code keyChar} is {@code CHAR_UNDEFINED};
1151 * or if {@code id} is {@code KEY_TYPED} and
1152 * {@code keyCode} is not {@code VK_UNDEFINED};
1153 * or if {@code id} is {@code KEY_TYPED} and
1154 * {@code keyLocation} is not {@code KEY_LOCATION_UNKNOWN};
1155 * or if {@code keyLocation} is not one of the legal
1156 * values enumerated above.
1157 * @throws IllegalArgumentException if {@code source} is null
1158 * @see #getSource()
1159 * @see #getID()
1160 * @see #getWhen()
1161 * @see #getModifiers()
1162 * @see #getKeyCode()
1163 * @see #getKeyChar()
1164 * @see #getKeyLocation()
1165 * @since 1.4
1166 */
1167 public KeyEvent(Component source, int id, long when, int modifiers,
1168 int keyCode, char keyChar, int keyLocation) {
1169 super(source, id, when, modifiers);
1170 if (id == KEY_TYPED) {
1171 if (keyChar == CHAR_UNDEFINED) {
1172 throw new IllegalArgumentException("invalid keyChar");
1173 }
1174 if (keyCode != VK_UNDEFINED) {
1175 throw new IllegalArgumentException("invalid keyCode");
1176 }
1177 if (keyLocation != KEY_LOCATION_UNKNOWN) {
1179 }
1180 }
1181
1182 this.keyCode = keyCode;
1183 this.keyChar = keyChar;
1184
1185 if ((keyLocation < KEY_LOCATION_UNKNOWN) ||
1186 (keyLocation > KEY_LOCATION_NUMPAD)) {
1187 throw new IllegalArgumentException("invalid keyLocation");
1188 }
1189 this.keyLocation = keyLocation;
1190 if ((getModifiers() != 0) && (getModifiersEx() == 0)) {
1191 setNewModifiers();
1192 } else if ((getModifiers() == 0) && (getModifiersEx() != 0)) {
1193 setOldModifiers();
1194 }
1195 originalSource = source;
1196 }
1197
1198 /**
1199 * Constructs a {@code KeyEvent} object.
1200 * <p> This method throws an
1201 * {@code IllegalArgumentException} if {@code source}
1202 * is {@code null}.
1203 *
1204 * @param source The {@code Component} that originated the event
1205 * @param id An integer indicating the type of event.
1206 * For information on allowable values, see
1207 * the class description for {@link KeyEvent}
1208 * @param when A long integer that specifies the time the event
1209 * occurred.
1210 * Passing negative or zero value
1211 * is not recommended
1212 * @param modifiers The modifier keys down during event (shift, ctrl,
1213 * alt, meta).
1214 * Passing negative value
1215 * is not recommended.
1216 * Zero value means that no modifiers were passed.
1217 * Use either an extended _DOWN_MASK or old _MASK modifiers,
1218 * however do not mix models in the one event.
1219 * The extended modifiers are preferred for using
1220 * @param keyCode The integer code for an actual key, or VK_UNDEFINED
1221 * (for a key-typed event)
1222 * @param keyChar The Unicode character generated by this event, or
1223 * CHAR_UNDEFINED (for key-pressed and key-released
1224 * events which do not map to a valid Unicode character)
1225 * @throws IllegalArgumentException if {@code id} is
1226 * {@code KEY_TYPED} and {@code keyChar} is
1227 * {@code CHAR_UNDEFINED}; or if {@code id} is
1228 * {@code KEY_TYPED} and {@code keyCode} is not
1229 * {@code VK_UNDEFINED}
1230 * @throws IllegalArgumentException if {@code source} is null
1231 * @see #getSource()
1232 * @see #getID()
1233 * @see #getWhen()
1234 * @see #getModifiers()
1235 * @see #getKeyCode()
1236 * @see #getKeyChar()
1237 */
1238 public KeyEvent(Component source, int id, long when, int modifiers,
1239 int keyCode, char keyChar) {
1240 this(source, id, when, modifiers, keyCode, keyChar,
1241 KEY_LOCATION_UNKNOWN);
1242 }
1243
1244 /**
1245 * @deprecated as of JDK1.1; use {@link #KeyEvent(Component, int, long, int, int, char)} instead
1246 * @param source The {@code Component} that originated the event
1247 * @param id An integer indicating the type of event.
1248 * For information on allowable values, see
1249 * the class description for {@link KeyEvent}
1250 * @param when A long integer that specifies the time the event
1251 * occurred.
1252 * Passing negative or zero value
1253 * is not recommended
1254 * @param modifiers The modifier keys down during event (shift, ctrl,
1255 * alt, meta).
1256 * Passing negative value
1257 * is not recommended.
1258 * Zero value means that no modifiers were passed.
1259 * Use either an extended _DOWN_MASK or old _MASK modifiers,
1260 * however do not mix models in the one event.
1261 * The extended modifiers are preferred for using
1262 * @param keyCode The integer code for an actual key, or VK_UNDEFINED
1263 * (for a key-typed event)
1264 */
1265 @Deprecated
1266 public KeyEvent(Component source, int id, long when, int modifiers,
1267 int keyCode) {
1268 this(source, id, when, modifiers, keyCode, (char)keyCode);
1269 }
1270
1271 /**
1272 * Returns the integer keyCode associated with the key in this event.
1273 *
1274 * @return the integer code for an actual key on the keyboard.
1275 * (For {@code KEY_TYPED} events, the keyCode is
1276 * {@code VK_UNDEFINED}.)
1277 */
1278 public int getKeyCode() {
1279 return keyCode;
1280 }
1281
1282 /**
1283 * Set the keyCode value to indicate a physical key.
1284 *
1285 * @param keyCode an integer corresponding to an actual key on the keyboard.
1286 */
1287 public void setKeyCode(int keyCode) {
1288 this.keyCode = keyCode;
1289 }
1290
1291 /**
1292 * Returns the character associated with the key in this event.
1293 * For example, the {@code KEY_TYPED} event for shift + "a"
1294 * returns the value for "A".
1295 * <p>
1296 * {@code KEY_PRESSED} and {@code KEY_RELEASED} events
1297 * are not intended for reporting of character input. Therefore,
1298 * the values returned by this method are guaranteed to be
1299 * meaningful only for {@code KEY_TYPED} events.
1300 *
1301 * @return the Unicode character defined for this key event.
1302 * If no valid Unicode character exists for this key event,
1303 * {@code CHAR_UNDEFINED} is returned.
1304 */
1305 public char getKeyChar() {
1306 return keyChar;
1307 }
1308
1309 /**
1310 * Set the keyChar value to indicate a logical character.
1311 *
1312 * @param keyChar a char corresponding to the combination of keystrokes
1313 * that make up this event.
1314 */
1315 public void setKeyChar(char keyChar) {
1316 this.keyChar = keyChar;
1317 }
1318
1319 /**
1320 * Set the modifiers to indicate additional keys that were held down
1321 * (e.g. shift, ctrl, alt, meta) defined as part of InputEvent.
1322 * <p>
1323 * NOTE: use of this method is not recommended, because many AWT
1324 * implementations do not recognize modifier changes. This is
1325 * especially true for {@code KEY_TYPED} events where the shift
1326 * modifier is changed.
1327 *
1328 * @param modifiers an integer combination of the modifier constants.
1329 * @see InputEvent
1330 * @deprecated as of JDK1.1.4
1331 */
1332 @Deprecated
1333 public void setModifiers(int modifiers) {
1334 this.modifiers = modifiers;
1335 if ((getModifiers() != 0) && (getModifiersEx() == 0)) {
1336 setNewModifiers();
1337 } else if ((getModifiers() == 0) && (getModifiersEx() != 0)) {
1338 setOldModifiers();
1339 }
1340 }
1341
1342 /**
1343 * Returns the location of the key that originated this key event.
1344 *
1345 * Some keys occur more than once on a keyboard, e.g. the left and
1346 * right shift keys. Additionally, some keys occur on the numeric
1347 * keypad. This provides a way of distinguishing such keys.
1348 *
1349 * @return the location of the key that was pressed or released.
1350 * Always returns {@code KEY_LOCATION_UNKNOWN} for
1351 * {@code KEY_TYPED} events.
1352 * @since 1.4
1353 */
1354 public int getKeyLocation() {
1355 return keyLocation;
1356 }
1357
1358 /**
1359 * Returns a String describing the keyCode, such as "HOME", "F1" or "A".
1360 * These strings can be localized by changing the awt.properties file.
1361 *
1362 * @param keyCode the key whose description is to be returned
1363 * @return a string containing a text description for a physical key,
1364 * identified by its keyCode
1365 */
1366 public static String getKeyText(int keyCode) {
1367 if (keyCode >= VK_0 && keyCode <= VK_9 ||
1368 keyCode >= VK_A && keyCode <= VK_Z) {
1369 return String.valueOf((char)keyCode);
1370 }
1371
1524 case VK_CUT: return Toolkit.getProperty("AWT.cut", "Cut");
1525 case VK_FIND: return Toolkit.getProperty("AWT.find", "Find");
1526 case VK_PROPS: return Toolkit.getProperty("AWT.props", "Props");
1527 case VK_STOP: return Toolkit.getProperty("AWT.stop", "Stop");
1528 }
1529
1530 if (keyCode >= VK_NUMPAD0 && keyCode <= VK_NUMPAD9) {
1531 String numpad = Toolkit.getProperty("AWT.numpad", "NumPad");
1532 char c = (char)(keyCode - VK_NUMPAD0 + '0');
1533 return numpad + "-" + c;
1534 }
1535
1536 if ((keyCode & 0x01000000) != 0) {
1537 return String.valueOf((char)(keyCode ^ 0x01000000 ));
1538 }
1539 String unknown = Toolkit.getProperty("AWT.unknown", "Unknown");
1540 return unknown + " keyCode: 0x" + Integer.toString(keyCode, 16);
1541 }
1542
1543 /**
1544 * Returns a {@code String} describing the modifier key(s),
1545 * such as "Shift", or "Ctrl+Shift". These strings can be
1546 * localized by changing the {@code awt.properties} file.
1547 * <p>
1548 * Note that {@code InputEvent.ALT_MASK} and
1549 * {@code InputEvent.BUTTON2_MASK} have the same value,
1550 * so the string "Alt" is returned for both modifiers. Likewise,
1551 * {@code InputEvent.META_MASK} and
1552 * {@code InputEvent.BUTTON3_MASK} have the same value,
1553 * so the string "Meta" is returned for both modifiers.
1554 *
1555 * @param modifiers the modifier mask to be processed
1556 * @return string a text description of the combination of modifier
1557 * keys that were held down during the event
1558 * @see InputEvent#getModifiersExText(int)
1559 */
1560 public static String getKeyModifiersText(int modifiers) {
1561 StringBuilder buf = new StringBuilder();
1562 if ((modifiers & InputEvent.META_MASK) != 0) {
1563 buf.append(Toolkit.getProperty("AWT.meta", "Meta"));
1564 buf.append("+");
1565 }
1566 if ((modifiers & InputEvent.CTRL_MASK) != 0) {
1567 buf.append(Toolkit.getProperty("AWT.control", "Ctrl"));
1568 buf.append("+");
1569 }
1570 if ((modifiers & InputEvent.ALT_MASK) != 0) {
1571 buf.append(Toolkit.getProperty("AWT.alt", "Alt"));
1572 buf.append("+");
1578 if ((modifiers & InputEvent.ALT_GRAPH_MASK) != 0) {
1579 buf.append(Toolkit.getProperty("AWT.altGraph", "Alt Graph"));
1580 buf.append("+");
1581 }
1582 if ((modifiers & InputEvent.BUTTON1_MASK) != 0) {
1583 buf.append(Toolkit.getProperty("AWT.button1", "Button1"));
1584 buf.append("+");
1585 }
1586 if (buf.length() > 0) {
1587 buf.setLength(buf.length()-1); // remove trailing '+'
1588 }
1589 return buf.toString();
1590 }
1591
1592
1593 /**
1594 * Returns whether the key in this event is an "action" key.
1595 * Typically an action key does not fire a unicode character and is
1596 * not a modifier key.
1597 *
1598 * @return {@code true} if the key is an "action" key,
1599 * {@code false} otherwise
1600 */
1601 public boolean isActionKey() {
1602 switch (keyCode) {
1603 case VK_HOME:
1604 case VK_END:
1605 case VK_PAGE_UP:
1606 case VK_PAGE_DOWN:
1607 case VK_UP:
1608 case VK_DOWN:
1609 case VK_LEFT:
1610 case VK_RIGHT:
1611 case VK_BEGIN:
1612
1613 case VK_KP_LEFT:
1614 case VK_KP_UP:
1615 case VK_KP_RIGHT:
1616 case VK_KP_DOWN:
1617
1618 case VK_F1:
1619 case VK_F2:
|