1. /*

  2.  * @(#)KeyEvent.java	1.39 01/11/29

  3.  *

  4.  * Copyright 2002 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package java.awt.event;

  9. 

  10. import java.awt.Event;

  11. import java.awt.Component;

  12. import java.awt.Toolkit;

  13. 

  14. /**

  15.  * An event which indicates that a keystroke occurred in a component.

  16.  * <P>

  17.  * This low-level event is generated by a component object (such as a text 

  18.  * field) when a key is pressed, released, or typed.  

  19.  * The event is passed to every <code>KeyListener</code>

  20.  * or <code>KeyAdapter</code> object which registered to receive such

  21.  * events using the component's <code>addKeyListener</code> method.

  22.  * (<code>KeyAdapter</code> objects implement the 

  23.  * <code>KeyListener</code> interface.)  Each such listener object 

  24.  * gets this <code>KeyEvent</code> when the event occurs.

  25.  *

  26.  * <p>

  27.  * <em>"Key typed" events</em> are higher-level and generally do not depend on 

  28.  * the platform or keyboard layout.  They are generated when a character is 

  29.  * entered, and are the preferred way to find out about character input.

  30.  * In the simplest case, a key typed event is produced by a single key press 

  31.  * (e.g., 'a').  Often, however, characters are produced by series of key 

  32.  * presses (e.g., 'shift' + 'a'), and the mapping from key pressed events to 

  33.  * key typed events may be many-to-one or many-to-many.  Key releases are not 

  34.  * usually necessary to generate a key typed event, but there are some cases 

  35.  * where the key typed event is not generated until a key is released (e.g., 

  36.  * entering ASCII sequences via the Alt-Numpad method in Windows).  

  37.  * No key typed events are generated for keys that don't generate characters

  38.  * (e.g., action keys, modifier keys, etc.).

  39.  * The getKeyChar method always returns a valid Unicode character or 

  40.  * CHAR_UNDEFINED.  

  41.  * For key pressed and key released events, the getKeyCode method returns 

  42.  * the event's keyCode.  For key typed events, the getKeyCode method 

  43.  * always returns VK_UNDEFINED.

  44.  *

  45.  * <p>

  46.  * <em>"Key pressed" and "key released" events</em> are lower-level and depend 

  47.  * on the platform and keyboard layout. They are generated whenever a key is 

  48.  * pressed or released, and are the only way to find out about keys that don't 

  49.  * generate character input (e.g., action keys, modifier keys, etc.). The key 

  50.  * being pressed or released is indicated by the getKeyCode method, which returns 

  51.  * a virtual key code.

  52.  *

  53.  * <p>

  54.  * <em>Virtual key codes</em> are used to report which keyboard key has

  55.  * been pressed, rather than a character generated by the combination

  56.  * of one or more keystrokes (like "A", which comes from shift and "a").  

  57.  *

  58.  * <P>

  59.  * For example, pressing the Shift key will cause a KEY_PRESSED event 

  60.  * with a VK_SHIFT keyCode, while pressing the 'a' key will result in 

  61.  * a VK_A keyCode.  After the 'a' key is released, a KEY_RELEASED event 

  62.  * will be fired with VK_A. Separately, a KEY_TYPED event with a keyChar 

  63.  * value of 'A' is generated.

  64.  *

  65.  * <P>

  66.  * Notes:

  67.  * <ul>

  68.  * <li>Key combinations which do not result in characters, such as action keys 

  69.  * like F1 and the HELP key, do not generate KEY_TYPED events.

  70.  * <li>Not all keyboards or systems are capable of generating all

  71.  * virtual key codes.  No attempt is made in Java to artificially

  72.  * generate these keys.

  73.  * <li>Virtual key codes do not identify a physical key, they depend on the

  74.  * platform and keyboard layout. For

  75.  * example, the key that on a Windows U.S. keyboard layout generates VK_Q,

  76.  * generates VK_A on a Windows French keyboard layout.

  77.  * <li>In order to support the platform-independent handling of action keys,

  78.  * the Java platform uses a few additional virtual key constants for functions

  79.  * that would otherwise have to be recognized by interpreting virtual key codes

  80.  * and modifiers. For example, for Japanese Windows keyboards, VK_ALL_CANDIDATES

  81.  * is returned instead of VK_CONVERT with the ALT modifer.

  82.  * </ul>

  83.  *

  84.  * <P>

  85.  * WARNING: Aside from those keys that are defined by the Java language

  86.  * (VK_ENTER, VK_BACK_SPACE, and VK_TAB), do not rely on the values of the VK_

  87.  * constants.  Sun reserves the right to change these values as needed

  88.  * to accomodate a wider range of keyboards in the future.  

  89.  *

  90.  * @see KeyAdapter

  91.  * @see KeyListener

  92.  * @see <a href="http://java.sun.com/docs/books/tutorial/post1.0/ui/keylistener.html">Tutorial: Writing a Key Listener</a>

  93.  * @see <a href="http://www.awl.com/cp/javaseries/jcl1_2.html">Reference: The Java Class Libraries (update file)</a>

  94.  *

  95.  * @version 1.39 11/29/01

  96.  * @author Carl Quinn

  97.  * @author Amy Fowler

  98.  * @author Norbert Lindenberg

  99.  */

  100. public class KeyEvent extends InputEvent {

  101. 

  102.     /**

  103.      * The first number in the range of ids used for key events.

  104.      */

  105.     public static final int KEY_FIRST = 400;

  106. 

  107.     /**

  108.      * The last number in the range of ids used for key events.

  109.      */

  110.     public static final int KEY_LAST  = 402;

  111. 

  112.     /**

  113.      * The "key typed" event.  This event is generated when a character is

  114.      * entered.  In the simplest case, it is produced by a single key press.  

  115.      * Often, however, characters are produced by series of key presses, and 

  116.      * the mapping from key pressed events to key typed events may be 

  117.      * many-to-one or many-to-many.  

  118.      */

  119.     public static final int KEY_TYPED = KEY_FIRST;

  120. 

  121.     /**

  122.      * The "key pressed" event. This event is generated when a key

  123.      * is pushed down.

  124.      */

  125.     public static final int KEY_PRESSED = 1 + KEY_FIRST; //Event.KEY_PRESS

  126. 

  127.     /**

  128.      * The "key released" event. This event is generated when a key

  129.      * is let up.

  130.      */

  131.     public static final int KEY_RELEASED = 2 + KEY_FIRST; //Event.KEY_RELEASE

  132. 

  133.     /* Virtual key codes. */

  134. 

  135.     public static final int VK_ENTER          = '\n';

  136.     public static final int VK_BACK_SPACE     = '\b';

  137.     public static final int VK_TAB            = '\t';

  138.     public static final int VK_CANCEL         = 0x03;

  139.     public static final int VK_CLEAR          = 0x0C;

  140.     public static final int VK_SHIFT          = 0x10;

  141.     public static final int VK_CONTROL        = 0x11;

  142.     public static final int VK_ALT            = 0x12;

  143.     public static final int VK_PAUSE          = 0x13;

  144.     public static final int VK_CAPS_LOCK      = 0x14;

  145.     public static final int VK_ESCAPE         = 0x1B;

  146.     public static final int VK_SPACE          = 0x20;

  147.     public static final int VK_PAGE_UP        = 0x21;

  148.     public static final int VK_PAGE_DOWN      = 0x22;

  149.     public static final int VK_END            = 0x23;

  150.     public static final int VK_HOME           = 0x24;

  151.     public static final int VK_LEFT           = 0x25;

  152.     public static final int VK_UP             = 0x26;

  153.     public static final int VK_RIGHT          = 0x27;

  154.     public static final int VK_DOWN           = 0x28;

  155.     public static final int VK_COMMA          = 0x2C;

  156.     public static final int VK_MINUS          = 0x2D;

  157.     public static final int VK_PERIOD         = 0x2E;

  158.     public static final int VK_SLASH          = 0x2F;

  159. 

  160.     /** VK_0 thru VK_9 are the same as ASCII '0' thru '9' (0x30 - 0x39) */

  161.     public static final int VK_0              = 0x30;

  162.     public static final int VK_1              = 0x31;

  163.     public static final int VK_2              = 0x32;

  164.     public static final int VK_3              = 0x33;

  165.     public static final int VK_4              = 0x34;

  166.     public static final int VK_5              = 0x35;

  167.     public static final int VK_6              = 0x36;

  168.     public static final int VK_7              = 0x37;

  169.     public static final int VK_8              = 0x38;

  170.     public static final int VK_9              = 0x39;

  171. 

  172.     public static final int VK_SEMICOLON      = 0x3B;

  173.     public static final int VK_EQUALS         = 0x3D;

  174. 

  175.     /** VK_A thru VK_Z are the same as ASCII 'A' thru 'Z' (0x41 - 0x5A) */

  176.     public static final int VK_A              = 0x41;

  177.     public static final int VK_B              = 0x42;

  178.     public static final int VK_C              = 0x43;

  179.     public static final int VK_D              = 0x44;

  180.     public static final int VK_E              = 0x45;

  181.     public static final int VK_F              = 0x46;

  182.     public static final int VK_G              = 0x47;

  183.     public static final int VK_H              = 0x48;

  184.     public static final int VK_I              = 0x49;

  185.     public static final int VK_J              = 0x4A;

  186.     public static final int VK_K              = 0x4B;

  187.     public static final int VK_L              = 0x4C;

  188.     public static final int VK_M              = 0x4D;

  189.     public static final int VK_N              = 0x4E;

  190.     public static final int VK_O              = 0x4F;

  191.     public static final int VK_P              = 0x50;

  192.     public static final int VK_Q              = 0x51;

  193.     public static final int VK_R              = 0x52;

  194.     public static final int VK_S              = 0x53;

  195.     public static final int VK_T              = 0x54;

  196.     public static final int VK_U              = 0x55;

  197.     public static final int VK_V              = 0x56;

  198.     public static final int VK_W              = 0x57;

  199.     public static final int VK_X              = 0x58;

  200.     public static final int VK_Y              = 0x59;

  201.     public static final int VK_Z              = 0x5A;

  202. 

  203.     public static final int VK_OPEN_BRACKET   = 0x5B;

  204.     public static final int VK_BACK_SLASH     = 0x5C;

  205.     public static final int VK_CLOSE_BRACKET  = 0x5D;

  206. 

  207.     public static final int VK_NUMPAD0        = 0x60;

  208.     public static final int VK_NUMPAD1        = 0x61;

  209.     public static final int VK_NUMPAD2        = 0x62;

  210.     public static final int VK_NUMPAD3        = 0x63;

  211.     public static final int VK_NUMPAD4        = 0x64;

  212.     public static final int VK_NUMPAD5        = 0x65;

  213.     public static final int VK_NUMPAD6        = 0x66;

  214.     public static final int VK_NUMPAD7        = 0x67;

  215.     public static final int VK_NUMPAD8        = 0x68;

  216.     public static final int VK_NUMPAD9        = 0x69;

  217.     public static final int VK_MULTIPLY       = 0x6A;

  218.     public static final int VK_ADD            = 0x6B;

  219.     public static final int VK_SEPARATER      = 0x6C;

  220.     public static final int VK_SUBTRACT       = 0x6D;

  221.     public static final int VK_DECIMAL        = 0x6E;

  222.     public static final int VK_DIVIDE         = 0x6F;

  223.     public static final int VK_DELETE         = 0x7F; /* ASCII DEL */

  224.     public static final int VK_NUM_LOCK       = 0x90;

  225.     public static final int VK_SCROLL_LOCK    = 0x91;

  226. 

  227.     /** Constant for the F1 function key. */

  228.     public static final int VK_F1             = 0x70;

  229. 

  230.     /** Constant for the F2 function key. */

  231.     public static final int VK_F2             = 0x71;

  232. 

  233.     /** Constant for the F3 function key. */

  234.     public static final int VK_F3             = 0x72;

  235. 

  236.     /** Constant for the F4 function key. */

  237.     public static final int VK_F4             = 0x73;

  238. 

  239.     /** Constant for the F5 function key. */

  240.     public static final int VK_F5             = 0x74;

  241. 

  242.     /** Constant for the F6 function key. */

  243.     public static final int VK_F6             = 0x75;

  244. 

  245.     /** Constant for the F7 function key. */

  246.     public static final int VK_F7             = 0x76;

  247. 

  248.     /** Constant for the F8 function key. */

  249.     public static final int VK_F8             = 0x77;

  250. 

  251.     /** Constant for the F9 function key. */

  252.     public static final int VK_F9             = 0x78;

  253. 

  254.     /** Constant for the F10 function key. */

  255.     public static final int VK_F10            = 0x79;

  256. 

  257.     /** Constant for the F11 function key. */

  258.     public static final int VK_F11            = 0x7A;

  259. 

  260.     /** Constant for the F12 function key. */

  261.     public static final int VK_F12            = 0x7B;

  262. 

  263.     /** Constant for the F13 function key. */

  264.     /* F13 - F24 are used on IBM 3270 keyboard; use random range for constants. */

  265.     public static final int VK_F13            = 0xF000;

  266.  

  267.     /** Constant for the F14 function key. */

  268.     public static final int VK_F14            = 0xF001;

  269.  

  270.     /** Constant for the F15 function key. */

  271.     public static final int VK_F15            = 0xF002;

  272.  

  273.     /** Constant for the F16 function key. */

  274.     public static final int VK_F16            = 0xF003;

  275.  

  276.     /** Constant for the F17 function key. */

  277.     public static final int VK_F17            = 0xF004;

  278.  

  279.     /** Constant for the F18 function key. */

  280.     public static final int VK_F18            = 0xF005;

  281.  

  282.     /** Constant for the F19 function key. */

  283.     public static final int VK_F19            = 0xF006;

  284.  

  285.     /** Constant for the F20 function key. */

  286.     public static final int VK_F20            = 0xF007;

  287.  

  288.     /** Constant for the F21 function key. */

  289.     public static final int VK_F21            = 0xF008;

  290.  

  291.     /** Constant for the F22 function key. */

  292.     public static final int VK_F22            = 0xF009;

  293.  

  294.     /** Constant for the F23 function key. */

  295.     public static final int VK_F23            = 0xF00A;

  296.  

  297.     /** Constant for the F24 function key. */

  298.     public static final int VK_F24            = 0xF00B;

  299.  

  300.     public static final int VK_PRINTSCREEN    = 0x9A;

  301.     public static final int VK_INSERT         = 0x9B;

  302.     public static final int VK_HELP           = 0x9C;

  303.     public static final int VK_META           = 0x9D;

  304. 

  305.     public static final int VK_BACK_QUOTE     = 0xC0;

  306.     public static final int VK_QUOTE          = 0xDE;

  307. 

  308.     /**  for KeyPad cursor arrow keys */

  309.     public static final int VK_KP_UP          = 0xE0;

  310.     public static final int VK_KP_DOWN        = 0xE1;

  311.     public static final int VK_KP_LEFT        = 0xE2;

  312.     public static final int VK_KP_RIGHT       = 0xE3;

  313.     

  314.     /* For European keyboards */

  315.     public static final int VK_DEAD_GRAVE               = 0x80;

  316.     public static final int VK_DEAD_ACUTE               = 0x81;

  317.     public static final int VK_DEAD_CIRCUMFLEX          = 0x82;

  318.     public static final int VK_DEAD_TILDE               = 0x83;

  319.     public static final int VK_DEAD_MACRON              = 0x84;

  320.     public static final int VK_DEAD_BREVE               = 0x85;

  321.     public static final int VK_DEAD_ABOVEDOT            = 0x86;

  322.     public static final int VK_DEAD_DIAERESIS           = 0x87;

  323.     public static final int VK_DEAD_ABOVERING           = 0x88;

  324.     public static final int VK_DEAD_DOUBLEACUTE         = 0x89;

  325.     public static final int VK_DEAD_CARON               = 0x8a;

  326.     public static final int VK_DEAD_CEDILLA             = 0x8b;

  327.     public static final int VK_DEAD_OGONEK              = 0x8c;

  328.     public static final int VK_DEAD_IOTA                = 0x8d;

  329.     public static final int VK_DEAD_VOICED_SOUND        = 0x8e;

  330.     public static final int VK_DEAD_SEMIVOICED_SOUND    = 0x8f;

  331. 

  332.     public static final int VK_AMPERSAND                = 0x96;

  333.     public static final int VK_ASTERISK                 = 0x97;

  334.     public static final int VK_QUOTEDBL                 = 0x98;

  335.     public static final int VK_LESS                     = 0x99;

  336. 

  337.     public static final int VK_GREATER                  = 0xa0;

  338.     public static final int VK_BRACELEFT                = 0xa1;

  339.     public static final int VK_BRACERIGHT               = 0xa2;

  340. 

  341.     /** Constant for the "@" key. */

  342.     public static final int VK_AT                       = 0x0200;

  343.  

  344.     /** Constant for the ":" key. */

  345.     public static final int VK_COLON                    = 0x0201;

  346.  

  347.     /** Constant for the "^" key. */

  348.     public static final int VK_CIRCUMFLEX               = 0x0202;

  349.  

  350.     /** Constant for the "$" key. */

  351.     public static final int VK_DOLLAR                   = 0x0203;

  352.  

  353.     /** Constant for the Euro currency sign key. */

  354.     public static final int VK_EURO_SIGN                = 0x0204;

  355.  

  356.     /** Constant for the "!" key. */

  357.     public static final int VK_EXCLAMATION_MARK         = 0x0205;

  358.  

  359.     /** Constant for the inverted exclamation mark key. */

  360.     public static final int VK_INVERTED_EXCLAMATION_MARK = 0x0206;

  361.  

  362.     /** Constant for the "(" key. */

  363.     public static final int VK_LEFT_PARENTHESIS         = 0x0207;

  364.  

  365.     /** Constant for the "#" key. */

  366.     public static final int VK_NUMBER_SIGN              = 0x0208;

  367.  

  368.     /** Constant for the "+" key. */

  369.     public static final int VK_PLUS                     = 0x0209;

  370.  

  371.     /** Constant for the ")" key. */

  372.     public static final int VK_RIGHT_PARENTHESIS        = 0x020A;

  373.  

  374.     /** Constant for the "_" key. */

  375.     public static final int VK_UNDERSCORE               = 0x020B;

  376.  

  377.     /* for input method support on Asian Keyboards */

  378.     public static final int VK_FINAL                    = 0x0018;

  379.     public static final int VK_CONVERT                  = 0x001C;

  380.     public static final int VK_NONCONVERT               = 0x001D;

  381.     public static final int VK_ACCEPT                   = 0x001E;

  382.     public static final int VK_MODECHANGE               = 0x001F;

  383.     public static final int VK_KANA                     = 0x0015;

  384.     public static final int VK_KANJI                    = 0x0019;

  385. 

  386.     /** Constant for the Alphanumeric function key. */

  387.     /* Japanese PC 106 keyboard */

  388.     public static final int VK_ALPHANUMERIC             = 0x00F0;

  389.  

  390.     /** Constant for the Katakana function key. */

  391.     /* Japanese PC 106 keyboard */

  392.     public static final int VK_KATAKANA                 = 0x00F1;

  393.  

  394.     /** Constant for the Hiragana function key. */

  395.     /* Japanese PC 106 keyboard */

  396.     public static final int VK_HIRAGANA                 = 0x00F2;

  397.  

  398.     /** Constant for the Full-Width Characters function key. */

  399.     /* Japanese PC 106 keyboard */

  400.     public static final int VK_FULL_WIDTH               = 0x00F3;

  401.  

  402.     /** Constant for the Half-Width Characters function key. */

  403.     /* Japanese PC 106 keyboard */

  404.     public static final int VK_HALF_WIDTH               = 0x00F4;

  405.  

  406.     /** Constant for the Roman Characters function key. */

  407.     /* Japanese PC 106 keyboard */

  408.     public static final int VK_ROMAN_CHARACTERS         = 0x00F5;

  409.  

  410.     /** Constant for the All Candidates function key. */

  411.     /* Japanese PC 106 keyboard - VK_CONVERT + ALT */

  412.     public static final int VK_ALL_CANDIDATES           = 0x0100;

  413.  

  414.     /** Constant for the Previous Candidate function key. */

  415.     /* Japanese PC 106 keyboard - VK_CONVERT + SHIFT */

  416.     public static final int VK_PREVIOUS_CANDIDATE       = 0x0101;

  417.  

  418.     /** Constant for the Code Input function key. */

  419.     /* Japanese PC 106 keyboard - VK_ALPHANUMERIC + ALT */

  420.     public static final int VK_CODE_INPUT               = 0x0102;

  421.  

  422.     /** Constant for the Japanese-Katakana function key.

  423.      *  This key switches to a Japanese input method and selects its Katakana input mode. */

  424.     /* Japanese Macintosh keyboard - VK_JAPANESE_HIRAGANA + SHIFT */

  425.     public static final int VK_JAPANESE_KATAKANA        = 0x0103;

  426.  

  427.     /** Constant for the Japanese-Hiragana function key.

  428.      *  This key switches to a Japanese input method and selects its Hiragana input mode. */

  429.     /* Japanese Macintosh keyboard */

  430.     public static final int VK_JAPANESE_HIRAGANA        = 0x0104;

  431.  

  432.     /** Constant for the Japanese-Roman function key.

  433.      *  This key switches to a Japanese input method and selects its Roman-Direct input mode. */

  434.     /* Japanese Macintosh keyboard */

  435.     public static final int VK_JAPANESE_ROMAN           = 0x0105;

  436.  

  437. 

  438.     /* for Sun keyboards */

  439.     public static final int VK_CUT                      = 0xFFD1;

  440.     public static final int VK_COPY                     = 0xFFCD;

  441.     public static final int VK_PASTE                    = 0xFFCF;

  442.     public static final int VK_UNDO                     = 0xFFCB;

  443.     public static final int VK_AGAIN                    = 0xFFC9;

  444.     public static final int VK_FIND                     = 0xFFD0;

  445.     public static final int VK_PROPS                    = 0xFFCA;

  446.     public static final int VK_STOP                     = 0xFFC8;

  447.     

  448.     /** Constant for the Compose function key. */

  449.     public static final int VK_COMPOSE                  = 0xFF20;

  450.  

  451.     /** Constant for the AltGraph modifier key. */

  452.     public static final int VK_ALT_GRAPH                = 0xFF7E;

  453. 

  454.     /**

  455.      * KEY_TYPED events do not have a keyCode value.

  456.      * This value is used, instead.  

  457.      */

  458.     public static final int VK_UNDEFINED      = 0x0;

  459. 

  460.     /**

  461.      * KEY_PRESSED and KEY_RELEASED events which do not map to a

  462.      * valid Unicode character use this for the keyChar value.

  463.      */

  464.     public static final char CHAR_UNDEFINED   = 0x0ffff;

  465. 

  466.     /**

  467.      * The unique value assigned to each of the keys on the

  468.      * keyboard.  There is a common set of key codes that

  469.      * can be fired by most keyboards.

  470.      * The symbolic name for a key code should be used rather

  471.      * than the code value itself.

  472.      *

  473.      * @serial

  474.      * @see getKeyCode()

  475.      * @see setKeyCode()

  476.      */

  477. 

  478.     int  keyCode;

  479.     /**

  480.      * <code>keyChar</code> is a valid unicode character

  481.      * that is fired by a key or a key combination on

  482.      * a keyboard.

  483.      *

  484.      * @serial

  485.      * @see getKeyChar()

  486.      * @see setKeyChar()

  487.      */

  488.     char keyChar;

  489. 

  490.     /*

  491.      * JDK 1.1 serialVersionUID 

  492.      */

  493.      private static final long serialVersionUID = -2352130953028126954L;

  494. 

  495.     static {

  496.         /* ensure that the necessary native libraries are loaded */

  497. 	NativeLibLoader.loadLibraries();

  498. 	initIDs();

  499.     }

  500. 

  501.     /**

  502.      * Initialize JNI field and method IDs for fields that may be

  503.        accessed from C.

  504.      */

  505.     private static native void initIDs();

  506. 

  507.     /**

  508.      * Constructs a KeyEvent object.

  509.      *

  510.      * @param source    the Component that originated the event

  511.      * @param id        an integer identifying the type of event

  512.      * @param when      a long integer that specifys the time the event occurred

  513.      * @param modifiers the modifier keys down during event 

  514.      *                  (shift, ctrl, alt, meta)

  515.      * @param keyCode   the integer code for an actual key, or VK_UNDEFINED 

  516.      *                  (for a key-typed event)

  517.      * @param keyChar   the Unicode character generated by this event, or 

  518.      *                  CHAR_UNDEFINED (for key-pressed and key-released

  519.      *                  events which do not map to a valid Unicode character)

  520.      */

  521.     public KeyEvent(Component source, int id, long when, int modifiers,

  522.                     int keyCode, char keyChar) {

  523.         super(source, id, when, modifiers);

  524. 

  525.         if (id == KEY_TYPED && keyChar == CHAR_UNDEFINED) {

  526.             throw new IllegalArgumentException("invalid keyChar");

  527.         }

  528.         if (id == KEY_TYPED && keyCode != VK_UNDEFINED) {

  529.             throw new IllegalArgumentException("invalid keyCode");

  530.         }

  531. 

  532.         this.keyCode = keyCode;

  533.         this.keyChar = keyChar;

  534.     }

  535. 

  536.     /*

  537.      * @deprecated, as of JDK1.1 - Do NOT USE; will be removed in 1.1.1.

  538.      */

  539.     public KeyEvent(Component source, int id, long when, int modifiers,

  540.                     int keyCode) {

  541.         this(source, id, when, modifiers, keyCode, (char)keyCode);

  542.     }

  543. 

  544.     /**

  545.      * Returns the integer key-code associated with the key in this event.

  546.      * 

  547.      * @return the integer code for an actual key on the keyboard. 

  548.      *         (For KEY_TYPED events, keyCode is VK_UNDEFINED.)

  549.      */

  550.     public int getKeyCode() {

  551.         return keyCode;

  552.     }

  553. 

  554.     /**

  555.      * Set the keyCode value to indicate a physical key.

  556.      *

  557.      * @param keyCode an integer corresponding to an actual key on the keyboard.

  558.      */

  559.     public void setKeyCode(int keyCode) {

  560.         this.keyCode = keyCode;

  561.     }

  562. 

  563.     /**

  564.      * Set the keyChar value to indicate a logical character.

  565.      *

  566.      * @param keyChar a char corresponding to to the combination of keystrokes

  567.      *                that make up this event.

  568.      */

  569.     public void setKeyChar(char keyChar) {

  570.         this.keyChar = keyChar;

  571.     }

  572. 

  573.     /**

  574.      * Set the modifiers to indicate additional keys that were held down

  575.      * (shift, ctrl, alt, meta) defined as part of InputEvent.

  576.      * <p>

  577.      * NOTE:  use of this method is not recommended, because many AWT

  578.      * implementations do not recognize modifier changes.  This is

  579.      * especially true for KEY_TYPED events where the shift modifier

  580.      * is changed.

  581.      *

  582.      * @param modifiers an integer combination of the modifier constants.

  583.      *

  584.      * @see InputEvent

  585.      *

  586.      * @deprecated, as of JDK1.1.4

  587.      */

  588.     public void setModifiers(int modifiers) {

  589.         this.modifiers = modifiers;

  590.     }

  591. 

  592.     /**

  593.      * Returns the character associated with the key in this event.

  594.      * For example, the key-typed event for shift + "a" returns the 

  595.      * value for "A".

  596.      *

  597.      * @return the Unicode character defined for this key event.

  598.      *         If no valid Unicode character exists for this key event, 

  599.      *         keyChar is CHAR_UNDEFINED.

  600.      */

  601.     public char getKeyChar() {

  602.         return keyChar;

  603.     }

  604. 

  605.     /**

  606.      * Returns a String describing the keyCode, such as "HOME", "F1" or "A".

  607.      * These strings can be localized by changing the awt.properties file.

  608.      *

  609.      * @return string a text description for a physical key, identified by

  610.      *                its keyCode

  611.      */

  612.     public static String getKeyText(int keyCode) {

  613.         if (keyCode >= VK_0 && keyCode <= VK_9 || 

  614.             keyCode >= VK_A && keyCode <= VK_Z) {

  615.             return String.valueOf((char)keyCode);

  616.         }

  617. 

  618.         // Check for other ASCII keyCodes.

  619.         int index = ",./;=[\\]".indexOf(keyCode);

  620.         if (index >= 0) {

  621.             return String.valueOf((char)keyCode);

  622.         }

  623. 	

  624.         switch(keyCode) {

  625.           case VK_ENTER: return Toolkit.getProperty("AWT.enter", "Enter");

  626.           case VK_BACK_SPACE: return Toolkit.getProperty("AWT.backSpace", "Backspace");

  627.           case VK_TAB: return Toolkit.getProperty("AWT.tab", "Tab");

  628.           case VK_CANCEL: return Toolkit.getProperty("AWT.cancel", "Cancel");

  629.           case VK_CLEAR: return Toolkit.getProperty("AWT.clear", "Clear");

  630.           case VK_SHIFT: return Toolkit.getProperty("AWT.shift", "Shift");

  631.           case VK_CONTROL: return Toolkit.getProperty("AWT.control", "Control");

  632.           case VK_ALT: return Toolkit.getProperty("AWT.alt", "Alt");

  633.           case VK_PAUSE: return Toolkit.getProperty("AWT.pause", "Pause");

  634.           case VK_CAPS_LOCK: return Toolkit.getProperty("AWT.capsLock", "Caps Lock");

  635.           case VK_ESCAPE: return Toolkit.getProperty("AWT.escape", "Escape");

  636.           case VK_SPACE: return Toolkit.getProperty("AWT.space", "Space");

  637.           case VK_PAGE_UP: return Toolkit.getProperty("AWT.pgup", "Page Up");

  638.           case VK_PAGE_DOWN: return Toolkit.getProperty("AWT.pgdn", "Page Down");

  639.           case VK_END: return Toolkit.getProperty("AWT.end", "End");

  640.           case VK_HOME: return Toolkit.getProperty("AWT.home", "Home");

  641.           case VK_LEFT: return Toolkit.getProperty("AWT.left", "Left");

  642.           case VK_UP: return Toolkit.getProperty("AWT.up", "Up");

  643.           case VK_RIGHT: return Toolkit.getProperty("AWT.right", "Right");

  644.           case VK_DOWN: return Toolkit.getProperty("AWT.down", "Down");

  645.           // handled by ASCII value above:

  646.           //   comma, period, slash, 0-9, semicolon, equals, A-Z,

  647.           //   open_bracket, back_slash, close_bracket

  648. 

  649.           // numpad numeric keys handled below

  650.           case VK_MULTIPLY: return Toolkit.getProperty("AWT.multiply", "NumPad *");

  651.           case VK_ADD: return Toolkit.getProperty("AWT.add", "NumPad +");

  652.           case VK_SEPARATER: return Toolkit.getProperty("AWT.separater", "NumPad ,");

  653.           case VK_SUBTRACT: return Toolkit.getProperty("AWT.subtract", "NumPad -");

  654.           case VK_DECIMAL: return Toolkit.getProperty("AWT.decimal", "NumPad .");

  655.           case VK_DIVIDE: return Toolkit.getProperty("AWT.divide", "NumPad /");

  656.           case VK_DELETE: return Toolkit.getProperty("AWT.delete", "Delete");

  657.           case VK_NUM_LOCK: return Toolkit.getProperty("AWT.numLock", "Num Lock");

  658.           case VK_SCROLL_LOCK: return Toolkit.getProperty("AWT.scrollLock", "Scroll Lock");

  659. 

  660.           case VK_F1: return Toolkit.getProperty("AWT.f1", "F1");

  661.           case VK_F2: return Toolkit.getProperty("AWT.f2", "F2");

  662.           case VK_F3: return Toolkit.getProperty("AWT.f3", "F3");

  663.           case VK_F4: return Toolkit.getProperty("AWT.f4", "F4");

  664.           case VK_F5: return Toolkit.getProperty("AWT.f5", "F5");

  665.           case VK_F6: return Toolkit.getProperty("AWT.f6", "F6");

  666.           case VK_F7: return Toolkit.getProperty("AWT.f7", "F7");

  667.           case VK_F8: return Toolkit.getProperty("AWT.f8", "F8");

  668.           case VK_F9: return Toolkit.getProperty("AWT.f9", "F9");

  669.           case VK_F10: return Toolkit.getProperty("AWT.f10", "F10");

  670.           case VK_F11: return Toolkit.getProperty("AWT.f11", "F11");

  671.           case VK_F12: return Toolkit.getProperty("AWT.f12", "F12");

  672.           case VK_F13: return Toolkit.getProperty("AWT.f13", "F13");

  673.           case VK_F14: return Toolkit.getProperty("AWT.f14", "F14");

  674.           case VK_F15: return Toolkit.getProperty("AWT.f15", "F15");

  675.           case VK_F16: return Toolkit.getProperty("AWT.f16", "F16");

  676.           case VK_F17: return Toolkit.getProperty("AWT.f17", "F17");

  677.           case VK_F18: return Toolkit.getProperty("AWT.f18", "F18");

  678.           case VK_F19: return Toolkit.getProperty("AWT.f19", "F19");

  679.           case VK_F20: return Toolkit.getProperty("AWT.f20", "F20");

  680.           case VK_F21: return Toolkit.getProperty("AWT.f21", "F21");

  681.           case VK_F22: return Toolkit.getProperty("AWT.f22", "F22");

  682.           case VK_F23: return Toolkit.getProperty("AWT.f23", "F23");

  683.           case VK_F24: return Toolkit.getProperty("AWT.f24", "F24");

  684. 

  685.           case VK_PRINTSCREEN: return Toolkit.getProperty("AWT.printScreen", "Print Screen");

  686.           case VK_INSERT: return Toolkit.getProperty("AWT.insert", "Insert");

  687.           case VK_HELP: return Toolkit.getProperty("AWT.help", "Help");

  688.           case VK_META: return Toolkit.getProperty("AWT.meta", "Meta");

  689.           case VK_BACK_QUOTE: return Toolkit.getProperty("AWT.backQuote", "Back Quote");

  690.           case VK_QUOTE: return Toolkit.getProperty("AWT.quote", "Quote");

  691. 			 

  692.           case VK_KP_UP: return Toolkit.getProperty("AWT.up", "Up");

  693.           case VK_KP_DOWN: return Toolkit.getProperty("AWT.down", "Down");

  694.           case VK_KP_LEFT: return Toolkit.getProperty("AWT.left", "Left");

  695.           case VK_KP_RIGHT: return Toolkit.getProperty("AWT.right", "Right");

  696. 

  697.           case VK_DEAD_GRAVE: return Toolkit.getProperty("AWT.deadGrave", "Dead Grave");

  698.           case VK_DEAD_ACUTE: return Toolkit.getProperty("AWT.deadAcute", "Dead Acute");

  699.           case VK_DEAD_CIRCUMFLEX: return Toolkit.getProperty("AWT.deadCircumflex", "Dead Circumflex");

  700.           case VK_DEAD_TILDE: return Toolkit.getProperty("AWT.deadTilde", "Dead Tilde");

  701.           case VK_DEAD_MACRON: return Toolkit.getProperty("AWT.deadMacron", "Dead Macron");

  702.           case VK_DEAD_BREVE: return Toolkit.getProperty("AWT.deadBreve", "Dead Breve");

  703.           case VK_DEAD_ABOVEDOT: return Toolkit.getProperty("AWT.deadAboveDot", "Dead Above Dot");

  704.           case VK_DEAD_DIAERESIS: return Toolkit.getProperty("AWT.deadDiaeresis", "Dead Diaeresis");

  705.           case VK_DEAD_ABOVERING: return Toolkit.getProperty("AWT.deadAboveRing", "Dead Above Ring");

  706.           case VK_DEAD_DOUBLEACUTE: return Toolkit.getProperty("AWT.deadDoubleAcute", "Dead Double Acute");

  707.           case VK_DEAD_CARON: return Toolkit.getProperty("AWT.deadCaron", "Dead Caron");

  708.           case VK_DEAD_CEDILLA: return Toolkit.getProperty("AWT.deadCedilla", "Dead Cedilla");

  709.           case VK_DEAD_OGONEK: return Toolkit.getProperty("AWT.deadOgonek", "Dead Ogonek");

  710.           case VK_DEAD_IOTA: return Toolkit.getProperty("AWT.deadIota", "Dead Iota");

  711.           case VK_DEAD_VOICED_SOUND: return Toolkit.getProperty("AWT.deadVoicedSound", "Dead Voiced Sound");

  712.           case VK_DEAD_SEMIVOICED_SOUND: return Toolkit.getProperty("AWT.deadSemivoicedSound", "Dead Semivoiced Sound");

  713. 

  714.           case VK_AMPERSAND: return Toolkit.getProperty("AWT.ampersand", "Ampersand");

  715.           case VK_ASTERISK: return Toolkit.getProperty("AWT.asterisk", "Asterisk");

  716.           case VK_QUOTEDBL: return Toolkit.getProperty("AWT.quoteDbl", "Double Quote");

  717.           case VK_LESS: return Toolkit.getProperty("AWT.Less", "Less");

  718.           case VK_GREATER: return Toolkit.getProperty("AWT.greater", "Greater");

  719.           case VK_BRACELEFT: return Toolkit.getProperty("AWT.braceLeft", "Left Brace");

  720.           case VK_BRACERIGHT: return Toolkit.getProperty("AWT.braceRight", "Right Brace");

  721.           case VK_AT: return Toolkit.getProperty("AWT.at", "At");

  722.           case VK_COLON: return Toolkit.getProperty("AWT.colon", "Colon");

  723.           case VK_CIRCUMFLEX: return Toolkit.getProperty("AWT.circumflex", "Circumflex");

  724.           case VK_DOLLAR: return Toolkit.getProperty("AWT.dollar", "Dollar");

  725.           case VK_EURO_SIGN: return Toolkit.getProperty("AWT.euro", "Euro");

  726.           case VK_EXCLAMATION_MARK: return Toolkit.getProperty("AWT.exclamationMark", "Exclamation Mark");

  727.           case VK_INVERTED_EXCLAMATION_MARK: return Toolkit.getProperty("AWT.invertedExclamationMark", "Inverted Exclamation Mark");

  728.           case VK_LEFT_PARENTHESIS: return Toolkit.getProperty("AWT.leftParenthesis", "Left Parenthesis");

  729.           case VK_NUMBER_SIGN: return Toolkit.getProperty("AWT.numberSign", "Number Sign");

  730.           case VK_MINUS: return Toolkit.getProperty("AWT.minus", "Minus");

  731.           case VK_PLUS: return Toolkit.getProperty("AWT.plus", "Plus");

  732.           case VK_RIGHT_PARENTHESIS: return Toolkit.getProperty("AWT.rightParenthesis", "Right Parenthesis");

  733.           case VK_UNDERSCORE: return Toolkit.getProperty("AWT.underscore", "Underscore");

  734. 

  735.           case VK_FINAL: return Toolkit.getProperty("AWT.final", "Final");

  736.           case VK_CONVERT: return Toolkit.getProperty("AWT.convert", "Convert");

  737.           case VK_NONCONVERT: return Toolkit.getProperty("AWT.noconvert", "No Convert");

  738.           case VK_ACCEPT: return Toolkit.getProperty("AWT.accept", "Accept");

  739.           case VK_MODECHANGE: return Toolkit.getProperty("AWT.modechange", "Mode Change");

  740. 	  case VK_KANA: return Toolkit.getProperty("AWT.kana", "Kana");

  741. 	  case VK_KANJI: return Toolkit.getProperty("AWT.kanji", "Kanji");

  742.           case VK_ALPHANUMERIC: return Toolkit.getProperty("AWT.alphanumeric", "Alphanumeric");

  743. 	  case VK_KATAKANA: return Toolkit.getProperty("AWT.katakana", "Katakana");

  744. 	  case VK_HIRAGANA: return Toolkit.getProperty("AWT.hiragana", "Hiragana");

  745. 	  case VK_FULL_WIDTH: return Toolkit.getProperty("AWT.fullWidth", "Full-Width");

  746. 	  case VK_HALF_WIDTH: return Toolkit.getProperty("AWT.halfWidth", "Half-Width");

  747. 	  case VK_ROMAN_CHARACTERS: return Toolkit.getProperty("AWT.romanCharacters", "Roman Characters");

  748. 	  case VK_ALL_CANDIDATES: return Toolkit.getProperty("AWT.allCandidates", "All Candidates");

  749. 	  case VK_PREVIOUS_CANDIDATE: return Toolkit.getProperty("AWT.previousCandidate", "Previous Candidate");

  750. 	  case VK_CODE_INPUT: return Toolkit.getProperty("AWT.codeInput", "Code Input");

  751. 	  case VK_JAPANESE_KATAKANA: return Toolkit.getProperty("AWT.japaneseKatakana", "Japanese Katakana");

  752. 	  case VK_JAPANESE_HIRAGANA: return Toolkit.getProperty("AWT.japaneseHiragana", "Japanese Hiragana");

  753. 	  case VK_JAPANESE_ROMAN: return Toolkit.getProperty("AWT.japaneseRoman", "Japanese Roman");

  754. 

  755.           case VK_AGAIN: return Toolkit.getProperty("AWT.again", "Again");

  756.           case VK_UNDO: return Toolkit.getProperty("AWT.undo", "Undo");

  757.           case VK_COPY: return Toolkit.getProperty("AWT.copy", "Copy");

  758.           case VK_PASTE: return Toolkit.getProperty("AWT.paste", "Paste");

  759.           case VK_CUT: return Toolkit.getProperty("AWT.cut", "Cut");

  760.           case VK_FIND: return Toolkit.getProperty("AWT.find", "Find");

  761.           case VK_PROPS: return Toolkit.getProperty("AWT.props", "Props");

  762.           case VK_STOP: return Toolkit.getProperty("AWT.stop", "Stop");

  763. 

  764.           case VK_COMPOSE: return Toolkit.getProperty("AWT.compose", "Compose");

  765.           case VK_ALT_GRAPH: return Toolkit.getProperty("AWT.altGraph", "Alt Graph");

  766.         }

  767. 

  768.         if (keyCode >= VK_NUMPAD0 && keyCode <= VK_NUMPAD9) {

  769.             String numpad = Toolkit.getProperty("AWT.numpad", "NumPad");

  770. 	    char c = (char)(keyCode - VK_NUMPAD0 + '0');

  771.             return numpad + "-" + c;

  772.         }

  773. 

  774.         String unknown = Toolkit.getProperty("AWT.unknown", "Unknown keyCode");

  775.         return unknown + ": 0x" + Integer.toString(keyCode, 16);

  776.     }

  777. 

  778.     /**

  779.      * Returns a String describing the modifier key(s), such as "Shift",

  780.      * or "Ctrl+Shift".  These strings can be localized by changing the 

  781.      * awt.properties file.

  782.      *

  783.      * @return string a text description of the combination of modifier

  784.      *                keys that were held down during the event

  785.      */

  786.     public static String getKeyModifiersText(int modifiers) {

  787.         StringBuffer buf = new StringBuffer();

  788.         if ((modifiers & InputEvent.META_MASK) != 0) {

  789.             buf.append(Toolkit.getProperty("AWT.meta", "Meta"));

  790.             buf.append("+");

  791.         }

  792.         if ((modifiers & InputEvent.CTRL_MASK) != 0) {

  793.             buf.append(Toolkit.getProperty("AWT.control", "Ctrl"));

  794.             buf.append("+");

  795.         }

  796.         if ((modifiers & InputEvent.ALT_MASK) != 0) {

  797.             buf.append(Toolkit.getProperty("AWT.alt", "Alt"));

  798.             buf.append("+");

  799.         }

  800.         if ((modifiers & InputEvent.SHIFT_MASK) != 0) {

  801.             buf.append(Toolkit.getProperty("AWT.shift", "Shift"));

  802.             buf.append("+");

  803.         }

  804.         if ((modifiers & InputEvent.ALT_GRAPH_MASK) != 0) {

  805.             buf.append(Toolkit.getProperty("AWT.altGraph", "Alt Graph"));

  806.             buf.append("+");

  807.         }

  808.         if (buf.length() > 0) {

  809.             buf.setLength(buf.length()-1); // remove trailing '+'

  810.         }

  811.         return buf.toString();

  812.     }

  813. 

  814.     /** Returns whether or not the key in this event is an "action" key,

  815.      *  as defined in Event.java.

  816.      *

  817.      * @return boolean value, true if the key is an "action" key

  818.      *

  819.      * @see Event

  820.      */

  821.     public boolean isActionKey() {

  822.         switch (keyCode) {

  823.           case VK_HOME:

  824.           case VK_END:

  825.           case VK_PAGE_UP:

  826.           case VK_PAGE_DOWN:

  827.           case VK_UP:

  828.           case VK_DOWN:

  829.           case VK_LEFT:

  830.           case VK_RIGHT:

  831. 

  832. 	  case VK_KP_LEFT: 

  833. 	  case VK_KP_UP: 

  834. 	  case VK_KP_RIGHT: 

  835. 	  case VK_KP_DOWN: 

  836. 

  837.           case VK_F1:

  838.           case VK_F2:

  839.           case VK_F3:

  840.           case VK_F4:

  841.           case VK_F5:

  842.           case VK_F6:

  843.           case VK_F7:

  844.           case VK_F8:

  845.           case VK_F9:

  846.           case VK_F10:

  847.           case VK_F11:

  848.           case VK_F12:

  849.           case VK_F13:

  850.           case VK_F14:

  851.           case VK_F15:

  852.           case VK_F16:

  853.           case VK_F17:

  854.           case VK_F18:

  855.           case VK_F19:

  856.           case VK_F20:

  857.           case VK_F21:

  858.           case VK_F22:

  859.           case VK_F23:

  860.           case VK_F24:

  861.           case VK_PRINTSCREEN:

  862.           case VK_SCROLL_LOCK:

  863.           case VK_CAPS_LOCK:

  864.           case VK_NUM_LOCK:

  865.           case VK_PAUSE:

  866.           case VK_INSERT:

  867. 

  868.           case VK_FINAL:

  869.           case VK_CONVERT:

  870.           case VK_NONCONVERT:

  871.           case VK_ACCEPT:

  872.           case VK_MODECHANGE:

  873. 	  case VK_KANA:

  874. 	  case VK_KANJI:

  875.           case VK_ALPHANUMERIC:

  876. 	  case VK_KATAKANA:

  877. 	  case VK_HIRAGANA:

  878. 	  case VK_FULL_WIDTH:

  879. 	  case VK_HALF_WIDTH:

  880. 	  case VK_ROMAN_CHARACTERS:

  881. 	  case VK_ALL_CANDIDATES:

  882. 	  case VK_PREVIOUS_CANDIDATE:

  883. 	  case VK_CODE_INPUT:

  884. 	  case VK_JAPANESE_KATAKANA:

  885. 	  case VK_JAPANESE_HIRAGANA:

  886. 	  case VK_JAPANESE_ROMAN:

  887. 

  888.           case VK_AGAIN:

  889.           case VK_UNDO:

  890.           case VK_COPY:

  891.           case VK_PASTE:

  892.           case VK_CUT:

  893.           case VK_FIND:

  894.           case VK_PROPS:

  895.           case VK_STOP:

  896. 

  897.           case VK_HELP:

  898.               return true;

  899.         }

  900.         return false;

  901.     }

  902. 

  903.     /**

  904.      * Returns a parameter string identifying this event.

  905.      * This method is useful for event-logging and for debugging.

  906.      *

  907.      * @return a string identifying the event and its attributes

  908.      */

  909.     public String paramString() {

  910.         String typeStr;

  911.         switch(id) {

  912.           case KEY_PRESSED:

  913.               typeStr = "KEY_PRESSED";

  914.               break;

  915.           case KEY_RELEASED:

  916.               typeStr = "KEY_RELEASED";

  917.               break;

  918.           case KEY_TYPED:

  919.               typeStr = "KEY_TYPED";

  920.               break;

  921.           default:

  922.               typeStr = "unknown type";

  923.         }

  924. 

  925.         String str = typeStr + ",keyCode=" + keyCode;

  926.         if (isActionKey() || keyCode == VK_ENTER || keyCode == VK_BACK_SPACE || 

  927. 	    keyCode == VK_TAB || keyCode == VK_ESCAPE || keyCode == VK_DELETE ||

  928. 	    (keyCode >= VK_NUMPAD0 && keyCode <= VK_NUMPAD9) ||

  929. 	    keyCode == VK_COMPOSE || keyCode == VK_ALT_GRAPH) {

  930.             str += "," + getKeyText(keyCode);

  931. 	} else if (keyChar == '\n' || keyChar == '\b' ||

  932. 	    keyChar == '\t' || keyChar == VK_ESCAPE || keyChar == VK_DELETE) {

  933.             str += "," + getKeyText(keyChar);

  934.         } else {

  935.             str += ",keyChar='" + keyChar + "'";

  936.         }

  937.         if (modifiers > 0) {

  938.             str += ",modifiers=" + getKeyModifiersText(modifiers);

  939.         }

  940.         return str;

  941.     }

  942. 

  943. }