This document specifies an event flow for tree-based structures: . While it is expected that HTML and XML applications will follow this event flow, applications might reuse the interfaces defined in this document for non tree-based structures. In that case, it is the responsibility of such applications to define their event flow and how it relates to the . An example of such use can be found in .

An implementation is DOM Level 3 Events conformant if it supports the Core module defined in , the and the interfaces with their associated semantics defined in . An implementation conforms to a DOM Level 3 Events module if it conforms to DOM Level 3 Events and the event types defined in the module. An implementation conforms to an event type if it conforms to its associated semantics and DOM interfaces. For example, an implementation conforms to the DOM Level 3 User Interface Events module (see ) if it conforms to DOM Level 3 Events (i.e. implements all the basic interfaces), can generate the event types {"http://www.w3.org/2001/xml-events", "DOMActivate"} {"http://www.w3.org/2001/xml-events", "DOMFocusIn"} {"http://www.w3.org/2001/xml-events", "DOMFocusOut"} accordingly to their semantics, supports the UIEvent interface, and conforms to the DOM Level 2 Core module.

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

Each event module describes its own feature string in the event module listing.

The event is dispatched following a path from the root of the tree to this target node. It can then be handled locally at the target node level or from any target's ancestors higher in the tree. The event dispatching (also called event propagation) occurs in three phases and the following order:

Each node encountered during the dispatch of the event may contain event listeners.

An event type could be part of one or more categories. A category is represented using a local name and a namespace URI as defined in . The event types defined in this specification are not associated with one or more event categories and this specification does not provide methods to associate them. Other specifications may create and associate event categories with event listeners but in such case would need to inform the dispatch mechanism of those event categories. An example of the use of categories is given at .

Depending on the level of DOM support, or the devices used for display (e.g. screen) or interaction (e.g. mouse, keyboard, touch screen, voice, ...), these event types can be generated by the implementation. When used with an or application, the specifications of those languages may restrict the semantics and scope (in particular the possible target nodes) associated with an event type. For example, {"http://www.w3.org/2001/xml-events", "click"} can be targeted to all elements except applet, base, basefont, bdo, br, font, frame, frameset, head, html, iframe, isindex, meta, param, script, style, and title. Refer to the specification defining the language used in order to find those restrictions or to find event types that are not defined in this document.

The following list defines all event types (with the exception of two event types preserved for backward compatibility with , see ) provided in this specification. All event types defined in this specification are bound to the namespace URI "http://www.w3.org/2001/xml-events" and the following list only enumerates the local name of the event type.

The following table provides additional information on the event types. All events will accomplish the capture and target phases, but not all of them will accomplish the bubbling phase (see also ). Some events are not cancelable (see ). Some events will only be dispatched to a specific set of possible targets, specified using node types. Contextual information related to the event type is accessible using DOM interfaces.

As an example, the event {"http://www.w3.org/2001/xml-events", "load"} will trigger event listeners attached on Element nodes for that event and on the capture and target phases. This event cannot be cancelled. If an event listener for the load event is attached to a node other than Element nodes, or if it is attached to the bubbling phase only, this event listener cannot be triggered.

The event objects associated with the event types described above may contain context information. Refer to the description of the DOM interfaces for further information.

Namespace URIs were only introduced in DOM Level 3 Events and were not part of DOM Level 2 Events. DOM Level 2 Events methods are namespace ignorant and the event type is only represented by an XML name, specified in the Event.type attribute.

Therefore, while it is safe to use these methods when not dealing with namespaces, using them and the new ones at the same time should be avoided. DOM Level 2 Events methods solely identify events by their Event.type. On the contrary, the namespaces aware DOM Level 3 Events methods, identify attribute nodes by their Event.namespaceURI and Event.type. Because of this fundamental difference, mixing both sets of methods can lead to unpredictable results. For example, using EventTarget.addEventListenerNS(namespaceURI, type, listener, ...), two event listeners (or more) could be registered using the same type and same useCapture values, but different namespaceURIs. Calling EventTarget.removeEventListener(type, listener, ...) with that type and useCapture could then remove any or none of those event listeners. The result depends on the implementation. The only guarantee in such cases is that all methods which access an event listener by its namespaceURI and type will access the same event listener. For instance, EventTarget.removeEventListenerNS(namespaceURI, type, listener, ...) removes the event that EventTarget.addEventListenerNS(namespaceURI, type, listener, ...) added.

For compatibility reasons, the dispatching of an event will ignore namespace URIs if either the event or the event listener has a null namespace URI. If a DOM Level 2 event (i.e. with a null namespace URI) is dispatched in the DOM tree, all event listeners that match the type will be triggered as described in the . If a DOM Level 3 event (i.e. with a namespace URI) is dispatched in the DOM tree, all event listeners with the same type and the same or null namespace URI will be triggered as described in the .

The user can attach an event listener using the methods on the EventTarget interface:

The methods do not provide the ability to register the same event listener more than once for the same event type and the same phase. It is not possible to register an event listener:

To register an event listener, DOM applications must use the methods EventTarget.addEventListener() and EventTarget.addEventListenerNS().

An EventListener being registered on an EventTarget may choose to have that EventListener triggered during the capture phase by specifying the useCapture parameter of the EventTarget.addEventListener() or EventTarget.addEventListenerNS() methods to be true. If false, the EventListener will be triggered during the target and bubbling phases.

In , event listeners are attached using elements and attributes:

Event listeners can only be registered on Element nodes, i.e. other Node types are not addressable, and cannot be registered for a specific group either, i.e. they are always attached to the default group. The target phase and the bubbling phase are coupled during the registration. does not address namespaces in event types. If the value of the event attribute of the listener element contains a colon (':'), it should be interpreted as a QName as defined in .

In , event listeners are attached using elements:

Event listeners can only be registered on Element nodes, i.e. other Node types are not addressable, and cannot be registered for a specific group either, i.e. they are always attached to the default group. The target phase and the bubbling phase are coupled during the registration. does not address namespaces in event types but uses the notion of event categories. The event type "connection.disconnect.hangup" could be associated to the event categories {"http://www.example.org/2003/voicexml", "connection"} and {"http://www.example.org/2003/voicexml", "connection.disconnect"}.

In languages such as , , or , event listeners are specified as attributes:

Since only one attribute with the same name can appear on an element, it is therefore not possible to register more than one event listener on a single EventTarget for the event type. Also, event listeners can only be registered on Element nodes for the target phase and bubbling phase, i.e. other Node types and the capture phase are not addressable with these languages. Event listeners cannot be registered for a specific group either, i.e. they are always attached to the default group.

In order to achieve compatibility with those languages, implementors may view the setting of attributes which represent event handlers as the creation and registration of an EventListener on the EventTarget. The value of useCapture defaults to false. This EventListener behaves in the same manner as any other EventListeners which may be registered on the EventTarget. If the attribute representing the event listener is changed, this may be viewed as the removal of the previously registered EventListener and the registration of a new one. Furthermore, no specification is made as to the order in which event attributes will receive the event with regards to the other EventListeners on the EventTarget.

In most cases, the events dispatched by the DOM Events implementation are also created by the implementation. It is however possible to simulate events such as mouse events by creating the Event objects and dispatch them using the DOM Events implementation.

DOM Events provides two ways for creating Event objects. An application can either create Event objects that are known to the implementation, or create its own objects and have them dispatched by the DOM Events implementation.

Creating Event objects that are known to the DOM Events implementation is done using DocumentEvent.createEvent(). The application must then initialize the object by calling the appropriate initialization method before invoking EventTarget.dispatchEvent(). The Event objects created must be known by the DOM Events implementation; otherwise an event exception is thrown.

The DOM application might want to create its own Event objects, in order to change the default Event implementation provided by the DOM Events implementation or to generate new event types with specific contextual information. In any case, the application is responsible for creating and initializing the Event object. The application can then dispatch the event using the DOM Events implementation by using EventTarget.dispatchEvent().

However, the DOM Events implementation requires to have access to two attributes in the Event object in order to accomplish the dispatch appropriately: Event.currentTarget and Event.eventPhase. Those attributes are defined as readonly in the Event interface since event listeners must not change them and it is the responsibility of the DOM Events implementation to update them during the event flow. Therefore, implementing the Event interface when creating its own events is not enough for an application since the DOM Events implementation will not be able to update the current phase and the current node during the dispatch, unless the event object also implements the CustomEvent interface to give access to the relevant attributes.

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

The User Interface event types are listed below. For a full description of the semantics associated with these event types, refer to the . 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 . For additional information about conformance, please see the DOM Level 3 Core specification . The DOM Level 3 User Interface Events module is built on top of the DOM Level 2 User Interface Events 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.

The text event module originates from the onkeypress attribute. Unlike this attribute, the event type {"http://www.w3.org/2001/xml-events", "textInput"} applies only to characters and is designed for use with any text input devices, not just keyboards. Refer to Appendix A, "", for examples on how text events are used in combination with keyboard events.

The text event type is listed below. For a full description of the semantics associated with this event type, refer to the . 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 .

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

The Mouse event types are listed below. For a full description of the semantics associated with these event types, refer to the . 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 . The DOM Level 3 Mouse Events module is built on top of the DOM Level 2 Mouse Events 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):

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 when dealing with character input.

Depending on the character generation device, 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 . 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 .

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 resulting 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 mutation event types are listed below. For a full description of the semantics associated with these event types, refer to the . 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 . This MutationEvent interface is built on top of the DOM Level 2 Mutation Events 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 mutation name event types are listed below. For a full description of the semantics associated with these event types, refer to the . 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 . For additional information about conformance, please see the DOM Level 3 Core specification .

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 .

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

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.

The HTML event module is composed of events listed in 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 specification. Use Node.isSupported(feature, version) with the parameter values "HTML" and "2.0" (respectively) to determine whether or not the Document node supports 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 . For additional information about conformance, please see the DOM Level 3 Core specification . The DOM Level 3 HTML Events module is built on top of the DOM Level 2 HTML Events 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 descriptions of event types are refinements of the general descriptions provided in , with the addition of the events {"http://www.w3.org/2001/xml-events", "focus"} and {"http://www.w3.org/2001/xml-events", "blur"}. All events types are bound to the namespace URI "http://www.w3.org/2001/xml-events" and the following list only enumerates the local name of the event type.

The following table provides refinements or additional information on the event types. Some events will only be dispatched to a specific set of possible targets, specified using HTML node types.

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.