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 structure. In that case, it is the responsibility of such application to define their event flow and how it relates to the . As example of such use could 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 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 ancestor higher in the tree. The event dispatching (also called event propagation) occurs in three phases:

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

Depending on the level of DOM support, or the devices used to display (e.g. screen) or interact with (e.g. mouse, keyboard, touch screen, voice, ...), these event types could 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 but 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 table defines all event types provided in this specification (with the exception of two event types preserved for backward compatibility with ). All events will accomplish the capture phase and target phases, but not all of them will accomplish the bubbling phase (see also ). Some events are not cancelable (see ). Contextual information related to the event type are accessible using DOM interfaces.

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 DOM Level 3 Events methods related to namespaces, 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, two event listeners (or more) could be registered using the same type and same useCapture values, but different namespaceURIs. Calling EventTarget.removeEventListener 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 removes the event that EventTarget.addEventListenerNS 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 listener 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. The target phase and the bubbling phase are coupled during the registration, i.e. it is not possible to register an event listener for only one of these two phases (but the listener itself could ignore events during one of these phases if desired). It is also not possible to register an event listener for a specific event target and have it only triggered for this event target during the bubbling or capture phases (but again, the listener itself could ignore events with other event targets if desired).

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. 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 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 specifically designed for use with text input devices.