< prev index next >

src/java.desktop/share/classes/java/awt/event/KeyEvent.java

Print this page




  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:


< prev index next >