1.2.1. Key events

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "KeyEvents" and "3.0" (respectively) to determine whether or not the Mouse event module is supported by the implementation. In order to fully support this module, an implementation must also support the "UIEvents" feature defined in this specification. Please, refer to additional information about conformance in the DOM Level 3 Core specification .

Note: To create an instance of the KeyEvent interface, use the feature string "KeyEvents" as the value of the input parameter used with the createEvent method of the DocumentEvent interface.

Interface KeyEvent (introduced in DOM Level 3)

The KeyEvent interface provides specific contextual information associated with Key Events.

The detail attribute inherited from UIEvent is used to indicated the number of keypresses which have occurred during key repetition. If this information is not available this value should be 0.

IDL Definition

// Introduced in DOM Level 3:
interface KeyEvent : UIEvent {

  // VirtualKeyCode
  const unsigned long       DOM_VK_UNDEFINED               = 0x0;
  const unsigned long       DOM_VK_RIGHT_ALT               = 0x01;
  const unsigned long       DOM_VK_LEFT_ALT                = 0x02;
  const unsigned long       DOM_VK_LEFT_CONTROL            = 0x03;
  const unsigned long       DOM_VK_RIGHT_CONTROL           = 0x04;
  const unsigned long       DOM_VK_LEFT_SHIFT              = 0x05;
  const unsigned long       DOM_VK_RIGHT_SHIFT             = 0x06;
  const unsigned long       DOM_VK_LEFT_META               = 0x07;
  const unsigned long       DOM_VK_RIGHT_META              = 0x08;
  const unsigned long       DOM_VK_CAPS_LOCK               = 0x09;
  const unsigned long       DOM_VK_DELETE                  = 0x0A;
  const unsigned long       DOM_VK_END                     = 0x0B;
  const unsigned long       DOM_VK_ENTER                   = 0x0C;
  const unsigned long       DOM_VK_ESCAPE                  = 0x0D;
  const unsigned long       DOM_VK_HOME                    = 0x0E;
  const unsigned long       DOM_VK_INSERT                  = 0x0F;
  const unsigned long       DOM_VK_NUM_LOCK                = 0x10;
  const unsigned long       DOM_VK_PAUSE                   = 0x11;
  const unsigned long       DOM_VK_PRINTSCREEN             = 0x12;
  const unsigned long       DOM_VK_SCROLL_LOCK             = 0x13;
  const unsigned long       DOM_VK_LEFT                    = 0x14;
  const unsigned long       DOM_VK_RIGHT                   = 0x15;
  const unsigned long       DOM_VK_UP                      = 0x16;
  const unsigned long       DOM_VK_DOWN                    = 0x17;
  const unsigned long       DOM_VK_PAGE_DOWN               = 0x18;
  const unsigned long       DOM_VK_PAGE_UP                 = 0x19;
  const unsigned long       DOM_VK_F1                      = 0x1A;
  const unsigned long       DOM_VK_F2                      = 0x1B;
  const unsigned long       DOM_VK_F3                      = 0x1C;
  const unsigned long       DOM_VK_F4                      = 0x1D;
  const unsigned long       DOM_VK_F5                      = 0x1E;
  const unsigned long       DOM_VK_F6                      = 0x1F;
  const unsigned long       DOM_VK_F7                      = 0x20;
  const unsigned long       DOM_VK_F8                      = 0x21;
  const unsigned long       DOM_VK_F9                      = 0x22;
  const unsigned long       DOM_VK_F10                     = 0x23;
  const unsigned long       DOM_VK_F11                     = 0x24;
  const unsigned long       DOM_VK_F12                     = 0x25;
  const unsigned long       DOM_VK_F13                     = 0x26;
  const unsigned long       DOM_VK_F14                     = 0x27;
  const unsigned long       DOM_VK_F15                     = 0x28;
  const unsigned long       DOM_VK_F16                     = 0x29;
  const unsigned long       DOM_VK_F17                     = 0x2A;
  const unsigned long       DOM_VK_F18                     = 0x2B;
  const unsigned long       DOM_VK_F19                     = 0x2C;
  const unsigned long       DOM_VK_F20                     = 0x2D;
  const unsigned long       DOM_VK_F21                     = 0x2E;
  const unsigned long       DOM_VK_F22                     = 0x2F;
  const unsigned long       DOM_VK_F23                     = 0x30;
  const unsigned long       DOM_VK_F24                     = 0x31;

           attribute DOMString        outputString;
           attribute unsigned long    keyVal;
           attribute unsigned long    virtKeyVal;
           attribute boolean          inputGenerated;
           attribute boolean          numPad;
  boolean            checkModifier(in unsigned long modifer);
  void               initKeyEvent(in DOMString typeArg, 
                                  in boolean canBubbleArg, 
                                  in boolean cancelableArg, 
                                  in views::AbstractView viewArg, 
                                  in unsigned short detailArg, 
                                  in DOMString outputStringArg, 
                                  in unsigned long keyValArg, 
                                  in unsigned long virtKeyValArg, 
                                  in boolean inputGeneratedArg, 
                                  in boolean numPadArg);
  void               initModifier(in unsigned long modifier, 
                                  in boolean value);
};

Definition group VirtualKeyCode

An integer indicating which key was pressed.

Defined Constants

DOM_VK_CAPS_LOCK

DOM_VK_DELETE

DOM_VK_DOWN

DOM_VK_END

DOM_VK_ENTER

DOM_VK_ESCAPE

DOM_VK_F1

Constant for the F1 function key.

DOM_VK_F10

Constant for the F10 function key.

DOM_VK_F11

Constant for the F11 function key.

DOM_VK_F12

Constant for the F12 function key.

DOM_VK_F13

Constant for the F13 function key.

DOM_VK_F14

Constant for the F14 function key.

DOM_VK_F15

Constant for the F15 function key.

DOM_VK_F16

Constant for the F16 function key.

DOM_VK_F17

Constant for the F17 function key.

DOM_VK_F18

Constant for the F18 function key.

DOM_VK_F19

Constant for the F19 function key.

DOM_VK_F2

Constant for the F2 function key.

DOM_VK_F20

Constant for the F20 function key.

DOM_VK_F21

Constant for the F21 function key.

DOM_VK_F22

Constant for the F22 function key.

DOM_VK_F23

Constant for the F23 function key.

DOM_VK_F24

Constant for the F24 function key.

DOM_VK_F3

Constant for the F3 function key.

DOM_VK_F4

Constant for the F4 function key.

DOM_VK_F5

Constant for the F5 function key.

DOM_VK_F6

Constant for the F6 function key.

DOM_VK_F7

Constant for the F7 function key.

DOM_VK_F8

Constant for the F8 function key.

DOM_VK_F9

Constant for the F9 function key.

DOM_VK_HOME

DOM_VK_INSERT

DOM_VK_LEFT

DOM_VK_LEFT_ALT

This key is a modifier key

DOM_VK_LEFT_CONTROL

This key is a modifier key

DOM_VK_LEFT_META

This key is a modifier key

DOM_VK_LEFT_SHIFT

This key is a modifier key

DOM_VK_NUM_LOCK

DOM_VK_PAGE_DOWN

DOM_VK_PAGE_UP

DOM_VK_PAUSE

DOM_VK_PRINTSCREEN

DOM_VK_RIGHT

DOM_VK_RIGHT_ALT

This key is a modifier key

DOM_VK_RIGHT_CONTROL

This key is a modifier key

DOM_VK_RIGHT_META

This key is a modifier key

DOM_VK_RIGHT_SHIFT

This key is a modifier key

DOM_VK_SCROLL_LOCK

DOM_VK_UNDEFINED

Used for key events which do not have a virtual key code available.

DOM_VK_UP

Attributes

inputGenerated of type boolean

The inputGenerated attribute indicates whether the key event will normally cause visible output. If the key event does not generate any visible output, such as the use of a function key or the combination of certain modifier keys used in conjunction with another key, then the value will be false. If visible output is normally generated by the key event then the value will be true.
The value of inputGenerated does not guarantee the creation of a character. If a key event causing visible output is cancelable it may be prevented from causing output. This attribute is intended primarily to differentiate between keys events which may or may not produce visible output depending on the system state.

keyVal of type unsigned long

The value of keyVal holds the value of the Unicode character associated with the depressed key. If the key has no Unicode representation or no Unicode character is available the value is 0..

numPad of type boolean

The numPad attribute indicates whether or not the key event was generated on the number pad section of the keyboard. If the number pad was used to generate the key event the value is true, otherwise the value is false.

outputString of type DOMString

outputString holds the value of the output generated by the key event. This may be a single Unicode character or it may be a string. It may also be null in the case where no output was generated by the key event.

virtKeyVal of type unsigned long

When the key associated with a key event is not representable via a Unicode character virtKeyVale holds the virtual key code associated with the depressed key. If the key has a Unicode representation or no virtual code is available the value is DOM_VK_UNDEFINED.

Methods

checkModifier

The CheckModifier method is used to check the status of a single modifier key associated with a KeyEvent. The identifier of the modifier in question is passed into the CheckModifier function. If the modifier is triggered it will return true. If not, it will return false.
The list of keys below represents the allowable modifier paramaters for this method.

• DOM_VK_LEFT_ALT
• DOM_VK_RIGHT_ALT
• DOM_VK_LEFT_CONTROL
• DOM_VK_RIGHT_CONTROL
• DOM_VK_LEFT_SHIFT
• DOM_VK_RIGHT_SHIFT
• DOM_VK_META

Parameters

modifer of type unsigned long

The modifier which the user wishes to query.

Return Value

boolean

The status of the modifier represented as a boolean.

No Exceptions

initKeyEvent

The initKeyEvent method is used to initialize the value of a MouseEvent created through the DocumentEvent interface. This method may only be called before the KeyEvent has been dispatched via the dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence. This method has no effect if called after the event has been dispatched.

Parameters

typeArg of type DOMString

Specifies the event type.

canBubbleArg of type boolean

Specifies whether or not the event can bubble.

cancelableArg of type boolean

Specifies whether or not the event's default action can be prevent.

viewArg of type views::AbstractView

Specifies the KeyEvent's AbstractView.

detailArg of type unsigned short

Specifies the number of repeated keypresses, if available.

outputStringArg of type DOMString

Specifies the KeyEvent's outputString attribute

keyValArg of type unsigned long

Specifies the KeyEvent's keyValattribute

virtKeyValArg of type unsigned long

Specifies the KeyEvent's virtKeyValattribute

inputGeneratedArg of type boolean

Specifies the KeyEvent's inputGeneratedattribute

numPadArg of type boolean

Specifies the KeyEvent's numPadattribute

No Return Value

No Exceptions

initModifier

The initModifier method is used to initialize the values of any modifiers associated with a KeyEvent created through the DocumentEvent interface. This method may only be called before the KeyEvent has been dispatched via the dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times with the same modifier property the final invocation takes precedence. Unless explicitly give a value of true, all modifiers have a value of false. This method has no effect if called after the event has been dispatched.
The list of keys below represents the allowable modifier paramaters for this method.

• DOM_VK_LEFT_ALT
• DOM_VK_RIGHT_ALT
• DOM_VK_LEFT_CONTROL
• DOM_VK_RIGHT_CONTROL
• DOM_VK_LEFT_SHIFT
• DOM_VK_RIGHT_SHIFT
• DOM_VK_META

Parameters

modifier of type unsigned long

The modifier which the user wishes to initialize

value of type boolean

The new value of the modifier.

No Return Value

No Exceptions

There are two major groups of key events. The first contains the textEvent event. The textEvent event indicates that text information has been entered, either in the form of printable characters or non-printable text information such as modifier keys. textEvent events are not necessarily accompanied by the events of the second major groups of key events, keydown and keyup.

textEvent

The textEvent event indicates that text information has been entered. The text information entered can originate from a variety of sources. It could, for example, be a character resulting from a keypress. It could also be a string resulting from an input method.

• Bubbles: Yes
• Cancelable: Yes

The keydown and keyup events comprise the second group of key events. These events are fired to indicate the physical motion of the keys on the character generation device. Depending on the input system being used, textEvent events may or may not be generated for each pair of keydown and keyup events.

keydown

The keydown event occurs when a key is pressed down.

• Bubbles: Yes
• Cancelable: Yes

keyup

The keyup event occurs when a key is released.

• Bubbles: Yes
• Cancelable: Yes

1.2.2. EventListener Grouping

EventListener grouping is intended to allow groups of EventListeners to be registered which will each have independent event flow within them which is not affected by changes to event flow in any other group. This may be used to control events separately in multiple views on a document. It may also be used to develop an application which uses events without the problem of possible interference by other applications running within the same document.

The new interfaces added for EventListener grouping should not interfere with the interfaces established in the Level 2 DOM. For purposes of interoperability between the Level 2 DOM Event Model and the new interfaces added in Level 3 the implementation can be assumed to define a default EventGroup. This EventGroup is implicitly used in the registration of all EventListeners registered via the Level 2 DOM Event Model methods which do not specify an EventGroup.

Interface EventGroup

The EventGroup interface functions primarily as a placeholder for separating the event flows when there are multiple groups of listeners for a DOM tree.

EventListeners can be registered without an EventGroup using the existing EventTarget interface, or with an associated EventGroup using the new EventTargetGroup interface. When an event is dispatched, it is dispatched independently to each EventGroup. In particular, the stopPropagation method of the Event interface only stops propagation within an EventListener's associated EventGroup.

IDL Definition

interface EventGroup {
  boolean            isSameEventGroup(in EventGroup eventGroup);
};

Methods

isSameEventGroup

This method checks if the supplied EventGroup is the same as the EventGroup upon which the method is called.

Parameters

eventGroup of type EventGroup

The EventGroup with which to check equality.

Return Value

boolean

Returns true if the EventGroups are equal, else returns false.

No Exceptions

Interface EventTargetGroup

The EventTargetGroup interface is implemented by the same set of objects that implement the EventTarget interface, namely all EventTargets in in implementation which supports the Event model and the EventGroup extension.

IDL Definition

interface EventTargetGroup {
  void               addEventListener(in DOMString type, 
                                      in EventListener listener, 
                                      in boolean useCapture, 
                                      in EventGroup eventGroup);
  void               removeEventListener(in DOMString type, 
                                         in EventListener listener, 
                                         in boolean useCapture, 
                                         in EventGroup eventGroup);
};

Methods

addEventListener

This method is equivalent to the addEventListener method of the EventTarget interface, with the exception of the added eventGroup parameter. The listener is registered with this EventGroup associated.

Parameters

type of type DOMString

listener of type EventListener

useCapture of type boolean

eventGroup of type EventGroup

The EventGroup to associate with the listener.

No Return Value

No Exceptions

removeEventListener

This method is equivalent to the removeEventListener method of the EventTarget interface, with the exception of the added eventGroup parameter. The listener registered with this EventGroup associated is removed.

Parameters

type of type DOMString

listener of type EventListener

useCapture of type boolean

eventGroup of type EventGroup

The EventGroup to associate with the listener.

No Return Value

No Exceptions

Interface DocumentEventGroup

The DocumentEventGroup interface provides a mechanism by which the user can create an EventGroup of a type supported by the implementation. It is expected that the DocumentEvent interface will be implemented on the same object which implements the Documentinterface in an implementation which supports the EventGroupextension.

IDL Definition

interface DocumentEventGroup {
  EventGroup         createEventGroup();
};

Methods

createEventGroup

This method creates a new EventGroup for use in the addEventListener and removeEventListener methods of the EventTargetGroup interface.

Return Value

EventGroup

The newly created EventGroup.

No Parameters

No Exceptions