This specification defines the Document Object Model Events Level 3, a generic platform- and language-neutral event system which allows registration of event handlers, describes event flow through a tree structure, and provides basic contextual information for each event. The Document Object Model Events Level 3 builds on the Document Object Model Events Level 2 [DOM Level 2 Events].

1. Document Object Model Events

Editors:: Björn Höhrmann; Philippe Le Hégaret, W3C (until November 2003); Tom Pixley, Netscape Communications Corporation (until July 2002)

1.1 Introduction
- 1.1.1 Event flows
- 1.1.2 Conformance
1.2 DOM event flow
- 1.2.1 Phases
- 1.2.2 Event listeners
1.3 Default actions and cancelable events
1.4 Activation requests and behavior
1.5 Event types
1.6 Event listener registration
1.7 Basic interfaces
- Event, CustomEvent, EventTarget, EventListener, EventException, EventExceptionCode
- 1.7.1 Event creation
  - DocumentEvent
1.8 Event module definitions

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 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:

The DOM event flow, which describe the flow of events in a tree-based structure.
A set of interfaces to access contextual information on events and to register event listeners.

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 structures. In that case, it is the responsibility of such applications to define their event flow and how it relates to the DOM event flow. An example of such use can 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 DOMActivate, DOMFocusIn, DOMFocusOut, focus, and blur accordingly to their semantics, supports the UIEvent interface, and conforms to the 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.

Note: This specification is to be understood in the context of the DOM Level 3 Core specification [DOM Level 3 Core] and the general considerations for DOM implementations apply. For example, handling of namespace URIs is discussed in XML Namespaces, and behavior in exceptional circumstances (such as when a null argument is passed when null was not expected) is discussed under DOMException.

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's ancestors higher in the tree. The event dispatching (also called event propagation) occurs in three phases and the following order:

The capture phase: the event is dispatched to the target's ancestors from the root of the tree to the direct parent of the target node.
The target phase: the event is dispatched to the target node.
The bubbling phase: the event is dispatched to the target's ancestors from the direct parent of the target node to the root of the tree.

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

The target's ancestors are determined before the initial dispatch of the event. If the target node is removed during the dispatching, or a target's ancestor is added or removed, the event propagation will always be based on the target node and the target's 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 (Event types) or event category (Event types and event categories), phase, and group (Event groups).

If the event listener is being 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}, which 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.

In general, a DOM application does not need to define and use a separate group unless other event listeners, external to the DOM application, may change the event propagation (e.g. from a concurrent DOM application, from imported functionalities that rely on the event system, etc.).

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 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 the following three conditions are all met:

they were registered for the same type of event, or the same category.
they were registered for the same phase;
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 an event listener 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 can be:

immediate: no more event listeners from the same group will be triggered by the event object (see Event.stopImmediatePropagation());
deferred 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 (see Event.stopPropagation()).

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 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. 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 do changes on the display and the DOM tree. In such case, if a DOM attribute is changed before the event is fired, cancelling the device event type will also reverse the change. A good example is the attribute HTMLInputElement.checked: as described in [DOM Level 2 HTML], the value of this property 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 property HTMLInputElement.checked will need to be changed back to its original value.

1.4 Activation requests and behavior

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 respective keyboard event.

Implementations are, however, 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.5.1 Event types and event categories

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

1.5.2 Complete list of event types

Depending on the level of DOM support, or the devices used for display (e.g. screen) or interaction (e.g., mouse, keyboard, touch screen, and voice), these event types can 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. 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 provides a non-normative summary of the event types defined in this specification. All event types are in no namespace and this specification refers to them by their local name only. All events will accomplish the capture 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). Some events will only be dispatched to a specific set of possible targets, specified using node types. Contextual information related to the event type is accessible using DOM interfaces.

type	Bubbling phase	Cancelable	Target node types	DOM interface
DOMActivate	Yes	Yes	`Element`	`UIEvent`
DOMFocusIn	Yes	No	`Element`	`UIEvent`
DOMFocusOut	Yes	No	`Element`	`UIEvent`
focus	No	No	`Element`	`UIEvent`
blur	No	No	`Element`	`UIEvent`
textInput	Yes	Yes	`Element`	`TextEvent`
click	Yes	Yes	`Element`	`MouseEvent`
mousedown	Yes	Yes	`Element`	`MouseEvent`
mouseup	Yes	Yes	`Element`	`MouseEvent`
mouseover	Yes	Yes	`Element`	`MouseEvent`
mousemove	Yes	Yes	`Element`	`MouseEvent`
mouseout	Yes	Yes	`Element`	`MouseEvent`
keydown	Yes	Yes	`Element`	`KeyboardEvent`
keyup	Yes	Yes	`Element`	`KeyboardEvent`
DOMSubtreeModified	Yes	No	`Document`, `DocumentFragment`, `Element`, `Attr`	`MutationEvent`
DOMNodeInserted	Yes	No	`Element`, `Attr`, `Text`, `Comment`, `CDATASection`, `DocumentType`, `EntityReference`, `ProcessingInstruction`	`MutationEvent`
DOMNodeRemoved	Yes	No	`Element`, `Attr`, `Text`, `Comment`, `CDATASection`, `DocumentType`, `EntityReference`, `ProcessingInstruction`	`MutationEvent`
DOMNodeRemovedFromDocument	No	No	`Element`, `Attr`, `Text`, `Comment`, `CDATASection`, `DocumentType`, `EntityReference`, `ProcessingInstruction`	`MutationEvent`
DOMNodeInsertedIntoDocument	No	No	`Element`, `Attr`, `Text`, `Comment`, `CDATASection`, `DocumentType`, `EntityReference`, `ProcessingInstruction`	`MutationEvent`
DOMAttrModified	Yes	No	`Element`	`MutationEvent`
DOMCharacterDataModified	Yes	No	`Text`, `Comment`, `CDATASection`, `ProcessingInstruction`	`MutationEvent`
DOMElementNameChanged	Yes	No	`Element`	`MutationNameEvent`
DOMAttributeNameChanged	Yes	No	`Element`	`MutationNameEvent`
load	No	No	`Document`, `Element`	`Event`
unload	No	No	`Document`, `Element`	`Event`
abort	Yes	No	`Element`	`Event`
error	Yes	No	`Element`	`Event`
select	Yes	No	`Element`	`Event`
change	Yes	No	`Element`	`Event`
submit	Yes	Yes	`Element`	`Event`
reset	Yes	Yes	`Element`	`Event`
resize	Yes	No	`Document`, `Element`	`UIEvent`
scroll	Yes	No	`Document`, `Element`	`UIEvent`

As an example, the event load will trigger event listeners attached on Element nodes for that event and on the capture and target phases. This event cannot be cancelled. If an event listener for the load event is attached to a node other than Document or Element nodes, or if it is attached to the bubbling phase only, this event listener cannot be triggered.

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

1.5.3 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. All event types in this specification are defined to be in no namespace, DOM Level 2 methods have been modified to refer to event types in no namespace when adding or removing event listeners and initializing event objects, and new methods have been added to provide equivalent functionality for event types in a namespace. A future draft of this document will provide guidelines on defining new event types.

DOM Level 3 Events considers the Event.type attribute to be case-sensitive, while DOM Level 2 Events considers Event.type to be case-insensitive.

1.6 Event listener registration

Note: This section is non-normative.

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

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

1.6.1 Using the `EventTarget` methods

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

aCircle.addEventListener("DOMActivate", aListener, false);

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

for only one of the target and bubbling phases since those phases are coupled during the registration (but the listener itself could ignore events during one of these phases if desired).
for a specific event category.

To register an event listener, DOM applications 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.6.2 Using XML Events

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

<listener event="DOMActivate" observer="aCircle" handler="#aListener"
          phase="default" propagate="stop"/>

1.6.3 Using VoiceXML Events

In [VoiceXML 2.0], event listeners are attached using elements:

<form>
  <field>
    <prompt>Please say something</prompt>
    <catch event="error.noauthorization">
     <prompt>You don't have the authorization!</prompt>
    </catch>
    <catch event="connection.disconnect.hangup">
     <prompt>Connection error</prompt>
    </catch>
    <catch event="connection.disconnect">
     <prompt>Connection error</prompt>
    </catch>
  </field>
  <catch event="error">
    <prompt>Unknown error</prompt>
  </catch>
</form>

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

1.6.4 Using XML or HTML attributes

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

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

Since only one attribute with the same name can appear on an element, it is 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, other Node types and the capture phase are not addressable with these languages. Event listeners cannot be registered for a specific group either, they are always attached to the default group.

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

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 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.
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 creation time, or null if it is unspecified.
For events initialized with a DOM Level 2 Events method, such as Event.initEvent(), this is always null.
target of type EventTarget, readonly: Used to indicate the event target. This attribute contains the target node when used with the 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

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

The initEventNS method is used to initialize the value of an Event object and 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

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 Event.stopPropagation() or Event.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 Event.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 Event.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 deferred until all event listeners attached on the Event.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 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 namespaceURI, 
                                       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

The initCustomEventNS method is used to initialize the value of a CustomEvent object and has the same behavior as Event.initEventNS().

Parameters

namespaceURI 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 the Event flows. The interface allows registration and removal 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.

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. In order to register a listener for a different event group (Event groups) the previously registered listener has to be removed first.

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

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. 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 parameters namespaceURI and evtGroup.

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: 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.
evtGroup of type DOMObject: The object that represents the event group 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.

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

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. The Event.namespaceURI for which the user registered the event listener is implied and is null.

Note: Event listeners registered for other event groups than the default group cannot be removed using this method; see EventTarget.removeEventListenerNS() for that 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 an event listener, independently of the associated event 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: 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.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.

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.

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. If the feature "Events" is supported by the Document object, the DocumentEvent interface must be implemented on the same object. If the feature "+Events" is supported by the Document object, an object that supports the DocumentEvent interface must be returned by invoking the method Node.getFeature("+Events", "3.0") on the Document object.

IDL Definition

// Introduced in DOM Level 2:
interface DocumentEvent {
  Event              createEvent(in DOMString eventType)
                                        raises(DOMException);
  // 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" and so on. 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 invoke DocumentEvent.createEvent("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, DOMActivate for example, and set its context information, e.g. UIEvent.detail in this example.
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.

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

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

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

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 object and has the same behavior as Event.initEvent().

Parameters

typeArg 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.
viewArg of type views::AbstractView: Specifies

Document Object Model (DOM) Level 3 Events Specification

Version 1.0

W3C Working Draft 13 April 2006

Abstract

Status of this document

Table of Contents

Expanded Table of Contents

W3C Copyright Notices and Licenses

W3C^® Document Copyright Notice and License

W3C^® Software Copyright Notice and License

W3C^® Short Software Notice

1. Document Object Model Events

Table of Contents

1.1 Introduction

1.1.1 Event flows

1.1.2 Conformance

1.2 DOM event flow

1.2.1 Phases

1.2.2 Event listeners

1.2.2.1 Registration of event listeners

1.2.2.2 Event groups

1.2.2.3 Triggering an event listener

1.2.2.4 Removing an event listener

1.2.2.5 Reentrance

1.2.2.6 Event propagation and event groups

1.3 Default actions and cancelable events

1.4 Activation requests and behavior

1.5 Event types

1.5.1 Event types and event categories

1.5.2 Complete list of event types

1.5.3 Compatibility with DOM Level 2 Events

1.6 Event listener registration

1.6.1 Using the `EventTarget` methods

1.6.2 Using XML Events

1.6.3 Using VoiceXML Events

1.6.4 Using XML or HTML attributes

1.7 Basic interfaces

1.7.1 Event creation

1.8 Event module definitions

1.8.1 User Interface event types

Document Object Model (DOM) Level 3 Events Specification

Version 1.0

W3C Working Draft 13 April 2006

Abstract

Status of this document

Table of Contents

Expanded Table of Contents

W3C Copyright Notices and Licenses

W3C® Document Copyright Notice and License

W3C® Software Copyright Notice and License

W3C® Short Software Notice

1. Document Object Model Events

Table of Contents

1.1 Introduction

1.1.1 Event flows

1.1.2 Conformance

1.2 DOM event flow

1.2.1 Phases

1.2.2 Event listeners

1.2.2.1 Registration of event listeners

1.2.2.2 Event groups

1.2.2.3 Triggering an event listener

1.2.2.4 Removing an event listener

1.2.2.5 Reentrance

1.2.2.6 Event propagation and event groups

1.3 Default actions and cancelable events

1.4 Activation requests and behavior

1.5 Event types

1.5.1 Event types and event categories

1.5.2 Complete list of event types

1.5.3 Compatibility with DOM Level 2 Events

1.6 Event listener registration

1.6.1 Using the EventTarget methods

1.6.2 Using XML Events

1.6.3 Using VoiceXML Events

1.6.4 Using XML or HTML attributes

1.7 Basic interfaces

1.7.1 Event creation

1.8 Event module definitions

1.8.1 User Interface event types

W3C^® Document Copyright Notice and License

W3C^® Software Copyright Notice and License

W3C^® Short Software Notice

1.6.1 Using the `EventTarget` methods