mozilla
Your Search Results

    KeyboardEvent

    KeyboardEvent objects describe a user interaction with the keyboard. Each event describes a key; the event type (keydown, keypress, or keyup) identifies what kind of activity was performed.

    Note: The KeyboardEvent indicates just what's happening on a key. When you need to handle text input, use HTML5 input event instead. For example, if user inputs text from hand-writing system like tablet PC, key events may not be fired.

    Constructor

    KeyboardEvent()
    Creates a KeyboardEvent object.

    Methods

    This interface also inherits methods of its parents, UIEvent and Event.

    KeyboardEvent.getModifierState()
    Returns a Boolean indicating if the modifier key, like AltShiftCtrl, or Meta, was pressed when the event was created.
    KeyboardEvent.initKeyEvent()
    Initializes a KeyboardEvent object. This has only been implemented by Gecko (others used KeyboardEvent.initKeyboardEvent()) and should not be used any more. The standard modern way is to use the KeyboardEvent() constructor.
    KeyboardEvent.initKeyboardEvent()
    Initializes a KeyboardEvent object. This has never been implemented by Gecko (who used KeyboardEvent.initKeyEvent()) and should not be used any more. The standard modern way is to use the KeyboardEvent() constructor.

    Properties

    This interface also inherits properties of its parents, UIEvent and Event.

    KeyboardEvent.altKey Read only
    Returns a Boolean that is true if the Alt ( Option or on OS X) key was active when the key event was generated.
    KeyboardEvent.char Read only
    Returns a DOMString representing the character value of the key. If the key corresponds to a printable character, this value is a non-empty Unicode string containing that character. If the key doesn't have a printable representation, this is an empty string.
    Note: If the key is used as a macro that inserts multiple characters, this attribute's value is the entire string, not just the first character.
    Warning: This has been dropped from DOM Level 3 Events. This is supported only on IE.
    KeyboardEvent.charCode Read only
    Returns an unsigned long representing the Unicode reference number of the key; this attribute is used only by the keypress event. For keys whose char attribute contains multiple characters, this is the Unicode value of the first character in that attribute. In Firefox 26 this returns codes for printable characters.
    Warning: This attribute is deprecated; you should use key instead, if available.
    KeyboardEvent.code Read only
    Returns a DOMString with the code value of the key represented by the event.
    KeyboardEvent.ctrlKey Read only
    Returns a Boolean that is true if the Ctrl key was active when the key event was generated.
    KeyboardEvent.isComposing Read only
    Returns a Boolean that is true if the event is fired between after compositionstart and before compositionend.
    KeyboardEvent.key Read only
    Returns a DOMString representing the key value of the key represented by the event.
    KeyboardEvent.keyCode  Read only
    Returns an unsigned long representing a system and implementation dependent numerical code identifying the unmodified value of the pressed key.
    Warning: This attribute is deprecated; you should use key instead, if available.
    KeyboardEvent.locale Read only
    Returns a DOMString representing a locale string indicating the locale the keyboard is configured for. This may be the empty string if the browser or device doesn't know the keyboard's locale.
    Note: This does not describe the locale of the data being entered. A user may be using one keyboard layout while typing text in a different language.
    KeyboardEvent.location Read only
    Returns an unsigned long representing the location of the key on the keyboard or other input device.
    KeyboardEvent.metaKey Read only
    Returns a Boolean that is true if the Meta (or Command on OS X) key was active when the key event was generated.
    KeyboardEvent.repeat Read only
    Returns a Boolean that is true if the key is being held down such that it is automatically repeating.
    KeyboardEvent.shiftKey Read only
    Returns a Boolean that is true if the Shift key was active when the key event was generated.
    KeyboardEvent.which Read only
    Returns an unsigned long representing a system and implementation dependent numeric code identifying the unmodified value of the pressed key; this is usually the same as keyCode.
    Warning: This attribute is deprecated; you should use key instead, if available.

    Notes

    There are keydown, keypress, and keyup events. For most keys, Gecko dispatches a sequence of key events like this:

    1. When the key is first depressed, the keydown event is sent.
    2. If the key is not a modifier key, the keypress event is sent.
    3. When the user releases the key, the keyup event is sent.

    Special cases

    Certain keys toggle the state of an LED indicator, such as Caps Lock, Num Lock, and Scroll Lock. On Windows and Linux, these keys dispatch only the keydown and keyup events. Note that on Linux, Firefox 12 and earlier also dispatched the keypress event for these keys.

    On Mac, however, Caps Lock dispatches only the keydown event due to a platform event model limitation. Num Lock had been supported on old MacBook (2007 model and older) but Mac hasn't supported Num Lock feature even on external keyboards in these days. On the old MacBook which has Num Lock key, Num Lock doesn't cause any key events. And Gecko supports Scroll Lock key if an external keyboard which has F14 is connected. However, it generates keypress event. This inconsistent behavior is a bug; see bug 602812.

    Auto-repeat handling

    When a key is pressed and held down, it begins to auto-repeat. This results in a sequence of events similar to the following being dispatched:

    1. keydown
    2. keypress
    3. keydown
    4. keypress
    5. <<repeating until the user releases the key>>
    6. keyup

    This is what the DOM Level 3 specification says should happen. There are some caveats, however, as described below.

    Auto-repeat on some GTK environments such as Ubuntu 9.4

    In some GTK-based environments, auto-repeat dispatches a native key-up event automatically during auto-repeat, and there's no way for Gecko to know the difference between a repeated series of keypresses and an auto-repeat. On those platforms, then, an auto-repeat key will generate the following sequence of events:

    1. keydown
    2. keypress
    3. keyup
    4. keydown
    5. keypress
    6. keyup
    7. <<repeating until the user releases the key>>
    8. keyup

    In these environments, unfortunately, there's no way for web content to tell the difference between auto-repeating keys and keys that are just being pressed repeatedly.

    Auto-repeat handling prior to Gecko 4.0

    Before Gecko 4.0 , keyboard handling was less consistent across platforms.

    Windows
    Auto-repeat behavior is the same as in Gecko 4.0 and later.
    Mac
    After the initial keydown event, only keypress events are sent until the keyup event occurs; the inter-spaced keydown events are not sent.
    Linux
    The event behavior depends on the specific platform. It will either behave like Windows or Mac depending on what the native event model does.

    Example

    <!DOCTYPE html>
    <html>
    <head>
    <script>
    var metaChar = false;
    var exampleKey = 16;
    
    function keyEvent(event) {
      var key = event.keyCode || event.which;
      var keychar = String.fromCharCode(key);
      if (key == exampleKey) {
        metaChar = true;
      }
      if (key != exampleKey) {
        if (metaChar) {
          alert("Combination of metaKey + " + keychar);
          metaChar = false;
        } else {
          alert("Key pressed " + key);
        }
      }
    }
    
    function metaKeyUp (event) {
      var key = event.keyCode || event.which;
    
      if (key == exampleKey) {
        metaChar = false;
      }
    }
    </script>
    </head>
    
    <body onkeydown="keyEvent(event)" onkeyup="metaKeyUp(event)">
    </body>
    </html>
    

    Specifications

    Specification Status Comment
    Document Object Model (DOM) Level 3 Events Specification
    The definition of 'KeyboardEvent' in that specification.
    Working Draft Initial definition.

    The KeyboardEvent interface specification went through numerous draft versions, first under DOM Events Level 2 where it was dropped as no consensus arose, then under DOM Events Level 3. This led to the implementation of non-standard initialization methods, the early DOM Events Level 2 version, KeyboardEvent.initKeyEvent() by Gecko browsers and the early DOM Events Level 3 version, KeyboardEvent.initKeyboardEvent() by others. Both have been superseded by the modern usage of a constructor: KeyboardEvent().

    Browser compatibility

    Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
    Basic support (Yes) (Yes) (Yes) (Yes) (Yes)
    constructor (Yes) 31.0 (31.0) Not supported (Yes) ?
    .char Not supported Not supported (Yes) Not supported Not supported
    .charCode (Yes) (Yes) (Yes) (Yes) (Yes)
    .code See Browser compatibility of KeyboardEvent.code.
    .isComposing Not supported 31.0 (31.0) Not supported Not supported Not supported
    .key See Browser compatibility of KeyboardEvent.key.
    .keyCode (Yes) (Yes) (Yes) (Yes) (Yes)
    .locale Not supported Not supported (Yes) Not supported Not supported
    .location (Yes) 15.0 (15.0) (Yes) Not supported Not supported
    .repeat (Yes) 28.0 (28.0) (Yes) Not supported Not supported
    .which (Yes) (Yes) (Yes) (Yes) (Yes)
    .getModifierState() See Browser compatibility of KeyboardEvent.getModifierState
    .initKeyboardEvent() (Yes) *1 Not supported *2 9.0 *3 ? (Yes) *1
    Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
    Basic support ? (Yes) ? ? ?
    constructor ? 31.0 (31.0) ? ? ?
    .char ? Not supported ? ? ?
    .charCode ? (Yes) ? ? ?
    .code See Browser compatibility of KeyboardEvent.code.
    .isComposing Not supported 31.0 (31.0) Not supported Not supported Not supported
    .key See Browser compatibility table of KeyboardEvent.key.
    .keyCode ? (Yes) ? ? ?
    .locale ? Not supported ? ? ?
    .location ? 15.0 (15.0) ? ? ?
    .repeat ? 28.0 (28.0) ? ? ?
    .which ? (Yes) ? ? ?
    .getModifierState() See Browser compatibility of KeyboardEvent.getModifierState
    .initKeyboardEvent() ? Not supported ? ? ?


    *1 The arguments of initKeyboardEvent() of WebKit and Blink's are different from the definition in DOM Level 3 Events. The method is: initKeyboardEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg,  in views::AbstractView viewArg, in DOMString keyIndentifierArg, in unsigned long locationArg, in boolean ctrlKeyArg, in boolean altKeyArg, in boolean shiftKeyArg, in boolean metaKeyArg, in boolean altGraphKeyArg)

    *2 Gecko won't support initKeyboardEvent() because supporting it completely breaks feature detection of web applications. See bug 999645.

    *3 The argument of initKeyboardEvent() of IE is different from the definition in DOM Level 3 Events. The method is: initKeyboardEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString keyArg, in unsigned long locationArg, in DOMString modifierListArg, in boolean repeatArt, in DOMString locationArg). See document of initKeyboardEvent() in MSDN.

    Document Tags and Contributors

    Last updated by: fscholz,