Bug ID: JDK-4424517 Need KeyEvent APIs to distinguish numpad and keyLocation

Type: Bug
Component: client-libs
Sub-Component: java.awt
Affected Version: 1.3.0,1.4.0

Priority: P2
Status: Closed
Resolution: Fixed
OS: generic
CPU: generic

Submitted: 2001-03-12
Updated: 2001-09-12
Resolved: 2001-04-04

Other
1.4.0 betaFixed

One of the longstanding complaints from developers, including several 
important partners, has been that we have no way to distinguish between 
the left and right versions of a key, or to distinguish key events that 
originate on the numeric keypad.

CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: merlin-beta FIXED IN: merlin-beta INTEGRATED IN: merlin-beta VERIFIED IN: merlin-beta3

14-06-2004

SUGGESTED FIX KeyEvent.java *************** *** 680,688 **** * KEY_PRESSED and KEY_RELEASED events which do not map to a * valid Unicode character use this for the keyChar value. */ ! public static final char CHAR_UNDEFINED = 0x0ffff; /** * The unique value assigned to each of the keys on the * keyboard. There is a common set of key codes that * can be fired by most keyboards. --- 681,732 ---- * KEY_PRESSED and KEY_RELEASED events which do not map to a * valid Unicode character use this for the keyChar value. */ ! public static final char CHAR_UNDEFINED = 0xffff; /** + * A constant indicating that the keyLocation is indeterminate + * or not relevant. + * KEY_TYPED events do not have a keyLocation; this value + * is used instead. + * @since 1.4 + */ + public static final int KEY_LOCATION_UNKNOWN = 0; + + /** + * A constant indicating that the key pressed or released + * is not distinguished as the left or right version of a key, + * and did not originate on the numeric keypad (or did not + * originate with a virtual key corresponding to the numeric + * keypad). + * @since 1.4 + */ + public static final int KEY_LOCATION_STANDARD = 1; + + /** + * A constant indicating that the key pressed or released is in + * the left key location (there is more than one possible location + * for this key). Example: the left shift key. + * @since 1.4 + */ + public static final int KEY_LOCATION_LEFT = 2; + + /** + * A constant indicating that the key pressed or released is in + * the right key location (there is more than one possible location + * for this key). Example: the right shift key. + * @since 1.4 + */ + public static final int KEY_LOCATION_RIGHT = 3; + + /** + * A constant indicating that the key event originated on the + * numeric keypad or with a virtual key corresponding to the + * numeric keypad. + * @since 1.4 + */ + public static final int KEY_LOCATION_NUMPAD = 4; + + /** * The unique value assigned to each of the keys on the * keyboard. There is a common set of key codes that * can be fired by most keyboards. *************** *** 706,711 **** --- 750,767 ---- */ char keyChar; + /** + * The location of the key on the keyboard. + * + * Some keys occur more than once on a keyboard, e.g. the left and + * right shift keys. Additionally, some keys occur on the numeric + * keypad. This variable is used to distinguish such keys. + * + * @serial + * @see getKeyLocation() + */ + int keyLocation; + /* * JDK 1.1 serialVersionUID */ *************** *** 728,760 **** * * @param source the Component that originated the event * @param id an integer identifying the type of event ! * @param when a long integer that specifies the time the event occurred ! * @param modifiers the modifier keys down during event (shift, ctrl, alt, meta) ! * new _DOWN_ modifiers are set by old modifiers ! * @param keyCode the integer code for an actual key, or VK_UNDEFINED * (for a key-typed event) ! * @param keyChar the Unicode character generated by this event, or * CHAR_UNDEFINED (for key-pressed and key-released * events which do not map to a valid Unicode character) */ public KeyEvent(Component source, int id, long when, int modifiers, ! int keyCode, char keyChar) { super(source, id, when, modifiers); ! this.modifiers = mapOldModifiers(modifiers); ! if (id == KEY_TYPED && keyChar == CHAR_UNDEFINED) { ! throw new IllegalArgumentException("invalid keyChar"); } - if (id == KEY_TYPED && keyCode != VK_UNDEFINED) { - throw new IllegalArgumentException("invalid keyCode"); - } this.keyCode = keyCode; this.keyChar = keyChar; } /* ! * @deprecated, as of JDK1.1 - Do NOT USE; will be removed in 1.1.1. */ public KeyEvent(Component source, int id, long when, int modifiers, int keyCode) { --- 784,851 ---- * * @param source the Component that originated the event * @param id an integer identifying the type of event ! * @param when a long integer that specifies the time the event ! * occurred ! * @param modifiers the modifier keys down during the event ! * (e.g. shift, ctrl, alt, meta) ! * @param keyCode the integer code for an actual key, or VK_UNDEFINED * (for a key-typed event) ! * @param keyChar the Unicode character generated by this event, or * CHAR_UNDEFINED (for key-pressed and key-released * events which do not map to a valid Unicode character) + * @param location identifies the key location + * @throws IllegalArgumentException + * if the id is KEY_TYPED and the keyChar is CHAR_UNDEFINED, + * if the id is KEY_TYPED and the keyCode is not VK_UNDEFINED, + * or if the id is KEY_TYPED and the location is not + * KEY_LOCATION_UNKNOWN + * @since 1.4 */ public KeyEvent(Component source, int id, long when, int modifiers, ! int keyCode, char keyChar, int location) { super(source, id, when, modifiers); ! this.modifiers = mapOldModifiers(modifiers); ! if (id == KEY_TYPED) { ! if (keyChar == CHAR_UNDEFINED) { ! throw new IllegalArgumentException("invalid keyChar"); ! } ! if (keyCode != VK_UNDEFINED) { ! throw new IllegalArgumentException("invalid keyCode"); ! } ! if (location != KEY_LOCATION_UNKNOWN) { ! throw new IllegalArgumentException("invalid keyLocation"); ! } } this.keyCode = keyCode; this.keyChar = keyChar; + this.keyLocation = location; } + /** + * Constructs a KeyEvent object. + * + * @param source the Component that originated the event + * @param id an integer identifying the type of event + * @param when a long integer that specifies the time the event + occurred + * @param modifiers the modifier keys down during the event + (e.g. shift, ctrl, alt, meta) + * @param keyCode the integer code for an actual key, or VK_UNDEFINED + * (for a key-typed event) + * @param keyChar the Unicode character generated by this event, or + * CHAR_UNDEFINED (for key-pressed and key-released + * events which do not map to a valid Unicode character) + */ + public KeyEvent(Component source, int id, long when, int modifiers, + int keyCode, char keyChar) { + this(source, id, when, modifiers, keyCode, keyChar, + KEY_LOCATION_UNKNOWN); + } + /* ! * @deprecated, as of JDK1.1 */ public KeyEvent(Component source, int id, long when, int modifiers, int keyCode) { *************** *** 762,771 **** } /** ! * Returns the integer key-code associated with the key in this event. * * @return the integer code for an actual key on the keyboard. ! * (For KEY_TYPED events, keyCode is VK_UNDEFINED.) */ public int getKeyCode() { return keyCode; --- 853,862 ---- } /** ! * Returns the integer keyCode associated with the key in this event. * * @return the integer code for an actual key on the keyboard. ! * (For KEY_TYPED events, the keyCode is VK_UNDEFINED.) */ public int getKeyCode() { return keyCode; *************** *** 791,796 **** --- 882,902 ---- } /** + * Returns the location of the key that originated this key event. + * + * Some keys occur more than once on a keyboard, e.g. the left and + * right shift keys. Additionally, some keys occur on the numeric + * keypad. This provides a way of distinguishing such keys. + * + * @return the location of the key that was pressed or released, + * Always returns KEY_LOCATION_UNKNOWN for KEY_TYPED events. + * @since 1.4 + */ + public int getKeyLocation() { + return keyLocation; + } + + /** * Set the modifiers to indicate additional keys that were held down * (shift, ctrl, alt, meta) defined as part of InputEvent. * <p> *************** *** 1158,1166 **** --- 1264,1296 ---- } else { str += ",keyChar='" + keyChar + "'"; } + if (modifiers > 0) { str += ",modifiers=" + getKeyModifiersText(modifiers); } + + String locationStr; + switch (keyLocation) { + case KEY_LOCATION_UNKNOWN: + locationStr = "KEY_LOCATION_UNKNOWN"; + break; + case KEY_LOCATION_STANDARD: + locationStr = "KEY_LOCATION_STANDARD"; + break; + case KEY_LOCATION_LEFT: + locationStr = "KEY_LOCATION_LEFT"; + break; + case KEY_LOCATION_RIGHT: + locationStr = "KEY_LOCATION_RIGHT"; + break; + case KEY_LOCATION_NUMPAD: + locationStr = "KEY_LOCATION_NUMPAD"; + break; + default: + locationStr = "KEY_LOCATION_UNKNOWN"; + } + str += ",keyLocation=" + locationStr; + return str; }

11-06-2004

EVALUATION Commit to fix in Merlin-beta eric.hawkes@eng 2001-03-12 Note: SQE filed a bug that cannot be fixed due to compatibility problems. However, this fix will provide functionality that will allow developers to work around that deficiency. See 4342184. This issue has been escalated twice in the past, once by CBOT (we did a poor job on that, which has produced the unfixable incompatibility in 4342184). The other time was 4203982. eric.hawkes@eng 2001-03-12 See Comments for CCC request. eric.hawkes@eng 2001-03-13 This is verified using the tests developed for the CCC 4424517. ###@###.### 2001-09-12

12-03-2001

Duplicate :	JDK-4521090 - distinction between left and right ctrl keys / key events
Relates :	JDK-4342184 - In Windows, arrow keys throws Invalid key code exception when pressed by robot.
Relates :	JDK-4087296 - ANSI Keyboard duplicate keycodes
Relates :	JDK-4069679 - Key mapping for some keys is inconsistent.
Relates :	JDK-4626596 - Add support for location to identifier to AWTKeyStroke
Relates :	JDK-4106941 - KeyCodes for numeric keypad arrow keys are inconsistent between win32/Solaris
Relates :	JDK-4203982 - Keypad key codes are not unique
Relates :	JDK-4427794 - need to differentiate between left_shift key and right_shift_keys
Relates :	JDK-4302270 - Can't distinguish between left & right alt
Relates :	JDK-4114623 - Number Pad Enter Key is not supported on Java VM's