Document Object Model Events Tom Pixley Netscape Communications Corp. Overview of the DOM Level 2 Event Model

The DOM Level 2 Event Model is designed with two main goals. The first goal is the design of a generic event system which allows registration of event handlers, describes event flow through a tree structure, and provides basic contextual information for each event. 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 event model 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 Event Model specification define both the specification for the DOM Event Model and a number of conformant event modules designed for use within the model. The Event Model consists of the two sections on event propagation and event listener registration and the Event interface.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "Events" and "2.0" (respectively) to determine whether or not the event module is supported by the implementation. In order to fully support this module, an implementation must also support the "Core" feature defined in the DOM Level 2 Core specification . Please, refer to additional information about conformance in the DOM Level 2 Core specification .

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

Terminology

User interface events. These events are generated by user interaction through an external device (mouse, keyboard, etc.)

Device independent user interface events such as focus change messages or element triggering notifications.

Events caused by any action which modifies the structure of the document.

The process by which an event can be handled by one of the event's target's ancestors before being handled by the event's target.

The process by which an event propagates upward through its ancestors after being handled by the event's target.

A designation for events which indicates that upon handling the event the client may choose to prevent the DOM implementation from processing any default action associated with the event.

 Description of event flow

Event flow is the process through which the an event originates from the DOM implementation and is passed into the Document Object Model. The methods of event capture and event bubbling, along with various event listener registration techniques, allow the event to then be handled in a number of ways. It can be handled locally at the EventTarget level or centrally from an EventTarget higher in the document tree.

Basic event flow

Each event has an EventTarget toward which the event is directed by the DOM implementation. This EventTarget is specified in the Event's target attribute. When the event reaches the target, any event listeners registered on the EventTarget are triggered. Although all EventListeners on the EventTarget are guaranteed to be triggered by any event which is received by that EventTarget, no specification is made as to the order in which they will receive the event with regards to the other EventListeners on the EventTarget. If neither event capture or event bubbling are in use for that particular event, the event flow process will complete after all listeners have been triggered. If event capture or event bubbling is in use, the event flow will be modified as described in the sections below.

Any exceptions thrown inside an EventListener will not stop propagation of the event. It will continue processing any additional EventListener in the described manner.

It is expected that actions taken by EventListeners may cause additional events to fire. Additional events should be handled in a synchronous manner and may cause reentrancy into the event model.

 Event capture

Event capture is the process by which an EventListener registered on an ancestor of the event's target can intercept events of a given type before they are received by the event's target. Capture operates from the top of the tree, generally the Document, downward, making it the symmetrical opposite of bubbling which is described below. The chain of EventTargets from the top of the tree to the event's target is determined before the initial dispatch of the event. If modifications occur to the tree during event processing, event flow will proceed based on the initial state of the tree.

An EventListener being registered on an EventTarget may choose to have that EventListener capture events by specifying the useCapture parameter of the addEventListener method to be true. Thereafter, when an event of the given type is dispatched toward a descendant of the capturing object, the event will trigger any capturing event listeners of the appropriate type which exist in the direct line between the top of the document and the event's target. This downward propagation continues until the event's target is reached. A capturing EventListener will not be triggered by events dispatched directly to the EventTarget upon which it is registered.

If the capturing EventListener wishes to prevent further processing of the event from occurring it may call the stopProgagation method of the Event interface. This will prevent further dispatch of the event, although additional EventListeners registered at the same hierarchy level will still receive the event. Once an event's stopPropagation method has been called, further calls to that method have no additional effect. If no additional capturers exist and stopPropagation has not been called, the event triggers the appropriate EventListeners on the target itself.

Although event capture is similar to the delegation based event model in which all interested parties register their listeners directly on the target about which they wish to receive notifications, it is different in two important respects. First, event capture only allows interception of events which are targeted at descendants of the capturing EventTarget. It does not allow interception of events targeted to the capturer's ancestors, its siblings, or its sibling's descendants. Secondly, event capture is not specified for a single EventTarget, it is specified for a specific type of event. Once specified, event capture intercepts all events of the specified type targeted toward any of the capturer's descendants.

 Event bubbling

Events which are designated as bubbling will initially proceed with the same event flow as non-bubbling events. The event is dispatched to its target EventTarget and any event listeners found there are triggered. Bubbling events will then trigger any additional event listeners found by following the EventTarget's parent chain upward, checking for any event listeners registered on each successive EventTarget. This upward propagation will continue up to and including the Document. EventListeners registered as capturers will not be triggered during this phase. The chain of EventTargets from the event target to the top of the tree is determined before the initial dispatch of the event. If modifications occur to the tree during event processing, event flow will proceed based on the initial state of the tree.

Any event handler may choose to prevent further event propagation by calling the stopPropagation method of the Event interface. If any EventListener calls this method, all additional EventListeners on the current EventTarget will be triggered but bubbling will cease at that level. Only one call to stopPropagation is required to prevent further bubbling.

 Event cancelation

Some events are specified as cancelable. For these events, the DOM implementation generally has a default action associated with the event. An example of this is a hyperlink in a web browser. When the user clicks on the hyperlink the default action is generally to active that hyperlink. Before processing these events, the implementation must check for event listeners registered to receive the event and dispatch the event to those listeners. These listeners then have the option of canceling the implementation's 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.

Cancelation is accomplished by calling the Event's preventDefault method. If one or more EventListeners call preventDefault during any phase of event flow the default action will be canceled.

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

 Event listener registration Event registration interfaces &events-eventtarget; &events-eventlistener; Interaction with HTML 4.0 event listeners

In HTML 4.0, event listeners were specified as attributes of an element. As such, registration of a second event listener of the same type would replace the first listener. The DOM Event Model allows registration of multiple event listeners on a single EventTarget. To achieve this, event listeners are no longer stored as attribute values.

In order to achieve compatibility with HTML 4.0, 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. No technique is provided to allow HTML 4.0 event listeners access to the context information defined for each event.

 Event interface &events-event; &events-eventexception; DocumentEvent interface &events-documentevent; Event module definitions

The DOM Level 2 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. Any new event types defined by third parties must not begin with any upper, lower, or mixed case version of the string "DOM". This prefix is reserved for future DOM event modules. It is also strongly recommended that third parties adding their own events use their own prefix to avoid confusion and lessen the probability of conflicts with other new events.

User Interface event types

The User Interface event module is composed of events listed in HTML 4.0 and additional events which are supported in DOM Level 0 browsers.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "UIEvents" and "2.0" (respectively) to determine whether or not the User Interface event module is supported by the implementation. In order to fully support this module, an implementation must also support the "Events" feature defined in this specification and the "Views" feature defined in the DOM Level 2 Views specification . Please, refer to additional information about conformance in the DOM Level 2 Core specification .

To create an instance of the UIEvent interface, use the feature string "UIEvents" as the value of the input parameter used with the createEvent method of the DocumentEvent interface.

 &events-uievent;

The different types of such events that can occur are:

The DOMFocusIn event occurs when an EventTarget receives focus, for instance via a pointing device being moved onto an element or by tabbing navigation to the element. Unlike the HTML event focus, DOMFocusIn can be applied to any focusable EventTarget, not just FORM controls.

Bubbles: Yes

Cancelable: No

Context Info: None

The DOMFocusOut event occurs when a EventTarget loses focus, for instance via a pointing device being moved out of an element or by tabbing navigation out of the element. Unlike the HTML event blur, DOMFocusOut can be applied to any focusable EventTarget, not just FORM controls.

Bubbles: Yes

Cancelable: No

Context Info: None

The activate event occurs when an element is activated, for instance, thru a mouse click or a keypress. A numerical argument is provided to give an indication of the type of activation that occurs: 1 for a simple activation (e.g. a simple click or Enter), 2 for hyperactivation (for instance a double click or Shift Enter).

Bubbles: Yes

Cancelable: Yes

Context Info: detail (the numerical value)

Mouse event types

The Mouse event module is composed of events listed in HTML 4.0 and additional events which are supported in DOM Level 0 browsers. This event module is specifically designed for use with mouse input devices.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "MouseEvents" and "2.0" (respectively) to determine whether or not the Mouse event module is supported by the implementation. In order to fully support this module, an implementation must also support the "UIEvents" feature defined in this specification. Please, refer to additional information about conformance in the DOM Level 2 Core specification .

To create an instance of the MouseEvent interface, use the feature string "MouseEvents" as the value of the input parameter used with the createEvent method of the DocumentEvent interface.

 &events-mouseevent;

The different types of Mouse events that can occur are:

The click event occurs when the pointing device button is clicked over an element. A click is defined as a mousedown and mouseup over the same screen location. The sequence of these events is: mousedown mouseup click If multiple clicks occur at the same screen location, the sequence repeats with the detail attribute incrementing with each repetition. This event is valid for most elements.

Bubbles: Yes

Cancelable: Yes

Context Info: screenX, screenY, clientX, clientY, altKey, ctrlKey, shiftKey, metaKey, button, detail

The mousedown event occurs when the pointing device button is pressed over an element. This event is valid for most elements.

Bubbles: Yes

Cancelable: Yes

Context Info: screenX, screenY, clientX, clientY, altKey, ctrlKey, shiftKey, metaKey, button, detail

The mouseup event occurs when the pointing device button is released over an element. This event is valid for most elements.

Bubbles: Yes

Cancelable: Yes

Context Info: screenX, screenY, clientX, clientY, altKey, ctrlKey, shiftKey, metaKey, button, detail

The mouseover event occurs when the pointing device is moved onto an element. This event is valid for most elements.

Bubbles: Yes

Cancelable: Yes

Context Info: screenX, screenY, clientX, clientY, altKey, ctrlKey, shiftKey, metaKey, relatedTarget indicates the EventTarget the pointing device is exiting.

The mousemove event occurs when the pointing device is moved while it is over an element. This event is valid for most elements.

Bubbles: Yes

Cancelable: No

Context Info: screenX, screenY, clientX, clientY, altKey, ctrlKey, shiftKey, metaKey

The mouseout event occurs when the pointing device is moved away from an element. This event is valid for most elements..

Bubbles: Yes

Cancelable: Yes

Context Info: screenX, screenY, clientX, clientY, altKey, ctrlKey, shiftKey, metaKey, relatedTarget indicates the EventTarget the pointing device is entering.

Key events

The DOM Level 2 Event specification does not provide a key event module. An event module designed for use with keyboard input devices will be included in a later version of the DOM specification.

 Mutation event types

The mutation event module is designed to allow notification of any changes to the structure of a document, including attr and text modifications. It may be noted that none of the mutation events listed are designated as cancelable. This stems from the fact that it is very difficult to make use of existing DOM interfaces which cause document modifications if any change to the document might or might not take place due to cancelation of the related event. Although this is still a desired capability, it was decided that it would be better left until the addition of transactions into the DOM.

Many single modifications of the tree can cause multiple mutation events to be fired. Rather than attempt to specify the ordering of mutation events due to every possible modification of the tree, the ordering of these events is left to the implementation.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "MutationEvents" and "2.0" (respectively) to determine whether or not the Mutation event module is supported by the implementation. In order to fully support this module, an implementation must also support the "Events" feature defined in this specification. Please, refer to additional information about conformance in the DOM Level 2 Core specification .

To create an instance of the MutationEvent interface, use the feature string "MutationEvents" as the value of the input parameter used with the createEvent method of the DocumentEvent interface.

 &events-mutationevent;

The different types of Mutation events that can occur are:

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 fired 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 accomodate 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 have fired.

Bubbles: Yes

Cancelable: No

Context Info: None

Fired when a node has been added as a child of another node. This event is dispatched after the insertion has taken place. The target of this event is the node being inserted.

Bubbles: Yes

Cancelable: No

Context Info: relatedNode holds the parent node

Fired when a node is being removed from its parent node. This event is dispatched before the node is removed from the tree. The target of this event is the node being removed.

Bubbles: Yes

Cancelable: No

Context Info: relatedNode holds the parent node

Fired when 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 of this event is the Node being removed. If the Node is being directly removed the DOMNodeRemoved event will fire before the DOMNodeRemovedFromDocument event.

Bubbles: No

Cancelable: No

Context Info: None

Fired when 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 of this event is the node being inserted. If the Node is being directly inserted the DOMNodeInserted event will fire before the DOMNodeInsertedIntoDocument event.

Bubbles: No

Cancelable: No

Context Info: None

Fired after an Attr has been modified on a node. The target of this event is the Node whose Attr changed. The value of attrChange indicates whether the Attr was modified, added, or removed. The value of relatedNode indicates the Attr node whose value has been affected. 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.

Bubbles: Yes

Cancelable: No

Context Info: attrName, attrChange, prevValue, newValue, relatedNode

Fired after CharacterData within a node has been modified but the node itself has not been inserted or deleted. This event is also triggered by modifications to PI elements. The target of this event is the CharacterData node.

Bubbles: Yes

Cancelable: No

Context Info: prevValue, newValue

HTML event types

The HTML event module is composed of events listed in HTML 4.0 and additional events which are supported in DOM Level 0 browsers.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "HTMLEvents" and "2.0" (respectively) to determine whether or not the HTML event module is supported by the implementation. In order to fully support this module, an implementation must also support the "Events" feature defined in this specification. Please, refer to additional information about conformance in the DOM Level 2 Core specification .

To create an instance of the Event interface for the HTML event module, use the feature string "HTMLEvents" as the value of the input parameter used with the createEvent method of the DocumentEvent interface.

The HTML events use the base DOM Event interface to pass contextual information.

The different types of such events that can occur are:

The load event occurs when the DOM implementation finishes loading all content within a document, all frames within a FRAMESET, or an OBJECT element.

Bubbles: No

Cancelable: No

Context Info: None

The unload event occurs when the DOM implementation removes a document from a window or frame. This event is valid for BODY and FRAMESET elements.

Bubbles: No

Cancelable: No

Context Info: None

The abort event occurs when page loading is stopped before an image has been allowed to completely load. This event applies to OBJECT elements.

Bubbles: Yes

Cancelable: No

Context Info: None

The error event occurs when an image does not load properly or when an error occurs during script execution. This event is valid for OBJECT elements, BODY elements, and FRAMESET element.

Bubbles: Yes

Cancelable: No

Context Info: None

The select event occurs when a user selects some text in a text field. This event is valid for INPUT and TEXTAREA elements.

Bubbles: Yes

Cancelable: No

Context Info: None

The change event occurs when a control loses the input focus and its value has been modified since gaining focus. This event is valid for INPUT, SELECT, and TEXTAREA. element.

Bubbles: Yes

Cancelable: No

Context Info: None

The submit event occurs when a form is submitted. This event only applies to the FORM element.

Bubbles: Yes

Cancelable: Yes

Context Info: None

The reset event occurs when a form is reset. This event only applies to the FORM element.

Bubbles: Yes

Cancelable: No

Context Info: None

The focus event occurs when an element receives focus either via a pointing device or by tabbing navigation. This event is valid for the following elements: LABEL, INPUT, SELECT, TEXTAREA, and BUTTON.

Bubbles: No

Cancelable: No

Context Info: None

The blur event occurs when an element loses focus either via the pointing device or by tabbing navigation. This event is valid for the following elements: LABEL, INPUT, SELECT, TEXTAREA, and BUTTON.

Bubbles: No

Cancelable: No

Context Info: None

The resize event occurs when a document view is resized.

Bubbles: Yes

Cancelable: No

Context Info: None

The scroll event occurs when a document view is scrolled.

Bubbles: Yes

Cancelable: No

Context Info: None