1. Document Object Model Events

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

1.2 Event dispatch and DOM event flow

This section defines the event dispatch mechanism of the event model defined in this specification. Applications may dispatch event objects using the EventTarget.dispatchEvent() method, and implementations must dispatch event objects as if through this method. The behavior of this method depends on the event flow associated with the underlying object. An event flow describes how event objects propagate through a data structure. As an example, when an event object is dispatched to an element in an XML document, the object propagates through parts of the document, as determined by the DOM event flow which is defined at the end of this section.

Figure: graphical representation of an event dispatched in a DOM tree using the DOM event flow [SVG 1.0 version]

Event objects are always dispatched to an event target called the event's target. At the beginning of the dispatch, implementations must first determine the event object's propagation path. This is an ordered list of event targets the object may propagate to. The last item in the list is the event's target; the preceding items in the list are referred to as the target's ancestors and the immediately preceding item as the target's parent. Once determined, the propagation path cannot be changed. As an example, in the DOM event flow event listeners might change the position of the target node in the document while the event object is being dispatched; such changes do not affect the propagation path.

As the next step the event object accomplishes one or more event phases. This specification defines the following event phases. Event objects accomplish them in the specified order using the partial propagation paths as defined below. A phase is skipped if it is not supported, or if the event object's propagation has been stopped. For example, if the Event.bubbles attribute is set to false, the bubble phase is skipped, and if Event.stopPropagation() has been called prior to the dispatch, all phases will be skipped.

1. The capture phase: the event object propagates through the target's ancestors to the target's parent. This phase is also known as the capturing phase. Event listeners registered for this phase can handle the event before it reaches its target.
2. The target phase: the event object has reached the event's target. This phase is also known as the at-target phase. Event listeners registered for this phase can handle the event once it has reached its target.
3. The bubble phase: the event object propagates through the target's ancestors in reverse order, starting with the target's parent. This phase is also known as the bubbling phase. Event listeners registered for this phase can handle the event after it has reached its target.

Implementations let event objects accomplish an event phase by applying the following steps while there are pending event targets in the partial propagation path for this phase and the event object's propagation has not been stopped through Event.stopPropagation().

Firstly, the implementation must determine the current target. This is the next pending event target in the partial propagation path, starting with the first. From the perspective of an event listener this is the event target the listener has been registered on.

Secondly, the implementation must determine the current target's candidate event listeners. This is the list of all event listeners that have been registered on the current target in their order of registration. Once determined, the candidate event listeners cannot be changed, adding or removing listeners does not affect the current target's candidate event listeners.

Finally, the implementation must process all candidate event listeners in order and trigger each listener if all the following conditions are met. A listener is triggered by invoking the EventListener.handleEvent() method or an equivalent binding-specific mechanism.

• The event object's immediate propagation has not been stopped.
• The listener has been registered for this event phase.
• The listener has been registered for this event type.

As the final step of the event dispatch, for reasons of backwards compatibility, the implementation must reset the event object's internal propagation and default action prevention states. This ensures that an event object may be properly dispatched multiple times while also allowing to prevent the event objects propagation or default actions prior to the event dispatch.

The model defined above applies regardless of the specific event flow associated with an event target. Each event flow defines how the propagation path is determined and which event phases are supported. The DOM event flow is an application of this model: the propagation path for a Node object is determined by its Node.parentNode chain, and all events accomplish the capture and target phases. Whether an event accomplishes the bubble phase is defined individually for each event type. An alternate application of this model can be found in [DOM Level 3 Load and Save].

The DOM event model is reentrant. Event listeners may perform actions that cause additional events to be dispatched. Such events are handled in a synchronous manner, the event propagation that causes the event listener to be triggered will resume only after the event dispatch of the new event is completed.

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 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 Event dispatch and 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. See also Default actions and cancelable keyboard 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.

Implementations could react to an event before dispatching it and make changes to the display and the DOM tree. Preventing the default action of such an event will reverse these changes. A good example is the attribute HTMLInputElement.checked: as described in [DOM Level 2 HTML], the value of this attribute may be changed before the dispatch of the event; the user clicks on the radio button, the radio button is being checked (or unchecked) on the display, the attribute HTMLInputElement.checked is changed as well, and then the device event type click is being dispatched. If the default action of the device event type is prevented, or if the default action attached to the DOMActivate event type is prevented, the attribute HTMLInputElement.checked will need to be changed back to its original value.

1.4 Activation requests and behavior

(This section is currently being rewritten.)

Event targets may have associated activation behavior that implementations perform in response to an activation request. As an example, the typical activiation behavior associated with hyperlinks is to follow the link. Activation requests are typically initiated by users through an input device.

In terms of this specification, the activation behavior of the event target is the default action of the event type DOMActivate. DOM applications should use this event type whenever they wish to make or react to an activation request.

Implementations dispatch the DOMActivate event as default action of a click event. This click event is either part of the activation request (e.g., a user requests activiation using a mouse), or synthesized by the implementation to accomodate legacy applications. Context information of such a click event is implementation dependent.

When implementations dispatch a synthesized click event, the expectation is that they do so as default action of another event type. For example, when a user activates a hyperlink using a keyboard, the click event would be dispatched as default action of the respective keyboard event.

Implementations are required to dispatch the synthesized click event as described above even if they do not dispatch such an event (e.g., when activation is requested by a voice command, since this specification does not address event types for voice input).

Note: The activation of an event target 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.

1.5 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 used in [DOM Level 3 Core]. All events defined in this specification are in no namespace.

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. Together they define the feature Events 3.0.

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. The object passed to the event listener may also implement derived interfaces that provide access to information directly relating to the type of event they represent.

To create an instance of the Event interface, use the DocumentEvent.createEvent("Event") method call.

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:
  void               stopImmediatePropagation();
  // Introduced in DOM Level 3:
  readonly attribute boolean         defaultPrevented;
  // 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 Event dispatch and 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 Event dispatch and DOM event flow.

defaultPrevented of type boolean, readonly, introduced in DOM Level 3

Used to indicate whether Event.preventDefault() has been called for this event.

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 initialization time, or null if it is unspecified.
DOM Level 2 Events initialization methods, such as Event.initEvent(), set the value to null.

target of type EventTarget, readonly

Used to indicate the event target. This attribute contains the target node when used with the Event dispatch and DOM event flow.

timeStamp of type DOMTimeStamp, readonly

Used to specify the time at which the event was created in milliseconds relative to 1970-01-01T00:00:00Z. 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, the value is 0.

type of type DOMString, readonly

The local name of the event type. The name must be an NCName as defined in [XML Namespaces 1.1] and is case-sensitive.

Methods

initEvent

Initializes attributes 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. This method has no effect if called after the event has been dispatched. If called from a subclass of the 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.namespaceURI to null. To initialize an event with a namespace URI, use the Event.initEventNS() method.

Parameters

eventTypeArg of type DOMString

Specifies Event.type, the local name of the event type.

canBubbleArg of type boolean

Specifies Event.bubbles. This parameter overrides the intrinsic bubbling behavior of the event.

cancelableArg of type boolean

Specifies Event.cancelable. This parameter overrides the intrinsic cancelable behavior of the event.

No Return Value

No Exceptions

initEventNS introduced in DOM Level 3

Initializes attributes of an Event object. This method has the same behavior as Event.initEvent().

Parameters

namespaceURIArg of type DOMString

Specifies Event.namespaceURI, the namespace URI associated with this event, or null if no namespace.

eventTypeArg of type DOMString

Refer to the Event.initEvent() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the Event.initEvent() method for a description of this parameter.

cancelableArg of type boolean

Refer to the Event.initEvent() method for a description of this parameter.

No Return Value

No Exceptions

preventDefault

Signifies 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). Calling this method for a non-cancelable event has no effect.

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

No Parameters

No Return Value

No Exceptions

stopImmediatePropagation introduced in DOM Level 3

Prevents other event listeners from being triggered and, unlike Event.stopPropagation() its effect is immediate . Once it has been called, further calls to this method have no additional effect.

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

No Parameters

No Return Value

No Exceptions

stopPropagation

Prevents other event listeners from being triggered but its effect is deferred until all event listeners attached on the Event.currentTarget have been triggered . Once it has been called, further calls to this method have no additional effect.

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

No Parameters

No Return Value

No Exceptions

Interface CustomEvent (introduced in DOM Level 3)

The CustomEvent interface is the recommended interface for application-specific event types. Unlike the Event interface, it allows applications to provide contextual information about the event type. Application-specific event types should have an associated namespace to avoid clashes with future general-purpose event types.

To create an instance of the CustomEvent interface, use the DocumentEvent.createEvent("CustomEvent") method call.

IDL Definition

// Introduced in DOM Level 3:
interface CustomEvent : Event {
  readonly attribute DOMObject       detail;
  void               initCustomEventNS(in DOMString namespaceURIArg, 
                                       in DOMString typeArg, 
                                       in boolean canBubbleArg, 
                                       in boolean cancelableArg, 
                                       in DOMObject detailArg);
};

Attributes

detail of type DOMObject, readonly

Specifies some detail information about the Event.

Methods

initCustomEventNS

Initializes attributes of a CustomEvent object. This method has the same behavior as Event.initEventNS().

Parameters

namespaceURIArg of type DOMString

Refer to the Event.initEventNS() method for a description of this parameter.

typeArg of type DOMString

Refer to the Event.initEventNS() method for a description of this parameter.

canBubbleArg of type boolean

Refer to the Event.initEventNS() method for a description of this parameter.

cancelableArg of type boolean

Refer to the Event.initEventNS() method for a description of this parameter.

detailArg of type DOMObject

Specifies CustomEvent.detail. This value may be null.

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 an event flow. The interface allows registration and removal of event listeners, and dispatch of events to an event target.

When used with the 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.

Invoking addEventListener or addEventListenerNS repeatedly on the same EventTarget with the same values for the parameters namespaceURI, type, listener, and useCapture has no effect. Doing so does not cause the EventListener to be called more than once and does not cause a change in the triggering order.

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, 
                                               DOMException);
  // Introduced in DOM Level 3:
  void               addEventListenerNS(in DOMString namespaceURI, 
                                        in DOMString type, 
                                        in EventListener listener, 
                                        in boolean useCapture);
  // Introduced in DOM Level 3:
  void               removeEventListenerNS(in DOMString namespaceURI, 
                                           in DOMString type, 
                                           in EventListener listener, 
                                           in boolean useCapture);
};

Methods

addEventListener

Registers an event listener, depending on the useCapture parameter, on the capture phase of the DOM event flow or its target and bubbling phases. Invoking this method is equivalent to invoking addEventListenerNS with the same values for the parameters type, listener, and useCapture, and the value null for the parameter namespaceURI.

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

Registers an event listener, 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

Refer to the EventTarget.addEventListener() method for a description of this parameter.

listener of type EventListener

Refer to the EventTarget.addEventListener() method for a description of this parameter.

useCapture of type boolean

Refer to the EventTarget.addEventListener() method for a description of this parameter.

No Return Value

No Exceptions

dispatchEvent modified in DOM Level 3

Dispatches an event into the implementation's event model. The event target of the event is the EventTarget object on which dispatchEvent is called.

Parameters

evt of type Event

The event to be dispatched.

Return Value

boolean

Indicates whether any of the listeners which handled the event called Event.preventDefault(). If Event.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.
DOMException	NOT_SUPPORTED_ERR: Raised if the Event object has not been created using DocumentEvent.createEvent(). INVALID_CHARACTER_ERR: Raised if Event.type is not an NCName as defined in [XML Namespaces 1.1].

removeEventListener

Removes an event listener. Calling removeEventListener with arguments which do not identify any currently registered EventListener on the EventTarget has no effect. The Event.namespaceURI for which the user registered the event listener is implied and is null.

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

Removes an event listener. 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

Refer to the EventTarget.removeEventListener() method for a description of this parameter.

listener of type EventListener

Refer to the EventTarget.removeEventListener() method for a description of this parameter.

useCapture of type boolean

Refer to the EventTarget.removeEventListener() method for a description of this parameter.

No Return Value

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, with methods such as Node.cloneNode or Range.cloneContents, does not copy the event listeners attached to it. Event listeners must be attached to the newly created Node afterwards if so desired.

Moving a Node, with methods Document.adoptNode, Node.appendChild, or Range.extractContents, does not affect the event listeners attached to it.

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

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.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 if required. The DOM will not attempt to define all possible events. For purposes of interoperability, the DOM defines a module of user interface events including lower level device dependent events and a module of document mutation events.