WD-DOM-Level-2-19981228


2. Document Object Model Events

Editors
Tom Pixley, Netscape Communications Corporation
Chris Wilson, Microsoft Corporation

Table of contents


2.1. 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 attempt to provide standard sets of events for user interface control and document mutation notifications, including defined contextual information for each of these event sets.

The second goal of the event model is to provide a common subset of the current event systems used within Microsoft Internet Explorer 4.0 and Netscape Navigator 4.0. 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.

2.1.1. Terminology

UI events
User interface events. These events are generated by user interaction through an external device (mouse, keyboard, etc.)
UI Logical events
Device independent user interface events such as focus change messages or element triggering notifications.
Mutation events
Events caused by any action which modifies the structure of the document.
Capturing
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.
Bubbling
The process by which an event propagates upward through its ancestors after being handled by the event's target.
Cancellable
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.

2.1.2. Requirements

The following constitutes the list of requirements for the DOM Level 2 Event Model.

(ED: Not all of the requirements below are addressed in the current version of the specification. However, all of the requirements which derive from existing event systems should currently be met.)

Requirements of event flow:

Requirements of event listener registration:

Requirements of contextual event information:

Requirements of event types:



2.2. 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 target Node level or centrally from a Node higher in the document tree.

2.2.1. Basic event flow

Each event has a Node toward which the event is directed by the DOM implementation. This Node is the event target. When the event reaches the target, any event listeners registered on the Node are triggered. 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.

2.2.2. Event Capture

Event capture is the process by which an ancestor of the event's target can register to intercept events of a given type before they are received by the event's target. In existing implementations, the ability to capture is only available to certain container elements such as documents and windows. This constraint is not necessarily a requirement of the DOM event model.

Capture does not occur by default and must be explicitly activated. A Node capable of event capture initiates the capture process by calling its captureEvent method, passing in the desired event type as an argument. Thereafter, when an event of the given type is dispatched toward a descendant of the capturing object, the event will trigger any event listeners of the appropriate type registered on the capturing Node before triggering any listeners registered on the target Node.

In order for additional event handlers to receive an event once it has been captured, an explicit call must be made to the capturer's routeEvent method to continue processing of the event. The application then finds the next highest capturing Node in the direct ancestral hierarchy above the target and calls any listeners there. If no additional capturers exist, the event triggers the appropriate event listeners on the target Node.

Although event capture is similar to the delegation based event model, it is different in two important respects. First, event capture only allows interception of events which are targetted at descendants of the capturing Node. It does not allow interception of events targetted to the capturer's ancestors, its siblings, or its sibling's descendants. Secondly, event capture is not specified for a specific Node, it is specified for a specific type of event. Once specified, event capture intercepts all events of the specified type targetted toward any of the capturer's descendants.

Interface EventCapturer

The EventCapturer interface is implemented by Node's which are designated as being able to capture events.

IDL Definition
interface EventCapturer {
  void                      captureEvent(in DOMString type);
  void                      releaseEvent(in DOMString type);
  void                      routeEvent();
};

Methods
captureEvent
This method is used when a capturing Node wishes to begin capturing a particular type of event.
Parameters
type

The name of the event to be captured


This method returns nothing.
This method raises no exceptions.
releaseEvent
This method is used when a capturing Node wishes to cease capturing a particular type of event.
Parameters
type

The name of the event to be released


This method returns nothing.
This method raises no exceptions.
routeEvent
This method is called during the handling of an event by a capturing Node to continue the event's flow to additional event handlers, or if none are present, to the event's target.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.

2.2.3. 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 their target Node and any event listeners found there are triggered. Bubbling events then perform a check of the event's cancelBubble attribute. If the attribute is false, the event will then look for additional event listeners by following the Node's parent chain upward, checking for any event listeners registered on each successive Node. This upward propagation will continue all the way up to the Document unless either the bubbling process is prevented through use of the cancelBubble attribute or the rules of bubbling and capture interaction determine that bubbling should cease.

An event handler may choose to prevent continuation of the bubbling process at any time by setting the cancelBubble attribute of the event object to true. Events will always propagate upward if not explicitly prevented from doing so through use of the cancelBubble property. It is important to note that in this aspect bubbling behaves differently than capturing which must explicitly continue propagation of the event flow.

2.2.4. Interaction between capturing and bubbling

If both capturing and bubbling are used at the same time some effort is required to ensure that they don't interfere with each other, causing unintended behavior. When this situation occurs, events are still captured, routed, and bubbled normally. However, near the end of the bubbling stage, when the event reaches the Node by which it was originally captured, the event ceases bubbling. This behavior exists to prevent a single event handler from being triggered multiple times by a single event, once during event capture and again during event bubbling.

2.2.5. Event cancellation

Some events are specified as cancellable. For these events, the DOM implementation generally has a default action associatiated with the event. 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 cancelling the implementation's default action or allowing the default action to proceed. Cancellation is accomplished by setting the event's returnValue attribute to false.

2.3. Event interfaces

Interface Event

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

IDL Definition
interface Event {
           attribute  DOMString            type;
           attribute  Node                 target;
           attribute  boolean              cancelBubble;
           attribute  boolean              returnValue;
};

Attributes
type
The type property represents the event name as a string property.
target
The target property indicates the Node to which the event was originally dispatched.
cancelBubble
The cancelBubble property is used to control the bubbling phase of event propagation. If the property is set to true, the event will cease bubbling at the current level. Otherwise, the event will bubble up to its parent.
returnValue
If an event is cancellable, the returnValue property is checked by the DOM implementation after the event has been processed by its event handlers. If the returnValue is false, the DOM implementation does not execute any default actions associated with the event.
Interface UIEvent

The UIEvent interface provides specific contextual information associated with User Interface and Logical events.

IDL Definition
interface UIEvent : Event {
           attribute  long                 screenX;
           attribute  long                 screenY;
           attribute  long                 clientX;
           attribute  long                 clientY;
           attribute  boolean              altKey;
           attribute  boolean              ctrlKey;
           attribute  boolean              shiftKey;
           attribute  unsigned long        keyCode;
           attribute  unsigned long        charCode;
           attribute  unsigned short       button;
};

Attributes
screenX
screenX indicates the horizontal coordinate at which the event occurred in relative to the origin of the screen coordinate system.
screenY
screenY indicates the vertical coordinate at which the event occurred relative to the origin of the screen coordinate system.
clientX
clientX indicates the horizontal coordinate at which the event occurred relative to the DOM implementation's client area.
clientY
clientY indicates the vertical coordinate at which the event occurred relative to the DOM implementation's client area.
altKey
altKey indicates whether the 'alt' key was depressed during the firing of the event.
ctrlKey
ctrlKey indicates whether the 'ctrl' key was depressed during the firing of the event.
shiftKey
shiftKey indicates whether the 'shift' key was depressed during the firing of the event.
keyCode
The value of keyCode holds the virtual key code value of the key which was depressed if the event is a key event. Otherwise, the value is zero.
charCode
charCode holds the value of the Unicode character associated with the depressed key if the event is a key event. Otherwise, the value is zero.
button
During mouse events caused by the depression or release of a mouse button, button is used to indicate which mouse button changed state.

2.4. Event set definitions

The DOM Level 2 Event Model allows a DOM implementation to support multiple sets of events. The model has been designed to allow addition of new event sets as is required. The DOM will not attempt to define all possible events. For purposes of interoperability, the DOM will define a set of user interface events, a set of UI logical events, and a set of document mutation events.

2.4.1. User Interface event types

The User Interface event set is composed of events listed in HTML 4.0 and additional events which are supported in both Netscape Navigator 4.0 and Microsoft Internet Explorer 4.0.

click
The click event occurs when the pointing device button is clicked over an element. This attribute may be used with most elements.
dblclick
The dblclick event occurs when the pointing device button is double clicked over an element. This attribute may be used with most elements.
mousedown
The mousedown event occurs when the pointing device button is pressed over an element. This attribute may be used with most elements.
mouseup
The mouseup event occurs when the pointing device button is released over an element. This attribute may be used with most elements.
mouseover
The mouseover event occurs when the pointing device is moved onto an element. This attribute may be used with most elements.
mousemove
The mousemove event occurs when the pointing device is moved while it is over an element. This attribute may be used with most elements.
mouseout
The mouseout event occurs when the pointing device is moved away from an element. This attribute may be used with most elements.
keypress
The keypress event occurs when a key is pressed and released. This attribute may be used with most elements.
keydown
The keydown event occurs when a key is pressed down. This attribute may be used with most elements.
keyup
The keyup event occurs when a key is released. This attribute may be used with most elements.
resize
The resize event occurs when a document is resized.
scroll
The scroll event occurs when a document is scrolled.

2.4.2. Mutation event types

The mutation event set is currently under development. Although it is not included here it should be noted that it will be expected to function with the same event flow system described above. It will also provide contextual event information via the Event interface, although it is likely that it will derive a specialized Event interface for use with mutation events.

2.4.3. HTML event types

The HTML event set is composed of events listed in HTML 4.0 and additional events which are supported in both Netscape Navigator 4.0 and Microsoft Internet Explorer 4.0.

load
The load event occurs when the DOM implementation finishes loading all content within a document, all frames within a FRAMESET, or an image.
unload
The unload event occurs when the DOM implementation removes a document from a window or frame. This attribute may be used with BODY and FRAMESET elements.
abort
The abort event occurs when page loading is stopped before an image has been allowed to completely load. This attribute applies to the IMG tag.
error
The error event occurs when an image does not load properly or when an error occurs during script execution. This attribute applies to the IMG tag and to the BODY and FRAMESET tags.
select
The select event occurs when a user selects some text in a text field. This attribute may be used with the INPUT and TEXTAREA elements.
change
The change event occurs when a control loses the input focus and its value has been modified since gaining focus. This attribute applies to the following elements: INPUT, SELECT, and TEXTAREA.
submit
The submit event occurs when a form is submitted. It only applies to the FORM element.
reset
The reset event occurs when a form is reset. It only applies to the FORM element.
focus
The focus event occurs when an element receives focus either via a pointing device or by tabbing navigation. This attribute may be used with the following elements: LABEL, INPUT, SELECT, TEXTAREA, and BUTTON.
blur
The blur event occurs when an element loses focus either by the pointing device or by tabbing navigation. It may be used with the same elements as onfocus