01 September, 2000

1. Document Object Model Events

Tom Pixley, Netscape Communications Corporation

Table of contents

1.1. Level 3 Events Overview

The goal of the DOM Level 3 Events specification is to expand upon the functionality specified in the DOM Level 2 Event Specification. The specification does this by adding new interfaces which are complimentary to the interfaces defined in the DOM Level 2 Event Specification as well as adding new event sets to those already defined.

This specification requires the previously designed interfaces in order to be functional. It is not designed to be standalone. These interfaces are not designed to supercede the interfaces already provided but instead to add to the functionality contained within them.

1.2. Level 3 Events Interfaces

1.2.1. Key events

A DOM consumer can use the hasFeature of the DOMImplementation interface to determine whether the Key event set has been implemented by a DOM implementation. The feature string for this event set is "KeyEvents". This string is also used with the createEvent method.

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               = 0x12;
  const unsigned long       DOM_VK_LEFT_ALT                = 0x12;
  const unsigned long       DOM_VK_LEFT_CONTROL            = 0x11;
  const unsigned long       DOM_VK_RIGHT_CONTROL           = 0x11;
  const unsigned long       DOM_VK_LEFT_SHIFT              = 0x10;
  const unsigned long       DOM_VK_RIGHT_SHIFT             = 0x10;
  const unsigned long       DOM_VK_META                    = 0x9D;
  const unsigned long       DOM_VK_BACK_SPACE              = 0x08;
  const unsigned long       DOM_VK_CAPS_LOCK               = 0x14;
  const unsigned long       DOM_VK_DELETE                  = 0x7F;
  const unsigned long       DOM_VK_END                     = 0x23;
  const unsigned long       DOM_VK_ENTER                   = 0x0D;
  const unsigned long       DOM_VK_ESCAPE                  = 0x1B;
  const unsigned long       DOM_VK_HOME                    = 0x24;
  const unsigned long       DOM_VK_NUM_LOCK                = 0x90;
  const unsigned long       DOM_VK_PAUSE                   = 0x13;
  const unsigned long       DOM_VK_PRINTSCREEN             = 0x9A;
  const unsigned long       DOM_VK_SCROLL_LOCK             = 0x91;
  const unsigned long       DOM_VK_SPACE                   = 0x20;
  const unsigned long       DOM_VK_TAB                     = 0x09;
  const unsigned long       DOM_VK_LEFT                    = 0x25;
  const unsigned long       DOM_VK_RIGHT                   = 0x27;
  const unsigned long       DOM_VK_UP                      = 0x26;
  const unsigned long       DOM_VK_DOWN                    = 0x28;
  const unsigned long       DOM_VK_PAGE_DOWN               = 0x22;
  const unsigned long       DOM_VK_PAGE_UP                 = 0x21;
  const unsigned long       DOM_VK_F1                      = 0x70;
  const unsigned long       DOM_VK_F2                      = 0x71;
  const unsigned long       DOM_VK_F3                      = 0x72;
  const unsigned long       DOM_VK_F4                      = 0x73;
  const unsigned long       DOM_VK_F5                      = 0x74;
  const unsigned long       DOM_VK_F6                      = 0x75;
  const unsigned long       DOM_VK_F7                      = 0x76;
  const unsigned long       DOM_VK_F8                      = 0x77;
  const unsigned long       DOM_VK_F9                      = 0x78;
  const unsigned long       DOM_VK_F10                     = 0x79;
  const unsigned long       DOM_VK_F11                     = 0x7A;
  const unsigned long       DOM_VK_F12                     = 0x7B;
  const unsigned long       DOM_VK_F13                     = 0xF000;
  const unsigned long       DOM_VK_F14                     = 0xF001;
  const unsigned long       DOM_VK_F15                     = 0xF002;
  const unsigned long       DOM_VK_F16                     = 0xF003;
  const unsigned long       DOM_VK_F17                     = 0xF004;
  const unsigned long       DOM_VK_F18                     = 0xF005;
  const unsigned long       DOM_VK_F19                     = 0xF006;
  const unsigned long       DOM_VK_F20                     = 0xF007;
  const unsigned long       DOM_VK_F21                     = 0xF008;
  const unsigned long       DOM_VK_F22                     = 0xF009;
  const unsigned long       DOM_VK_F23                     = 0xF00A;
  const unsigned long       DOM_VK_F24                     = 0xF00B;

           attribute DOMString        outputString;
           attribute unsigned long    keyVal;
           attribute unsigned long    virtKeyVal;
           attribute boolean          inputGenerated;
           attribute boolean          numPad;
  boolean            GetModifier(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);

Definition group VirtualKeyCode

An integer indicating which key was pressed.

Defined Constants







Constant for the F1 function key.

Constant for the F10 function key.

Constant for the F11 function key.

Constant for the F12 function key.

Constant for the F13 function key.

Constant for the F14 function key.

Constant for the F15 function key.

Constant for the F16 function key.

Constant for the F17 function key.

Constant for the F18 function key.

Constant for the F19 function key.

Constant for the F2 function key.

Constant for the F20 function key.

Constant for the F21 function key.

Constant for the F22 function key.

Constant for the F23 function key.

Constant for the F24 function key.

Constant for the F3 function key.

Constant for the F4 function key.

Constant for the F5 function key.

Constant for the F6 function key.

Constant for the F7 function key.

Constant for the F8 function key.

Constant for the F9 function key.



This key is modifier key

This key is modifier key

This key is modifier key

This key is modifier key







This key is modifier key

This key is modifier key

This key is modifier key




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


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.

The GetModifier 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 GetModifier 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.
modifer of type unsigned long
The modifier which the user wishes to query

Return Value


No Exceptions

Issue modifier:
why no modifiers parameter to the initKeyEvent?
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

The different types of Key events that can occur are:

The keypress event occurs when a key is pressed. If the key remains depressed, multiple keypresses may be generated. This event maps not to the physical depression of the key but is instead the result of that action, often being the insertion of a character.
  • Bubbles: Yes
  • Cancelable: Yes
The keydown event occurs when a key is pressed down.
  • Bubbles: Yes
  • Cancelable: Yes
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 now interfere with the interfaces established in the Level 2 DOM.

Interface EventGroup

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

Event listeners 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, thestopPropagation method of the Event interface only stops propagation for event listeners without an associated EventGroup. Correspondingly, the stopPropagation method of EventGrouped only stops propagatation for event listeners within the specified EventGroup.

IDL Definition
interface EventGroup {

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);

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.
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

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.
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 EventGrouped

The EventGrouped interface is implemented by all Event objects.

IDL Definition
interface EventGrouped {
  void               stopPropagation(in EventGroup eventGroup);

The stopPropagation method is used prevent further propagation of an event during event flow within an EventGroup. If this method is called by any EventListener the event will cease propagating through the tree within the specified EventGroup. The event will complete dispatch to all listeners on the current EventTarget before event flow stops. This method may be used during any stage of event flow. Event propagation for other EventGroups, or listeners not associated with any EventGroup, is not affected.
eventGroup of type EventGroup
The EventGroup in which to stop event propagation.

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();

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


The newly created EventGroup.

No Parameters
No Exceptions

1.3. Issues

Issue getModifier:
Why is modifier state exposed through a method rather than an attribute?
Issue ISO-IEC-9995:
Upon what do you base the set of virtual keycodes as well as their values? Have you coordinated this set with that defined by ISO/IEC 9995 which addresses various Keyboard symbol issues.
Issue ISO-IEC-14755:
Review ISO/IEC 14755 "Input methods to enter characters from the repertoire of ISO/IEC 10646 with a keyboard or other input device" to insure that the treatment of input state is consistent with that expected by current practice when it comes to platforms which support input methods.
Issue offsets:
(This issue is related with mouse events and Views?)
it would be useful if MouseEvent class had a property that would enable listners to learn about coordinates of the event within the element's own coordinate system.