previous   next   contents   index

21 February 2003

1. Document Object Model Events

Editors:
Philippe Le Hégaret, W3C
Tom Pixley, Netscape Communications Corporation (until July 2002)

Table of contents

1.1. Introduction

DOM Events is designed with two main goals. The first goal is the design of an event system which allows registration of event listeners, describes event flow through a tree structure. Additionally, the specification will provide standard modules of events for user interface control and document mutation notifications, including defined contextual information for each of these event modules.

The second goal of the DOM Events is to provide a common subset of the current event systems used in DOM Level 0 browsers. This is intended to foster interoperability of existing scripts and content. It is not expected that this goal will be met with full backwards compatibility. However, the specification attempts to achieve this when possible.

The following sections of the specification define both the specification for the DOM Event Model and a number of conformant event modules designed for use within the model. The DOM Event Model consists of:

1.1.1. Event flows

This document specifies an event flow for tree-based structures: DOM event flow. 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 DOM event flow. As example of such use could be found in [DOM Level 3 Load and Save].

1.1.2. Conformance

An implementation is DOM Level 3 Events conformant if it supports the Core module defined in [DOM Level 2 Core], the DOM event flow and the interfaces with their associated semantics defined in Basic interfaces. 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 User Interface event types) 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.

Note: An implementation which does not conform to an event module can still implement the DOM interfaces associated with it. The DOM application can then create an event object using the DocumentEvent.createEvent method and dispatch an event type associated with this interface using the EventTarget.dispatchEvent method.

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 [DOM Level 2 Core] and use the DOM event flow. For additional information about conformance, please see the DOM Level 3 Core specification [DOM Level 3 Core]. DOM Level 3 Events is built on top of DOM Level 2 Events [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.

1.2. DOM event flow

The DOM event flow is the process through which the event originates from the DOM Events implementation and is dispatched into a tree. Each event has an event target, a targeted node in the case of the DOM Event flow, toward which the event is dispatched by the DOM Events implementation.

1.2.1. Phases

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:

  1. The capture phase: the event is dispatched on the target ancestors from the root of the tree to the direct parent of the target node.
  2. The target phase: the event is dispatched on the target node.
  3. The bubbling phase: the event is dispatched on the target ancestors from the direct parent of the target node to the root of the tree.

graphical representation of an event dispatched in a DOM tree using the DOM event flow
graphical representation of an event dispatched in a DOM tree using the DOM event flow

Note: An SVG 1.0 version of the representation above is also available.

The target ancestors are determined before the initial dispatch of the event. If the target node is removed during the dispatching, or a target ancestor is added or removed, the event propagation will always be based on the target node and the target ancestors determined before the dispatch.

Some events may not necessarily accomplish the three phases of the DOM event flow, e.g. the event could only be defined for one or two phases. As an example, events defined in this specification will always accomplish the capture and target phases but some will not accomplish the bubbling phase ("bubbling events" versus "non-bubbling events", see also the Event.bubbles attribute).

1.2.2. Event listeners

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

1.2.2.1. Registration of event listeners

Event listeners can be registered on all nodes in the tree for a specific type of event, phase, and group. If the event listener is registered on a node while an event gets processed on this node, the event listener will not be triggered during the current phase but may be triggered during a later phase in the event flow, i.e. the bubbling phase.

1.2.2.2. Event groups

An event listener is always part of a group. It is either explicitly in a group if a group has been specified at the registration or implicitly in the default group if no group has been specified. Within a group, event listeners are ordered in their order of registration. If two event listeners {A1, A2}, that are part of the same group, are registered one after the other (A1, then A2) for the same phase, the DOM event flow guarantees their triggering order (A1, then A2). If the two listeners are not part of the same group, no specification is made as to the order in which they will be triggered.

Note: While this specification does not specify a full ordering (i.e. groups are still unordered), it does specify ordering within a group. This implies that if the event listeners {A1, A2, B1, B2}, with A and B being two different groups, are registered for the same phase in the following order: A1, A2, B1, and B2. The following triggering orders are possible and conform to the DOM event flow: {A1, A2, B1, B2}, {A1, B1, A2, B2}, {B1, A1, A2, B2}, {A1, B1, B2, A2}, {B1, A1, B2, A2}, {B1, B2, A1, A2}. DOM Events implementations may impose priorities on groups but DOM applications must not rely on it. Unlike this specification, [DOM Level 2 Events] did not specify any triggering order for event listeners.

1.2.2.3. Triggering an event listener

When the event is dispatched through the tree, from node to node, event listeners registered on the node are triggered if:

  1. they were registered for the same type of event;
  2. they were registered for the same phase;
  3. the event propagation has not been stopped for the group.

1.2.2.4. Removing an event listener

If an event listener is removed from a node while an event is being processed on the node, it will not be triggered by the current actions. Once removed, the event listener is never invoked again (unless registered again for future processing).

1.2.2.5. Reentrance

It is expected that actions taken by EventListeners may cause additional events to be dispatched. Additional events should be handled in a synchronous manner and may cause reentrance into the event model. If an event listener fires a new event using EventTarget.dispatchEvent, the event propagation that causes the event listener to be triggered will resume only after the event propagation of the new event is completed.

Since implementations may have restrictions such as stack-usage or other memory requirements, applications should not depend on how many synchronous events may be triggered.

1.2.2.6. Event propagation and event groups

All event listeners are part of a group (see Registration of event listeners). An event listener may prevent event listeners that are part of a same group from being triggered. The effect could be:

  • immediate and no more event listeners from the same group will be triggered by the event object;
  • differed until all event listeners from the same group have been triggered on the current node, i.e. the event listeners of the same group attached on other nodes will not be triggered.

If two event listeners are registered for two different groups, one cannot prevent the other from being triggered.

1.3. Default actions and cancelable events

Implementations may have a default action associated with an event type. An example is the [HTML 4.01] form element. When the user submits the form (e.g. by pressing on a submit button), the event {"http://www.w3.org/2001/xml-events", "submit"} is dispatched to the element and the default action for this event type is generally to send a request to a Web server with the parameters from the form.

The default actions are not part of the DOM Event flow. Before invoking a default action, the implementation must first dispatch the event as described in the DOM event flow.

A cancelable event is an event associated with a default action which is allowed to be canceled during the DOM event flow. At any phase during the event flow, the triggered event listeners have the option of canceling the default action or allowing the default action to proceed. In the case of the hyperlink in the browser, canceling the action would have the result of not activating the hyperlink. Not all events defined in this specification are cancelable events.

Different implementations will specify their own default actions, if any, associated with each event. The DOM Events specification does not attempt to specify these actions.

This specification does not provide mechanisms for accessing default actions or adding new ones.

Note: Some implementations also provide default actions before the dispatch of the event. It is not possible to cancel those default actions and this specification does not address them. An example of such default actions can be found in [DOM Level 2 HTML] on the HTMLInputElement.checked attribute.

1.4. Event types

Each event is associated with a type, called event type. The event type is composed of a local name and a namespace URI as defined in [XML Namespaces]. All events defined in this specification use the namespace URI "http://www.w3.org/2001/xml-events".

Note: As in [DOM Level 3 Core], DOM Level 3 Events does not perform any URI normalization or canonicalization. The URIs given to the DOM are assumed to be valid (e.g., characters such as white spaces are properly escaped), and no lexical checking is performed. Absolute URI references are treated as strings and compared literally. How relative namespace URI references are treated is undefined. To ensure interoperability only absolute namespace URI references (i.e., URI references beginning with a scheme name and a colon) should be used. Applications that wish to have no namespace should use the value null as the namespaceURI parameter of methods. If they pass an empty string the DOM implementation turns it into a null.

1.4.1. Complete list of event types

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 [XML 1.0] or [HTML 4.01] 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 [XHTML 1.0] 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 [HTML 4.01]). All events will accomplish the capture phase and target phases, but not all of them will accomplish the bubbling phase (see also DOM event flow). Some events are not cancelable (see Default actions and cancelable events). Contextual information related to the event type are accessible using DOM interfaces.

Event type Description Bubbling phase Cancelable Target node DOM interface
"http://www.w3.org/2001/xml-events", "DOMActivate" An element is activated, for instance, using a mouse device, a keyboard device, or a voice command.

Note: The activation of an element is device dependent but is also application dependent, e.g. a link in a document can be activated using a mouse click or a mouse double click.

 Yes Yes Element UIEvent
"http://www.w3.org/2001/xml-events", "DOMFocusIn" An event target receives focus, for instance via a pointing device being moved onto an element or using keyboard navigation. Yes No Element UIEvent
"http://www.w3.org/2001/xml-events", "DOMFocusOut" A event target loses focus, for instance via a pointing device being moved out of an element or by tabbing navigation out of the element. Yes No Element UIEvent
"http://www.w3.org/2001/xml-events", "textInput" One or more characters have been entered. The characters can originate from a variety of sources. For example, it could be a character resulting from a key being pressed or released on a keyboard device, a character resulting from the processing of an input method editor, or resulting from a voice command. Yes Yes Element TextEvent
"http://www.w3.org/2001/xml-events", "click" A pointing device button is clicked over an element. The definition of a click depends on the environment configuration; i.e. may depend on the screen location or the delay between the press and release of the pointing device button. In any case, the target node must be the same between the mousedown, mouseup, and click. The sequence of these events is: {"http://www.w3.org/2001/xml-events", "mousedown"}, {"http://www.w3.org/2001/xml-events", "mouseup"}, and {"http://www.w3.org/2001/xml-events", "click"}. Note that, given the definition of a click, If one or more of the event types {"http://www.w3.org/2001/xml-events", "mouseover"}, {"http://www.w3.org/2001/xml-events", "mousemove"}, and {"http://www.w3.org/2001/xml-events", "mouseout"} occur between the press and release of the pointing device button, the event type {"http://www.w3.org/2001/xml-events", "click"} cannot occur. In the case of nested elements, this event type is always targeted at the most deeply nested element. Yes Yes Element MouseEvent
"http://www.w3.org/2001/xml-events", "mousedown" A pointing device button is pressed over an element. In the case of nested elements, this event type is always targeted at the most deeply nested element. Yes Yes Element MouseEvent
"http://www.w3.org/2001/xml-events", "mouseup" A pointing device button is released over an element. In the case of nested elements, this event type is always targeted at the most deeply nested element. Yes Yes Element MouseEvent
"http://www.w3.org/2001/xml-events", "mouseover" A pointing device is moved onto an element. In the case of nested elements, this event type is always targeted at the most deeply nested element. Yes Yes Element MouseEvent
"http://www.w3.org/2001/xml-events", "mousemove" A pointing device is moved while it is over an element. In the case of nested elements, this event type is always targeted at the most deeply nested element. Yes Yes Element MouseEvent
"http://www.w3.org/2001/xml-events", "mouseout" A pointing device is moved away from an element. In the case of nested elements, this event type is always targeted at the most deeply nested element. Yes Yes Element MouseEvent
"http://www.w3.org/2001/xml-events", "keydown" A key is pressed down. This event type is device dependent and relies on the capabilities of the input devices and how they are mapped in the operating system. This event type is generated after the keyboard mapping but before the processing of the input method editor. This event should logically happen before the event {"http://www.w3.org/2001/xml-events", "keyup"} is produced. Yes Yes Element KeyboardEvent
"http://www.w3.org/2001/xml-events", "keyup" A key is released. This event type is device dependent and relies on the capabilities of the input devices and how they are mapped in the operating system. This event type is generated after the keyboard mapping but before the processing of the input method editor. This event should logically happen after the event {"http://www.w3.org/2001/xml-events", "keydown"} is produced. Yes Yes Element KeyboardEvent
"http://www.w3.org/2001/xml-events", "DOMSubtreeModified" This is a general event for notification of all changes to the document. It can be used instead of the more specific events listed below. It may be dispatched after a single modification to the document or, at the implementation's discretion, after multiple changes have occurred. The latter use should generally be used to accommodate multiple changes which occur either simultaneously or in rapid succession. The target of this event is the lowest common parent of the changes which have taken place. This event is dispatched after any other events caused by the mutation(s) have occurred. Yes No Document, DocumentFragment, Element, Attr MutationEvent
"http://www.w3.org/2001/xml-events", "DOMNodeInserted" A node has been added as a child of another node. This event is dispatched after the insertion has taken place. The target node of this event is the node being inserted. Yes No Element, Attr, Text, Comment, CDATASection, DocumentType, EntityReference, ProcessingInstruction MutationEvent
"http://www.w3.org/2001/xml-events", "DOMNodeRemoved" A node is being removed from its parent node. This event is dispatched before the node is removed from the tree. The target node of this event is the node being removed. Yes No Element, Attr, Text, Comment, CDATASection, DocumentType, EntityReference, ProcessingInstruction MutationEvent
"http://www.w3.org/2001/xml-events", "DOMNodeRemovedFromDocument" A node is being removed from a document, either through direct removal of the node or removal of a subtree in which it is contained. This event is dispatched before the removal takes place. The target node of this event type is the node being removed. If the node is being directly removed, the event type {"http://www.w3.org/2001/xml-events", "DOMNodeRemoved"} will fire before this event type. No No Element, Attr, Text, Comment, CDATASection, DocumentType, EntityReference, ProcessingInstruction MutationEvent
"http://www.w3.org/2001/xml-events", "DOMNodeInsertedIntoDocument" A node is being inserted into a document, either through direct insertion of the node or insertion of a subtree in which it is contained. This event is dispatched after the insertion has taken place. The target node of this event is the node being inserted. If the node is being directly inserted, the event type {"http://www.w3.org/2001/xml-events", "DOMNodeInserted"} will fire before this event type. No No Element, Attr, Text, Comment, CDATASection, DocumentType, EntityReference, ProcessingInstruction MutationEvent
"http://www.w3.org/2001/xml-events", "DOMAttrModified" Occurs after an Attr has been modified on a node. The target node of this event is the parent Element node whose Attr changed. It is expected that string based replacement of an Attr value will be viewed as a modification of the Attr since its identity does not change. Subsequently replacement of the Attr node with a different Attr node is viewed as the removal of the first Attr node and the addition of the second. Yes No Element MutationEvent
"http://www.w3.org/2001/xml-events", "DOMCharacterDataModified" Occurs after CharacterData.data or ProcessingInstruction.data have been modified but the node itself has not been inserted or deleted. The target node of this event is the CharacterData node or the ProcessingInstruction node. Yes No Text, Comment, CDATASection, ProcessingInstruction MutationEvent
"http://www.w3.org/2001/xml-events", "DOMElementNameChanged" Occurs after the namespaceURI and/or the nodeName of an Element node have been modified (e.g., the element was renamed using Document.renameNode). The target of this event is the renamed Element node. Yes No Element MutationNameEvent
"http://www.w3.org/2001/xml-events", "DOMAttributeNameChanged" Occurs after the namespaceURI and/or the nodeName of a Attr node have been modified (e.g., the attribute was renamed using Document.renameNode). The target of this event is the parent Element node whose Attr has been renamed. Yes No Element MutationNameEvent
"http://www.w3.org/2001/xml-events", "load" The DOM Implementation finishes loading in the environment the document or a resource linked from it. No No Element Event
"http://www.w3.org/2001/xml-events", "unload" The DOM implementation removes from the environment the document or a resource linked from it. No No Element Event
"http://www.w3.org/2001/xml-events", "abort" The loading of the document, or a resource linked from it, is stopped before being entirely loaded. Yes No Element Event
"http://www.w3.org/2001/xml-events", "error" The document, or a resource linked from it, has been loaded but cannot be interpreted according to its semantic, such as an invalid image or a script execution error. Yes No Element Event
"http://www.w3.org/2001/xml-events", "select" A user selects some text. DOM Level 3 Events does not provide contextual information to access the selected text. Yes No Element Event
"http://www.w3.org/2001/xml-events", "change" A control loses the input focus and its values has been modified since gaining focus. Yes No Element Event
"http://www.w3.org/2001/xml-events", "submit" A form, such as [HTML 4.01], [XHTML 1.0], or [XForms 1.0] forms, is submitted. Yes Yes Element Event
"http://www.w3.org/2001/xml-events", "reset" A form, such as [HTML 4.01], [XHTML 1.0], or [XForms 1.0] forms, is reset. Yes Yes Element Event
"http://www.w3.org/2001/xml-events", "resize" A document view is resized. Yes No Document UIEvent
"http://www.w3.org/2001/xml-events", "scroll" A document view is scrolled. Yes No Document UIEvent

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.

1.4.2. Compatibility with DOM Level 2 Events

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 DOM event flow. 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 DOM event flow.

1.5. Event listener registration

Note: This section is informative.

There are mainly two ways to associate an event listener to a node in the tree:

  1. at the programming level using the EventTarget methods.
  2. at the document level using [XML Events] or an ad-hoc syntax, as the ones provided in [XHTML 1.0] or [SVG 1.0].

1.5.1. Using the EventTarget methods

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

myCircle.addEventListenerNS("http://www.w3.org/2001/xml-events",
                            "DOMActivate",
                            myListener,
                            true,
                            myEvtGroup);

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.

1.5.2. Using XML Events

In [XML Events], event listeners are attached using elements and attributes:

<listener event="DOMActivate" observer="myCircle" handler="#myListener"
          phase="capture" propagate="stop"/>

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. [XML Events] 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 [XML Schema Part 2].

1.5.3. Using XML or HTML attributes

In languages such as [HTML 4.01], [XHTML 1.0], or [SVG 1.0], event listeners are specified as attributes:

<circle id="myCircle" onactivate="myListener(evt)"
        cx="300" cy="225" r="100" fill="red"/>

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.

1.6. Basic interfaces

The interfaces described in this section are fundamental to DOM Level 3 Events and must always be supported by the implementation.

Interface Event (introduced in DOM Level 2)

The Event interface is used to provide contextual information about an event to the listener processing the event. An object which implements the Event interface is passed as the parameter to an EventListener. More specific context information is passed to event listeners by deriving additional interfaces from Event which contain information directly relating to the type of event they represent. These derived interfaces are also implemented by the object passed to the event listener.


IDL Definition
// Introduced in DOM Level 2:
interface Event {

  // PhaseType
  const unsigned short      CAPTURING_PHASE                = 1;
  const unsigned short      AT_TARGET                      = 2;
  const unsigned short      BUBBLING_PHASE                 = 3;

  readonly attribute DOMString       type;
  readonly attribute EventTarget     target;
  readonly attribute EventTarget     currentTarget;
  readonly attribute unsigned short  eventPhase;
  readonly attribute boolean         bubbles;
  readonly attribute boolean         cancelable;
  readonly attribute DOMTimeStamp    timeStamp;
  void               stopPropagation();
  void               preventDefault();
  void               initEvent(in DOMString eventTypeArg, 
                               in boolean canBubbleArg, 
                               in boolean cancelableArg);
  // Introduced in DOM Level 3:
  readonly attribute DOMString       namespaceURI;
  // Introduced in DOM Level 3:
  boolean            isCustom();
  // Introduced in DOM Level 3:
  void               stopImmediatePropagation();
  // Introduced in DOM Level 3:
  boolean            isDefaultPrevented();
  // Introduced in DOM Level 3:
  boolean            isPropagationStopped();
  // Introduced in DOM Level 3:
  void               initEventNS(in DOMString namespaceURIArg, 
                                 in DOMString eventTypeArg, 
                                 in boolean canBubbleArg, 
                                 in boolean cancelableArg);
};

Definition group PhaseType

An integer indicating which phase of the event flow is being processed as defined in DOM event flow.

Defined Constants
AT_TARGET
The current event is in the target phase, i.e. it is being evaluated at the event target.
BUBBLING_PHASE
The current event phase is the bubbling phase.
CAPTURING_PHASE
The current event phase is the capture phase.
Attributes
bubbles of type boolean, readonly
Used to indicate whether or not an event is a bubbling event. If the event can bubble the value is true, otherwise the value is false.
cancelable of type boolean, readonly
Used to indicate whether or not an event can have its default action prevented (see also Default actions and cancelable events). If the default action can be prevented the value is true, otherwise the value is false.
currentTarget of type EventTarget, readonly
Used to indicate the EventTarget whose EventListeners are currently being processed. This is particularly useful during the capture and bubbling phases. This attribute could contain the target node or a target ancestor when used with the DOM event flow.
eventPhase of type unsigned short, readonly
Used to indicate which phase of event flow is currently being accomplished.
namespaceURI of type DOMString, readonly, introduced in DOM Level 3
The namespace URI associated with this event at creation time, or null if it is unspecified.
For events initialized with a DOM Level 2 Events method, such as initEvent, this is always null.
target of type EventTarget, readonly
Used to indicate the event target. This attribute contain the target node when used with the DOM event flow.
timeStamp of type DOMTimeStamp, readonly
Used to specify the time (in milliseconds relative to the epoch) at which the event was created. Due to the fact that some systems may not provide this information the value of timeStamp may be not available for all events. When not available, a value of 0 will be returned. Examples of epoch time are the time of the system start or 0:0:0 UTC 1st January 1970.
type of type DOMString, readonly
The name must be an NCName as defined in [XML Namespaces] and is case-sensitive. The character ":" (colon) should not be used in this attribute.
If the attribute Event.namespaceURI is different from null, this attribute represents a local name.
Methods
initEvent
The initEvent method is used to initialize the value of an Event created through the DocumentEvent.createEvent method. This method may only be called before the Event has been dispatched via the EventTarget.dispatchEvent method. If the method is called several times before invoking EventTarget.dispatchEvent, only the final invocation takes precedence. If called from a subclass of Event interface only the values specified in this method are modified, all other attributes are left unchanged.
This method sets the Event.type attribute to eventTypeArg, and Event.localName and Event.namespaceURI to null. To initialize an event with a local name and namespace URI, use the initEventNS method.
Parameters
eventTypeArg of type DOMString
Specifies the event type.
canBubbleArg of type boolean
Specifies whether or not the event can bubble. This parameter overrides the intrinsic bubbling behavior of the event.
cancelableArg of type boolean
Specifies whether or not the event's default action can be prevented. This parameter overrides the intrinsic cancelable behavior of the event.
No Return Value
No Exceptions
initEventNS introduced in DOM Level 3
The initEventNS method is used to initialize the value of an Event created through the DocumentEvent interface. This method may only be called before the Event has been dispatched via the dispatchEvent method, though it may be called multiple times the event has been dispatched. If called multiple times the final invocation takes precedence. If a call to initEventNS is made after one of the Event derived interfaces' init methods has been called, only the values specified in the initEventNS method are modified, all other attributes are left unchanged.
This method sets the Event.type attribute to eventTypeArg, and Event.namespaceURI to namespaceURIArg.
Parameters
namespaceURIArg of type DOMString
Specifies the namespace URI associated with this event, or null if no namespace.
eventTypeArg of type DOMString
Specifies the local name of the event type (see also the description of 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 prevented.
No Return Value
No Exceptions
isCustom introduced in DOM Level 3
This method will always return false, unless the event implements the CustomEvent interface.
Return Value

boolean

true if preventDefault() has been called for this event.
No Parameters
No Exceptions
isDefaultPrevented introduced in DOM Level 3
This method will return true if the method preventDefault() has been called for this event, false otherwise.
Return Value

boolean

true if preventDefault() has been called for this event.
No Parameters
No Exceptions
isPropagationStopped introduced in DOM Level 3
This method will return true if the method stopPropagation() has been called for this event in the current group, false in any other cases.
Return Value

boolean

true if the event propagation has been stopped in the current group.
No Parameters
No Exceptions
preventDefault
If an event is cancelable, the preventDefault method is used to signify that the event is to be canceled, meaning any default action normally taken by the implementation as a result of the event will not occur (see also Default actions and cancelable events), and thus independently of event groups. Calling this method for a non-cancelable event has no effect.

Note: This method does not stop the event propagation; use stopPropagation or stopImmediatePropagation for that effect.

No Parameters
No Return Value
No Exceptions
stopImmediatePropagation introduced in DOM Level 3
This method is used to prevent event listeners of the same group to be triggered and, unlike stopPropagation its effect is immediate (see Event propagation and event groups). Once it has been called, further calls to that method have no additional effect.

Note: This method does not prevent the default action from being invoked; use preventDefault for that effect.

No Parameters
No Return Value
No Exceptions
stopPropagation
This method is used to prevent event listeners of the same group to be triggered but its effect is differed until all event listeners attached on the currentTarget have been triggered (see Event propagation and event groups). Once it has been called, further calls to that method have no additional effect.

Note: This method does not prevent the default action from being invoked; use preventDefault for that effect.

No Parameters
No Return Value
No Exceptions
Interface EventTarget (introduced in DOM Level 2)

The EventTarget interface is implemented by all the objects which could be event targets in an implementation which supports the Event flows. The interface allows registration, removal or query of event listeners, and dispatch of events to an event target.

When used with DOM event flow, this interface is implemented by all target nodes and target ancestors, i.e. all DOM Nodes of the tree support this interface when the implementation conforms to DOM Level 3 Events and, therefore, this interface can be obtained by using binding-specific casting methods on an instance of the Node interface.

When using addEventListener or addEventListenerNS, if multiple identical EventListeners are registered on the same EventTarget with the same parameters the duplicate instances are discarded. They do not cause the EventListener to be called twice and since they are discarded they do not need to be removed.


IDL Definition
// Introduced in DOM Level 2:
interface EventTarget {
  void               addEventListener(in DOMString type, 
                                      in EventListener listener, 
                                      in boolean useCapture);
  void               removeEventListener(in DOMString type, 
                                         in EventListener listener, 
                                         in boolean useCapture);
  // Modified in DOM Level 3:
  boolean            dispatchEvent(in Event evt)
                                        raises(EventException);
  // Introduced in DOM Level 3:
  void               addEventListenerNS(in DOMString namespaceURI, 
                                        in DOMString type, 
                                        in EventListener listener, 
                                        in boolean useCapture, 
                                        in EventListenerGroup evtGroup);
  // Introduced in DOM Level 3:
  void               removeEventListenerNS(in DOMString namespaceURI, 
                                           in DOMString type, 
                                           in EventListener listener, 
                                           in boolean useCapture, 
                                           in EventListenerGroup evtGroup);
  // Introduced in DOM Level 3:
  boolean            willTriggerNS(in DOMString namespaceURI, 
                                   in DOMString type);
  // Introduced in DOM Level 3:
  boolean            hasEventListenerNS(in DOMString namespaceURI, 
                                        in DOMString type);
};

Methods
addEventListener
This method allows the registration of an event listener in the default group and, depending on the useCapture parameter, on the capture phase of the DOM event flow or its target and bubbling phases.
Parameters
type of type DOMString
Specifies the Event.type associated with the event for which the user is registering.
listener of type EventListener
The listener parameter takes an object implemented by the user which implements the EventListener interface and contains the method to be called when the event occurs.
useCapture of type boolean
If true, useCapture indicates that the user wishes to add the event listener for the capture phase only, i.e. this event listener will not be triggered during the target and bubbling phases. If false, the event listener will only be triggered during the target and bubbling phases.
No Return Value
No Exceptions
addEventListenerNS introduced in DOM Level 3
This method allows the registration of an event listener in a specified group or the default group and, depending on the useCapture parameter, on the capture phase of the DOM event flow or its target and bubbling phases.
Parameters
namespaceURI of type DOMString
Specifies the Event.namespaceURI associated with the event for which the user is registering.
type of type DOMString
Specifies the Event.type associated with the event for which the user is registering.
listener of type EventListener
The listener parameter takes an object implemented by the user which implements the EventListener interface and contains the method to be called when the event occurs.
useCapture of type boolean
If true, useCapture indicates that the user wishes to add the event listener for the capture phase only, i.e. this event listener will not be triggered during the target and bubbling phases. If false, the event listener will only be triggered during the target and bubbling phases.
evtGroup of type EventListenerGroup
The EventListenerGroup to associate with the EventListener (see also Event propagation and event groups). Use null to attach the event listener to the default group.
No Return Value
No Exceptions
dispatchEvent modified in DOM Level 3
This method allows the dispatch of events into the implementation's event model. The event target of the event is the EventTarget object on which dispatchEvent is called.
Issue dispatchEvent-1:
It is necessary to have an exception that occurs if the specified event is not an event which the implementation knows how to dispatch, if it was not created by calling DocumentEvent.createEvent and Event.isCustom() is false. NOT_SUPPORTED?
Parameters
evt of type Event
The event to be dispatched.
Return Value

boolean

Indicates whether any of the listeners which handled the event called preventDefault. If preventDefault was called the returned value is false, else it is true.
Exceptions

EventException

UNSPECIFIED_EVENT_TYPE_ERR: Raised if the Event.type was not specified by initializing the event before dispatchEvent was called. Specification of the Event.type as null or an empty string will also trigger this exception.

DISPATCH_REQUEST_ERR: Raised if the Event object is already being dispatched in the tree.
hasEventListenerNS introduced in DOM Level 3
This method allows the DOM application to know if this EventTarget contains an event listener registered for the specified event type. This is useful for determining at which nodes within a hierarchy altered handling of specific event types has been introduced, but should not be used to determine whether the specified event type triggers an event listener (see willTriggerNS).
Issue canTriggerOnTarget-useCapture:
do we need a useCapture parameter?
Resolution: No use case for that.
Parameters
namespaceURI of type DOMString
Specifies the Event.namespaceURI associated with the event.
type of type DOMString
Specifies the Event.type associated with the event.
Return Value

boolean

true if an event listener is registered on this EventTarget for the specified event type, false otherwise.
No Exceptions
removeEventListener
This method allows the removal of event listeners from the default group.
Calling removeEventListener with arguments which do not identify any currently registered EventListener on the EventTarget has no effect.
Parameters
type of type DOMString
Specifies the Event.type for which the user registered the event listener.
listener of type EventListener
The EventListener to be removed.
useCapture of type boolean
Specifies whether the EventListener being removed was registered for the capture phase or not. If a listener was registered twice, once for the capture phase and once for the target and bubbling phases, each must be removed separately. Removal of an event listener registered for the capture phase does not affect the same event listener registered for the target and bubbling phases, and vice versa.
No Return Value
No Exceptions
removeEventListenerNS introduced in DOM Level 3
This method allows the removal of event listeners from a specified group or the default group.
Calling removeEventListenerNS with arguments which do not identify any currently registered EventListener on the EventTarget has no effect.
Parameters
namespaceURI of type DOMString
Specifies the Event.namespaceURI associated with the event for which the user registered the event listener.
type of type DOMString
Specifies the Event.type associated with the event for which the user registered the event listener.
listener of type EventListener
The EventListener parameter indicates the EventListener to be removed.
useCapture of type boolean
Specifies whether the EventListener being removed was registered for the capture phase or not. If a listener was registered twice, once for the capture phase and once for the target and bubbling phases, each must be removed separately. Removal of an event listener registered for the capture phase does not affect the same event listener registered for the target and bubbling phases, and vice versa.
evtGroup of type EventListenerGroup
The EventListenerGroup associated with the EventListener. Use null to reference the default group.
No Return Value
No Exceptions
willTriggerNS introduced in DOM Level 3
This method allows the DOM application to know if an event listener, attached to this EventTarget or one of its ancestors, will be triggered by the specified event type during the dispatch of the event to this event target or one of its descendants.
Parameters
namespaceURI of type DOMString
Specifies the Event.namespaceURI associated with the event.
type of type DOMString
Specifies the Event.type associated with the event.
Return Value

boolean

true if an event listener will be triggered on the EventTarget with the specified event type, false otherwise.
No Exceptions
Interface EventListener (introduced in DOM Level 2)

The EventListener interface is the primary way for handling events. Users implement the EventListener interface and register their event listener on an EventTarget. The users should also remove their EventListener from its EventTarget after they have completed using the listener.

Copying a Node does not copy the event listeners attached to it. Event listeners must be attached to the newly created Node afterwards if so desired. Therefore, Nodes are copied using Node.cloneNode or Range.cloneContents, the EventListeners attached to the source Nodes are not attached to their copies.

Moving a Node does not affect the event listeners attached to it. Therefore, when Nodes are moved using Document.adoptNode, Node.appendChild, or Range.extractContents, the EventListeners attached to the moved Nodes stay attached to them.


IDL Definition
// Introduced in DOM Level 2:
interface EventListener {
  void               handleEvent(in Event evt);
};

Methods
handleEvent
This method is called whenever an event occurs of the event type for which the EventListener interface was registered.
Parameters
evt of type Event
The Event contains contextual information about the event.
No Return Value
No Exceptions
Interface EventListenerGroup (introduced in DOM Level 3)

Event listeners can be registered using Event.addEventListenerNS within a group.

When a set of actions associated with event listeners is critical for an application such as refreshing the display, it is important to separate them from other event listeners who might stop the event flow. In order to prevent undesirable side effects, the application should create a group using DocumentEvent.createEventListenerGroup and use it when adding or removing event listeners.


IDL Definition
// Introduced in DOM Level 3:
interface EventListenerGroup {
  boolean            isSameEventListenerGroup(in EventListenerGroup other);
};

Methods
isSameEventListenerGroup
This method checks if the supplied EventListenerGroup is the same as the EventListenerGroup upon which the method is called.
Parameters
other of type EventListenerGroup
The EventListenerGroup with which to check equality.
Return Value

boolean

Returns true if the EventListenerGroups are the same, else returns false.

Issue isSameEventListenerGroup-equal:
We should clarify what "equal" means here, or better yet, substitute it with "is the same"?
No Exceptions
Exception EventException introduced in DOM Level 2

Event operations may throw an EventException as specified in their method descriptions.


IDL Definition
// Introduced in DOM Level 2:
exception EventException {
  unsigned short   code;
};
// EventExceptionCode
const unsigned short      UNSPECIFIED_EVENT_TYPE_ERR     = 0;
// Introduced in DOM Level 3:
const unsigned short      DISPATCH_REQUEST_ERR           = 1;

Definition group EventExceptionCode

An integer indicating the type of error generated.

Defined Constants
DISPATCH_REQUEST_ERR, introduced in DOM Level 3.
If the Event object is already dispatched in the tree.
UNSPECIFIED_EVENT_TYPE_ERR
If the Event.type was not specified by initializing the event before the method was called. Specification of the Event.type as null or an empty string will also trigger this exception.

1.6.1. Event creation

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.

Interface DocumentEvent (introduced in DOM Level 2)

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


IDL Definition
// Introduced in DOM Level 2:
interface DocumentEvent {
  Event              createEvent(in DOMString eventType)
                                        raises(DOMException);
  // Introduced in DOM Level 3:
  EventListenerGroup createEventListenerGroup();
  // Introduced in DOM Level 3:
  boolean            canDispatch(in DOMString namespaceURI, 
                                 in DOMString type);
};

Methods
canDispatch introduced in DOM Level 3
Test if the implementation can generate events of a specified type.
Parameters
namespaceURI of type DOMString
Specifies the Event.namespaceURI of the event.
type of type DOMString
Specifies the Event.type of the event.
Return Value

boolean

true if the implementation can generate and dispatch this event type, false otherwise.
No Exceptions
createEvent
Parameters
eventType of type DOMString
The eventType parameter specifies the name of the DOM Events interface to be supported by the created event object, e.g. "Event", "MouseEvent", "MutationEvent" ... If the Event is to be dispatched via the EventTarget.dispatchEvent method the appropriate event init method must be called after creation in order to initialize the Event's values.
As an example, a user wishing to synthesize some kind of UIEvent would call DocumentEvent.createEvent with the parameter "UIEvent". The UIEvent.initUIEventNS method could then be called on the newly created UIEvent object to set the specific type of user interface event to be dispatched, {"http://www.w3.org/2001/xml-events", "DOMActivate"} for example, and set its context information, e.g. UIEvent.detail in this example.
The createEvent method is used in creating Events when it is either inconvenient or unnecessary for the user to create an Event themselves. In cases where the implementation provided Event is insufficient, users may supply their own Event implementations for use with the EventTarget.dispatchEvent method. However, the DOM implementation needs access to the attributes Event.currentTarget and Event.eventPhase to propagate appropriately the event in the DOM tree. Therefore users' Event implementations might need to support the CustomEvent interface for that effect.

Note: For backward compatibility reason, "UIEvents", "MouseEvents", "MutationEvents", and "HTMLEvents" feature names are valid values for the parameter eventType and represent respectively the interfaces "UIEvent", "MouseEvent", "MutationEvent", and "Event".

Return Value

Event

The newly created event object.
Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if the implementation does not support the Event interface requested.
createEventListenerGroup introduced in DOM Level 3
This method creates a new EventListenerGroup for use in the addEventListenerNS and removeEventListenerNS methods of the EventTarget interface (see also Event propagation and event groups).
Return Value

EventListenerGroup

The newly created EventListenerGroup object.
No Parameters
No Exceptions
Interface CustomEvent (introduced in DOM Level 3)

The CustomEvent interface gives access to the attributes Event.currentTarget and Event.eventPhase. It is intended to be used by the DOM Events implementation to access the underlying current target and event phase while dispatching a custom Event in the tree; it is intended to be implemented, and not used, by DOM applications.

The methods contained in this interface are not intended to be used by a DOM application, especially during the dispatch on the Event object. Changing the current target or the current phase may conduct into unpredictable results of the event flow. The DOM Events implementation should ensure that both methods return the appropriate current target and phase before invoking each event listener on the current target to protect DOM applications from malicious event listeners.

Note: If this interface is supported by the event object, Event.isCustom() must return true.


IDL Definition
// Introduced in DOM Level 3:
interface CustomEvent : Event {
  void               setCurrentTarget(in EventTarget target);
  void               setEventPhase(in unsigned short phase);
  void               setCurrentEventListenerGroup(in EventListenerGroup evtGroup);
  // Introduced in DOM Level 3:
  boolean            isImmediatePropagationStopped();
};

Methods
isImmediatePropagationStopped introduced in DOM Level 3
The isImmediatePropagationStopped method is used by the DOM Events implementation to know if the method stopImmediatePropagation() has been called for this event in the current group. It returns true if the method has been called, false otherwise.
Return Value

boolean

true if the event propagation has been stopped immediately in the current group.
No Parameters
No Exceptions
setCurrentEventListenerGroup
The setCurrentEventListenerGroup method is used by the DOM Events implementation to change the current event group on which the event is being processed.
Parameters
evtGroup of type EventListenerGroup
The specified event group. Use null to specify the default group.
No Return Value
No Exceptions
setCurrentTarget
The setCurrentTarget method is used by the DOM Events implementation to change the value of Event.currentTarget.
Parameters
target of type EventTarget
Specifies the new value for the Event.currentTarget attribute.
No Return Value
No Exceptions
setEventPhase
The setEventPhase method is used by the DOM Events implementation to change the value of Event.eventPhase.
Parameters
phase of type unsigned short
Specifies the new value for the Event.eventPhase attribute.
No Return Value
No Exceptions

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.

1.7.1. User Interface event types

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

Interface UIEvent (introduced in DOM Level 2)

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.


IDL Definition
// Introduced in DOM Level 2:
interface UIEvent : Event {
  readonly attribute views::AbstractView view;
  readonly attribute long            detail;
  void               initUIEvent(in DOMString typeArg, 
                                 in boolean canBubbleArg, 
                                 in boolean cancelableArg, 
                                 in views::AbstractView viewArg, 
                                 in long detailArg);
  // Introduced in DOM Level 3:
  void               initUIEventNS(in DOMString namespaceURI, 
                                   in DOMString typeArg, 
                                   in boolean canBubbleArg, 
                                   in boolean cancelableArg, 
                                   in views::AbstractView viewArg, 
                                   in long detailArg);
};

Attributes
detail of type long, readonly
Specifies some detail information about the Event, depending on the type of event.
view of type views::AbstractView, readonly
The view attribute identifies the AbstractView from which the event was generated.
Methods
initUIEvent
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.
Parameters
typeArg of type DOMString
Specifies the event type.
canBubbleArg of type boolean
Specifies whether or not the event can bubble. This parameter overrides the intrinsic bubbling behavior of the event.
cancelableArg of type boolean
Specifies whether or not the event's default action can be prevented. This parameter overrides the intrinsic cancelable behavior of the event.
viewArg of type views::AbstractView
Specifies the Event's AbstractView.
detailArg of type long
Specifies the Event's detail.
No Return Value
No Exceptions
initUIEventNS introduced in DOM Level 3
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.
Parameters
namespaceURI of type DOMString
Specifies the namespace URI associated with this event, or null if the application wish not to use namespaces.
typeArg of type DOMString
Specifies the event type (see also the description of the type attribute in the Event interface).
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 prevented.
viewArg of type views::AbstractView
Specifies the Event's AbstractView.
<