Table of contents

Appendices

1.7 Event module definitions

The DOM Event Model allows a DOM implementation to support multiple modules of events. The model has been designed to allow addition of new event modules as is required. The DOM will not attempt to define all possible events. For purposes of interoperability, the DOM will define a module of user interface events including lower level device dependent events, a module of UI logical events, and a module of document mutation events.

User Interface event types[top]

The User Interface event module contains basic event types associated with user interfaces.

The UIEvent interface provides specific contextual information associated with User Interface events.

NOTE: 

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

The view attribute identifies the AbstractView from which the event was generated.

Specifies some detail information about the Event, depending on the type of event.

The initUIEvent method is used to initialize the value of a UIEvent created using the DocumentEvent.createEvent method. This method may only be called before the UIEvent has been dispatched via the EventTarget.dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.

Specifies the event type.

Specifies whether or not the event can bubble. This parameter overrides the intrinsic bubbling behavior of the event.

Specifies whether or not the event's default action can be prevented. This parameter overrides the intrinsic cancelable behavior of the event.

Specifies the Event's AbstractView.

Specifies the Event's detail.

The initUIEventNS method is used to initialize the value of a UIEvent created using the DocumentEvent.createEvent method. This method may only be called before the UIEvent has been dispatched via the EventTarget.dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.

Specifies the namespace URI associated with this event, or null if the application wish not to use namespaces.

Specifies the event type (see also the description of the type attribute in the Event interface).

Specifies whether or not the event can bubble.

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

Specifies the Event's AbstractView.

Specifies the Event's detail.

The User Interface event types are listed below. For a full description of the semantics associated with these event types, refer to the [Complete list of event types]. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "UIEvents" and "3.0" (respectively) to determine whether or not the DOM Level 3 User Interface event types are supported by the implementation. In order to fully support this module, an implementation must also support the "Events" feature defined in this specification and the "Views" feature defined in the DOM Level 2 Views specification [DOM2Views]. For additional information about [conformance], please see the DOM Level 3 Core specification [DOMCore]. The DOM Level 3 User Interface Events module is built on top of the DOM Level 2 User Interface Events [DOM2Events] module, i.e. a DOM Level 3 User Interface Events implementation where hasFeature("UIEvents", "3.0") returns true must also return true when the version number is "2.0", "" or, null.

Text events[top]

The text event module originates from the [HTML40] onkeypress attribute. Unlike this attribute, the event type {"http://www.w3.org/2001/xml-events", "textInput"} applies only to characters and is specifically designed for use with text input devices.

The TextEvent interface provides specific contextual information associated with Text Events.

NOTE: 

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

Issue (repeat):

In the past, detail was used to contain the repeat count for the key. Do we want to keep this notion? How? using an auto-repeat event instead? Use cases?

Resolution:

closed.

Issue (1):

same question for visibleOutputGenerated: This attribute is device dependent (display related). What happen on voice system for example? What are the real use cases for it?

Resolution:

closed.

Issue (1):

What happens on paste through Ctrl-V? Do you get a textInput event or not if the selection contains characters?

Resolution:

This will be undefined by this specification.

data holds the value of the characters generated by the character device. This may be a single Unicode character or it may be a string.

The initTextEvent method is used to initialize the value of a TextEvent created using the DocumentEvent.createEvent method. This method may only be called before the TextEvent has been dispatched via the EventTarget.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.

Specifies the event type.

Specifies whether or not the event can bubble. This parameter overrides the intrinsic bubbling behavior of the event.

Specifies whether or not the event's default action can be prevent. This parameter overrides the intrinsic cancelable behavior of the event.

Specifies the TextEvent's view.

Specifies the TextEvent's data attribute

The initTextEventNS method is used to initialize the value of a TextEvent created using the DocumentEvent.createEvent method. This method may only be called before the TextEvent has been dispatched via the EventTarget.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.

Specifies the namespace URI associated with this event, or null if the applications wish to have no namespace.

Specifies the event type.

Specifies whether or not the event can bubble.

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

Specifies the TextEvent's view.

Specifies the TextEvent's data attribute

The text event type is listed below. For a full description of the semantics associated with this event type, refer to the [Complete list of event types]. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "TextEvents" and "3.0" (respectively) to determine whether or not the Text 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. For additional information about [conformance], please see the DOM Level 3 Core specification [DOMCore].

Mouse event types[top]

The Mouse event module originates from the [HTML40] onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, and onmouseout attributes. This event module is specifically designed for use with pointing input devices, such a mouse.

The MouseEvent interface provides specific contextual information associated with Mouse events.

In the case of nested elements mouse events are always targeted at the most deeply nested element. Ancestors of the targeted element may use bubbling to obtain notification of mouse events which occur within its descendent elements.

NOTE: 

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

The horizontal coordinate at which the event occurred relative to the origin of the screen coordinate system.

The vertical coordinate at which the event occurred relative to the origin of the screen coordinate system.

The horizontal coordinate at which the event occurred relative to the DOM implementation's client area.

The vertical coordinate at which the event occurred relative to the DOM implementation's client area.

true if the control (Ctrl) key modifier is activated.

true if the shift (Shift) key modifier is activated.

true if the alt (alternative) key modifier is activated.

true if the meta (Meta) key modifier is activated.

NOTE: 

The Command key modifier on Macintosh system must be represented using this key modifier.

During mouse events caused by the depression or release of a mouse button, button is used to indicate which mouse button changed state. 0 indicates the normal (in general on the left or the one button on Macintosh mice, used to activate a button or select text) button of the mouse. 2 indicates the contextual property (in general on the right, used to display a context menu) button of the mouse if present. 1 indicates the extra (in general in the middle and often combined with the mouse wheel) button. Some mice may provide or simulate more buttons and values higher than 2 could be used to represent such buttons.

Used to identify a secondary EventTarget related to a UI event. Currently this attribute is used with the mouseover event to indicate the EventTarget which the pointing device exited and with the mouseout event to indicate the EventTarget which the pointing device entered.

The initMouseEvent method is used to initialize the value of a MouseEvent created using the DocumentEvent.createEvent method. This method may only be called before the MouseEvent has been dispatched via the EventTarget.dispatchEvent method, though it may be called multiple times before being dispatched. If called multiple times, the final invocation takes precedence.

Specifies the event type.

Specifies whether or not the event can bubble.

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

Specifies the Event's view.

Specifies the Event's mouse click count.

Specifies the Event's screen x coordinate

Specifies the Event's screen y coordinate

Specifies the Event's client x coordinate

Specifies the Event's client y coordinate

Specifies whether or not control key was depressed during the Event.

Specifies whether or not alt key was depressed during the Event.

Specifies whether or not shift key was depressed during the Event.

Specifies whether or not meta key was depressed during the Event.

Specifies the Event's mouse button.

Specifies the Event's related EventTarget.

The initMouseEventNS method is used to initialize the value of a MouseEvent created using the DocumentEvent.createEvent interface. This method may only be called before the MouseEvent has been dispatched via the EventTarget.dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.

Specifies the namespace URI associated with this event, or null if the application wish to have no namespace.

Specifies the event type.

Specifies whether or not the event can bubble.

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

Specifies the Event's AbstractView.

Specifies the Event's mouse click count.

Specifies the Event's screen x coordinate

Specifies the Event's screen y coordinate

Specifies the Event's client x coordinate

Specifies the Event's client y coordinate

Specifies whether or not control key was depressed during the Event.

Specifies whether or not alt key was depressed during the Event.

Specifies whether or not shift key was depressed during the Event.

Specifies whether or not meta key was depressed during the Event.

Specifies the Event's mouse button.

Specifies the Event's related EventTarget.

Specifies whether or not alt graph key was depressed during the Event.

true if the alt-graph (Alt Gr) key modifier is activated.

NOTE: 

Some operating systems simulate the alt-graph key modifier with the combinaison of alt and ctrl key modifiers. Implementations are encouraged to use this modifier instead.

The Mouse event types are listed below. For a full description of the semantics associated with these event types, refer to the [Complete list of event types]. In the case of nested elements, mouse event types are always targeted at the most deeply nested element. Ancestors of the targeted element may use bubbling to obtain notification of mouse events which occur within its descendent elements. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "MouseEvents" 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. For additional information about [conformance], please see the DOM Level 3 Core specification [DOMCore]. The DOM Level 3 Mouse Events module is built on top of the DOM Level 2 Mouse Events [DOM2Events] module, i.e. a DOM Level 3 Mouse Events implementation where hasFeature("MouseEvents", "3.0") returns true must also return true when the version number is "2.0", "" or, null.

As an example, a "double-click" on a mouse device will produce the following events (the value of UIEvent.detail is indicated in parenthesis):

1. {"http://www.w3.org/2001/xml-events", "mousedown"} (1)

2. {"http://www.w3.org/2001/xml-events", "mouseup"} (1)

3. {"http://www.w3.org/2001/xml-events", "click"} (1)

4. {"http://www.w3.org/2001/xml-events", "mousedown"} (2)

5. {"http://www.w3.org/2001/xml-events", "mouseup"} (2)

6. {"http://www.w3.org/2001/xml-events", "click"} (2)

NOTE: 

plh -- I added this example above but didn't check if it is correct or not yet (do we have the click(1)?). If it is not, let me know in any case. I'll probably complicate the example a bit (with moves) to show how detail really works.

Keyboard event types[top]

Keyboard events are device dependent, i.e. they rely on the capabilities of the input devices and how they are mapped in the operating systems. It is therefore highly recommended to rely on [Events-TextEvent] when dealing with characters.

The KeyboardEvent interface provides specific contextual information associated with keyboard devices. Each keyboard event reference a key using an identifier.

Each modifier attribute (ctrlKey, shiftKey, altKey, metaKey, and altGraphKey) is activated when the key modifier is being pressed down or maintained pressed, i.e. the modifier attribute is not in use when the key modifier is being released.

NOTE: 

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

The key activation is not distinguished as the left or right version of the key, and did not originate from the numeric keypad (or did not originate with a virtual key corresponding to the numeric keypad). Example: the 'Q' key on a PC 101 Key US.

The key activated is in the left key location (there is more than one possible location for this key). Example: the left Shift key on a PC 101 Key US.

The key activation is in the right key location (there is more than one possible location for this key). Example: the right Shift key on a PC 101 Key US.

The key activation originated on the numeric keypad or with a virtual key corresponding to the numeric keypad. Example: the '1' key on a PC 101 Key US.

Implementations can use this constant to indicate that the location of the key cannot be determined.

NOTE: 

In case a DOM implementation wishes to provide new location information, all values above the value of this constant can be used for that effect and generic DOM applications should consider values above the value of this constant as being equivalent to DOM_KEY_LOCATION_UNKNOWN.

keyIdentifier holds the identifier of the key. For a list of possible value, refer to [Key identifiers for keyboard events.].

NOTE: 

Implementations that are unable to identify a key must use the key identifier "Unidentified".

The keyLocation attribute contains an indication of the location of they key on the device.

true if the control (Ctrl) key modifier is activated.

true if the shift (Shift) key modifier is activated.

true if the alt (alternative) key modifier is activated.

true if the meta (Meta) key modifier is activated.

NOTE: 

The Command key modifier on Macintosh system must be represented using this key modifier.

true if the alt-graph (Alt Gr) key modifier is activated.

NOTE: 

Some operating systems simulate the alt-graph key modifier with the combinaison of alt and ctrl key modifiers. Implementations are encouraged to use this modifier instead.

The initKeyboardEvent method is used to initialize the value of a KeyboardEvent created using the DocumentEvent.createEvent method. This method may only be called before the KeyboardEvent has been dispatched via the EventTarget.dispatchEvent method, though it may be called multiple times before being dispatched if necessary. If called multiple times, the final invocation takes precedence. This method has no effect if called after the event has been dispatched.

Specifies the event type.

Specifies whether or not the event can bubble. This parameter overrides the intrinsic bubbling behavior of the event.

Specifies whether or not the event's default action can be prevent. This parameter overrides the intrinsic cancelable behavior of the event.

Specifies the KeyboardEvent's AbstractView.

Specifies the KeyboardEvent's keyIdentifier attribute.

Specifies the KeyboardEvent's keyLocation attribute.

Specifies the KeyboardEvent's ctrlKey attribute.

Specifies the KeyboardEvent's shiftKey attribute.

Specifies the KeyboardEvent's altKey attribute.

Specifies the KeyboardEvent's metaKey attribute.

Specifies the KeyboardEvent's altGraphKey attribute.

The initKeyboardEventNS method is used to initialize the value of a KeyboardEvent created using the DocumentEvent.createEvent method. This method may only be called before the KeyboardEvent has been dispatched via the EventTarget.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.

Specifies the namespace URI associated with this event, or null if the applications wish to have no namespace.

Specifies the event type.

Specifies whether or not the event can bubble.

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

Specifies the KeyboardEvent's AbstractView.

Specifies the KeyboardEvent's keyIdentifier attribute

Specifies the KeyboardEvent's keyLocation attribute.

Specifies the KeyboardEvent's ctrlKey attribute.

Specifies the KeyboardEvent's shiftKey attribute.

Specifies the KeyboardEvent's altKey attribute.

Specifies the KeyboardEvent's metaKey attribute.

Specifies the KeyboardEvent's altGraphKey attribute.

Depending on the character device generation system, keyboard events may or may not be generated.

The keyboard event types are listed below. For a full description of the semantics associated with these event types, refer to the [Complete list of event types]. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "KeyboardEvents" and "3.0" (respectively) to determine whether or not the Keyboard 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. For additional information about [conformance], please see the DOM Level 3 Core specification [DOMCore].

Mutation and mutation name event types[top]

The mutation and mutation name event modules are designed to allow notification of any changes to the structure of a document, including attribute, text, or name modifications. It may be noted that none of the event types associated with the modules are designated as cancelable. This stems from the fact that it is very difficult to make use of existing DOM interfaces which cause document modifications if any change to the document might or might not take place due to cancelation of the resulted event. Although this is still a desired capability, it was decided that it would be better left until the addition of transactions into the DOM.

Many single modifications of the tree can cause multiple mutation events to be dispatched. Rather than attempt to specify the ordering of mutation events due to every possible modification of the tree, the ordering of these events is left to the implementation.

The MutationEvent interface provides specific contextual information associated with Mutation events.

NOTE: 

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

An integer indicating in which way the Attr was changed.

The Attr was modified in place.

The Attr was just added.

The Attr was just removed.

relatedNode is used to identify a secondary node related to a mutation event. For example, if a mutation event is dispatched to a node indicating that its parent has changed, the relatedNode is the changed parent. If an event is instead dispatched to a subtree indicating a node was changed within it, the relatedNode is the changed node. In the case of the DOMAttrModified event it indicates the Attr node which was modified, added, or removed.

prevValue indicates the previous value of the Attr node in DOMAttrModified events, and of the CharacterData node in DOMCharacterDataModified events.

newValue indicates the new value of the Attr node in DOMAttrModified events, and of the CharacterData node in DOMCharacterDataModified events.

attrName indicates the name of the changed Attr node in a DOMAttrModified event.

attrChange indicates the type of change which triggered the DOMAttrModified event. The values can be MODIFICATION, ADDITION, or REMOVAL.

The initMutationEvent method is used to initialize the value of a MutationEvent created using the DocumentEvent.createEvent method. This method may only be called before the MutationEvent has been dispatched via the EventTarget.dispatchEvent method, though it may be called multiple times before being dispatched if necessary. If called multiple times, the final invocation takes precedence.

Specifies the event type.

Specifies whether or not the event can bubble. This parameter overrides the intrinsic bubbling behavior of the event.

Specifies whether or not the event's default action can be prevented. This parameter overrides the intrinsic cancelable behavior of the event.

Specifies the Event's related Node.

Specifies the Event's prevValue attribute. This value may be null.

Specifies the Event's newValue attribute. This value may be null.

Specifies the Event's attrName attribute. This value may be null.

Specifies the Event's attrChange attribute.

The initMutationEventNS method is used to initialize the value of a MutationEvent created using the DocumentEvent.createEvent method. This method may only be called before the MutationEvent has been dispatched via the EventTarget.dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.

Specifies the namespace URI associated with this event, or null if the application wish to have no namespace.

Specifies the event type.

Specifies whether or not the event can bubble.

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

Specifies the Event's related Node.

Specifies the Event's prevValue attribute. This value may be null.

Specifies the Event's newValue attribute. This value may be null.

Specifies the Event's attrName attribute. This value may be null.

Specifies the Event's attrChange attribute.

The mutation event types are listed below. For a full description of the semantics associated with these event types, refer to the [Complete list of event types]. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "MutationEvents" and "3.0" (respectively) to determine whether or not the MutationEvent is supported by the implementation. In order to fully support this module, an implementation must also support the "Events" feature defined in this specification. For additional information about [conformance], please see the DOM Level 3 Core specification [DOMCore]. This MutationEvent interface is built on top of the DOM Level 2 Mutation Events [DOM2Events] module, i.e. a DOM Level 3 MutationEvent interface implementation where hasFeature("MutationEvents","3.0") returns true must also return true when the version number is "2.0", "" or, null.

The MutationNameEvent interface provides specific contextual information associated with Mutation name event types.

NOTE: 

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

The previous value of the relatedNode's namespaceURI.

The previous value of the relatedNode's nodeName.

The initMutationNameEvent method is used to initialize the value of a MutationNameEvent created using the DocumentEvent.createEvent method. This method may only be called before the MutationNameEvent has been dispatched via the EventTarget.dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.

Specifies the event type.

Specifies whether or not the event can bubble.

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

Specifies the Event's related Node.

Specifies the previous namespaceURI of the related Node. This value may be null.

Specifies the previous nodeName of the related Node.

The initMutationNameEventNS method is used to initialize the value of a MutationNameEvent created using the DocumentEvent.createEvent method. This method may only be called before the MutationNameEvent has been dispatched via the EventTarget.dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.

Specifies the namespace URI associated with this event, or null if the application wish to have no namespace.

Specifies the event type.

Specifies whether or not the event can bubble.

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

Specifies the Event's related Node.

Specifies the previous namespaceURI of the related Node. This value may be null.

Specifies the previous nodeName of the related Node.

The mutation name event types are listed below. For a full description of the semantics associated with these event types, refer to the [Complete list of event types]. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "MutationNameEvents" and "3.0" (respectively) to determine whether or not the MutationNameEvent is supported by the implementation. In order to fully support this module, an implementation must also support the "MutationEvents" feature defined in this specification and the "Core" feature defined in the DOM Level 3 Core specification [DOMCore]. For additional information about [conformance], please see the DOM Level 3 Core specification [DOMCore].

Basic event types[top]

This event module contains basic event types associated with document manipulation.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "BasicEvents" and "3.0" (respectively) to determine whether or not the basic event module is supported by the implementation. In order to fully support this module, an implementation must also support the "Events" feature defined in this specification. For additional information about [conformance], please see the DOM Level 3 Core specification [DOMCore].

The basic event types are listed below. For a full description of the semantics associated with these event types, refer to the [Complete list of event types].

The event types {"http://www.w3.org/2001/xml-events", "resize"} and {"http://www.w3.org/2001/xml-events", "scroll"} implement the UIEvent interface. All other HTML event types implement at least the basic Event interface. However, they may be generated from a user interface; in that case, the event objects also implements the UIEvent interface and UIEvent.view is in use.

HTML Events[top]

The HTML event module is composed of events listed in [HTML40] and additional events which are supported in DOM Level 0 browsers. It refines the semantics and scope of the basic event types and provides two new event types. This event module is only applicable if the Document supports the [DOM2HTML] specification. Use Node.isSupported(feature, version) with the parameter values "HTML" and "2.0" (respectively) to determine whether or not the Document node supported the HTML module.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "HTMLEvents" and "3.0" (respectively) to determine whether or not the HTML event module is supported by the implementation. In order to fully support this module, an implementation must also support the "BasicEvents" feature defined in this specification and the "HTML" feature defined in [DOM2HTML]. For additional information about [conformance], please see the DOM Level 3 Core specification [DOMCore]. The DOM Level 3 HTML Events module is built on top of the DOM Level 2 HTML Events [DOM2Events] module, i.e. a DOM Level 3 HTML Events implementation where hasFeature("HTMLEvents", "3.0") returns true must also return true when the version number is "2.0", "" or, null.

The following new event types are defined:

The event types {"http://www.w3.org/2001/xml-events", "focus"} and {"http://www.w3.org/2001/xml-events", "blur"} may be generated from a user interface; in that case, the event objects also implements the UIEvent interface and UIEvent.view is in use.