/*

 * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.awt.event;

import java.awt.Component;

import java.awt.GraphicsEnvironment;

import java.awt.Toolkit;

import java.io.IOException;

import java.io.ObjectInputStream;

import sun.awt.AWTAccessor;

/**

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

 * <p>

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

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

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

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

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

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

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

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

 * <p>

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

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

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

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

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

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

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

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

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

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

 * No key typed events are generated for keys that don't generate Unicode

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

 * <p>

 * The getKeyChar method always returns a valid Unicode character or

 * CHAR_UNDEFINED.  Character input is reported by KEY_TYPED events:

 * KEY_PRESSED and KEY_RELEASED events are not necessarily associated

 * with character input.  Therefore, the result of the getKeyChar method

 * is guaranteed to be meaningful only for KEY_TYPED events.

 * <p>

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

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

 * always returns {@code VK_UNDEFINED}. The {@code getExtendedKeyCode} method

 * may also be used with many international keyboard layouts.

 *

 * <p>

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

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

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

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

 * being pressed or released is indicated by the {@code getKeyCode} and {@code getExtendedKeyCode}

 * methods, which return a virtual key code.

 *

 * <p>

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

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

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

 *

 * <p>

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

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

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

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

 * value of 'A' is generated.

 *

 * <p>

 * Pressing and releasing a key on the keyboard results in the generating

 * the following key events (in order):

 * <PRE>

 *    {@code KEY_PRESSED}

 *    {@code KEY_TYPED} (is only generated if a valid Unicode character could be generated.)

 *    {@code KEY_RELEASED}

 * </PRE>

 *

 * But in some cases (e.g. auto-repeat or input method is activated) the order

 * could be different (and platform dependent).

 *

 * <p>

 * Notes:

 * <ul>

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

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

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

 * virtual key codes.  No attempt is made in Java to generate these keys

 * artificially.

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

 * platform and keyboard layout. For example, the key that generates VK_Q

 * when using a U.S. keyboard layout will generate VK_A when using a French

 * keyboard layout.

 * <li>The key that generates {@code VK_Q} when using a U.S. keyboard layout also

 * generates a unique code for Russian or Hebrew layout. There is no a

 * {@code VK_} constant for these and many other codes in various layouts. These codes

 * may be obtained by using {@code getExtendedKeyCode} and are used whenever

 * a {@code VK_} constant is used.

 * <li>Not all characters have a keycode associated with them.  For example,

 * there is no keycode for the question mark because there is no keyboard

 * for which it appears on the primary layer.

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

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

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

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

 * is returned instead of VK_CONVERT with the ALT modifier.

 * <li>As specified in <a href="../doc-files/FocusSpec.html">Focus Specification</a>

 * key events are dispatched to the focus owner by default.

 * </ul>

 *

 * <p>

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

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

 * constants.  The platform steward reserves the right to change these values as needed

 * to accommodate a wider range of keyboards in the future.

 * <p>

 * An unspecified behavior will be caused if the {@code id} parameter

 * of any particular {@code KeyEvent} instance is not

 * in the range from {@code KEY_FIRST} to {@code KEY_LAST}.

 *

 * @author Carl Quinn

 * @author Amy Fowler

 * @author Norbert Lindenberg

 *

 * @see KeyAdapter

 * @see KeyListener

 * @see <a href="http://docs.oracle.com/javase/tutorial/uiswing/events/keylistener.html">Tutorial: Writing a Key Listener</a>

 *

 * @since 1.1

 */

public class KeyEvent extends InputEvent {

    /**

     * Stores the state of native event dispatching system

     * - true, if when the event was created event proxying

     *         mechanism was active

     * - false, if it was inactive

     * Used in Component.dispatchEventImpl to correctly dispatch

     * events when proxy is active

     */

    private boolean isProxyActive = false;

    /**

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

     */

    public static final int KEY_FIRST = 400;

    /**

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

     */

    public static final int KEY_LAST  = 402;

    /**

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

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

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

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

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

     */

    public static final int KEY_TYPED = KEY_FIRST;

    /**

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

     * is pushed down.

     */

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

    /**

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

     * is let up.

     */

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

    /* Virtual key codes. */

    /** Constant for the ENTER virtual key. */

    public static final int VK_ENTER          = '\n';

    /** Constant for the BACK_SPACE virtual key. */

    public static final int VK_BACK_SPACE     = '\b';

    /** Constant for the TAB virtual key. */

    public static final int VK_TAB            = '\t';

    /** Constant for the CANCEL virtual key. */

    public static final int VK_CANCEL         = 0x03;

    /** Constant for the CLEAR virtual key. */

    public static final int VK_CLEAR          = 0x0C;

    /** Constant for the SHIFT virtual key. */

    public static final int VK_SHIFT          = 0x10;

    /** Constant for the CONTROL virtual key. */

    public static final int VK_CONTROL        = 0x11;

    /** Constant for the ALT virtual key. */

    public static final int VK_ALT            = 0x12;

    /** Constant for the PAUSE virtual key. */

    public static final int VK_PAUSE          = 0x13;

    /** Constant for the CAPS_LOCK virtual key. */

    public static final int VK_CAPS_LOCK      = 0x14;

    /** Constant for the ESCAPE virtual key. */

    public static final int VK_ESCAPE         = 0x1B;

    /** Constant for the SPACE virtual key. */

    public static final int VK_SPACE          = 0x20;

    /** Constant for the PAGE_UP virtual key. */

    public static final int VK_PAGE_UP        = 0x21;

    /** Constant for the PAGE_DOWN virtual key. */

    public static final int VK_PAGE_DOWN      = 0x22;

    /** Constant for the END virtual key. */

    public static final int VK_END            = 0x23;

    /** Constant for the HOME virtual key. */

    public static final int VK_HOME           = 0x24;

    /**

     * Constant for the non-numpad <b>left</b> arrow key.

     * @see #VK_KP_LEFT

     */

    public static final int VK_LEFT           = 0x25;

    /**

     * Constant for the non-numpad <b>up</b> arrow key.

     * @see #VK_KP_UP

     */

    public static final int VK_UP             = 0x26;

    /**

     * Constant for the non-numpad <b>right</b> arrow key.

     * @see #VK_KP_RIGHT

     */

    public static final int VK_RIGHT          = 0x27;

    /**

     * Constant for the non-numpad <b>down</b> arrow key.

     * @see #VK_KP_DOWN

     */

    public static final int VK_DOWN           = 0x28;

    /**

     * Constant for the comma key, ","

     */

    public static final int VK_COMMA          = 0x2C;

    /**

     * Constant for the minus key, "-"

     * @since 1.2

     */

    public static final int VK_MINUS          = 0x2D;

    /**

     * Constant for the period key, "."

     */

    public static final int VK_PERIOD         = 0x2E;

    /**

     * Constant for the forward slash key, "/"

     */

    public static final int VK_SLASH          = 0x2F;

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

    /** Constant for the "0" key. */

    public static final int VK_0              = 0x30;

    /** Constant for the "1" key. */

    public static final int VK_1              = 0x31;

    /** Constant for the "2" key. */

    public static final int VK_2              = 0x32;

    /** Constant for the "3" key. */

    public static final int VK_3              = 0x33;

    /** Constant for the "4" key. */

    public static final int VK_4              = 0x34;

    /** Constant for the "5" key. */

    public static final int VK_5              = 0x35;

    /** Constant for the "6" key. */

    public static final int VK_6              = 0x36;

    /** Constant for the "7" key. */

    public static final int VK_7              = 0x37;

    /** Constant for the "8" key. */

    public static final int VK_8              = 0x38;

    /** Constant for the "9" key. */

    public static final int VK_9              = 0x39;

    /**

     * Constant for the semicolon key, ";"

     */

    public static final int VK_SEMICOLON      = 0x3B;

    /**

     * Constant for the equals key, "="

     */

    public static final int VK_EQUALS         = 0x3D;

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

    /** Constant for the "A" key. */

    public static final int VK_A              = 0x41;

    /** Constant for the "B" key. */

    public static final int VK_B              = 0x42;

    /** Constant for the "C" key. */

    public static final int VK_C              = 0x43;

    /** Constant for the "D" key. */

    public static final int VK_D              = 0x44;

    /** Constant for the "E" key. */

    public static final int VK_E              = 0x45;

    /** Constant for the "F" key. */

    public static final int VK_F              = 0x46;

    /** Constant for the "G" key. */

    public static final int VK_G              = 0x47;

    /** Constant for the "H" key. */

    public static final int VK_H              = 0x48;

    /** Constant for the "I" key. */

    public static final int VK_I              = 0x49;

    /** Constant for the "J" key. */

    public static final int VK_J              = 0x4A;

    /** Constant for the "K" key. */

    public static final int VK_K              = 0x4B;

    /** Constant for the "L" key. */

    public static final int VK_L              = 0x4C;

    /** Constant for the "M" key. */

    public static final int VK_M              = 0x4D;

    /** Constant for the "N" key. */

    public static final int VK_N              = 0x4E;

    /** Constant for the "O" key. */

    public static final int VK_O              = 0x4F;

    /** Constant for the "P" key. */

    public static final int VK_P              = 0x50;

    /** Constant for the "Q" key. */

    public static final int VK_Q              = 0x51;

    /** Constant for the "R" key. */

    public static final int VK_R              = 0x52;

    /** Constant for the "S" key. */

    public static final int VK_S              = 0x53;

    /** Constant for the "T" key. */

    public static final int VK_T              = 0x54;

    /** Constant for the "U" key. */

    public static final int VK_U              = 0x55;

    /** Constant for the "V" key. */

    public static final int VK_V              = 0x56;

    /** Constant for the "W" key. */

    public static final int VK_W              = 0x57;

    /** Constant for the "X" key. */

    public static final int VK_X              = 0x58;

    /** Constant for the "Y" key. */

    public static final int VK_Y              = 0x59;

    /** Constant for the "Z" key. */

    public static final int VK_Z              = 0x5A;

    /**

     * Constant for the open bracket key, "["

     */

    public static final int VK_OPEN_BRACKET   = 0x5B;

    /**

     * Constant for the back slash key, "\"

     */

    public static final int VK_BACK_SLASH     = 0x5C;

    /**

     * Constant for the close bracket key, "]"

     */

    public static final int VK_CLOSE_BRACKET  = 0x5D;

    /** Constant for the number pad "0" key. */

    public static final int VK_NUMPAD0        = 0x60;

    /** Constant for the number pad "1" key. */

    public static final int VK_NUMPAD1        = 0x61;

    /** Constant for the number pad "2" key. */

    public static final int VK_NUMPAD2        = 0x62;

    /** Constant for the number pad "3" key. */

    public static final int VK_NUMPAD3        = 0x63;

    /** Constant for the number pad "4" key. */

    public static final int VK_NUMPAD4        = 0x64;

    /** Constant for the number pad "5" key. */

    public static final int VK_NUMPAD5        = 0x65;

    /** Constant for the number pad "6" key. */

    public static final int VK_NUMPAD6        = 0x66;

    /** Constant for the number pad "7" key. */

    public static final int VK_NUMPAD7        = 0x67;

    /** Constant for the number pad "8" key. */

    public static final int VK_NUMPAD8        = 0x68;

    /** Constant for the number pad "9" key. */

    public static final int VK_NUMPAD9        = 0x69;

    /** Constant for the number pad multiply key. */

    public static final int VK_MULTIPLY       = 0x6A;

    /** Constant for the number pad add key. */

    public static final int VK_ADD            = 0x6B;

    /**

     * This constant is obsolete, and is included only for backwards

     * compatibility.

     * @see #VK_SEPARATOR

     */

    public static final int VK_SEPARATER      = 0x6C;

    /**

     * Constant for the Numpad Separator key.

     * @since 1.4

     */

    public static final int VK_SEPARATOR      = VK_SEPARATER;

    /** Constant for the number pad subtract key. */

    public static final int VK_SUBTRACT       = 0x6D;

    /** Constant for the number pad decimal point key. */

    public static final int VK_DECIMAL        = 0x6E;

    /** Constant for the number pad divide key. */

    public static final int VK_DIVIDE         = 0x6F;

    /** Constant for the delete key. */

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

    /** Constant for the NUM_LOCK key. */

    public static final int VK_NUM_LOCK       = 0x90;

    /** Constant for the SCROLL_LOCK key. */

    public static final int VK_SCROLL_LOCK    = 0x91;

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

    public static final int VK_F1             = 0x70;

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

    public static final int VK_F2             = 0x71;

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

    public static final int VK_F3             = 0x72;

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

    public static final int VK_F4             = 0x73;

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

    public static final int VK_F5             = 0x74;