1.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 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 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 compliant event sets 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 consumer can use the hasFeature
of the DOMImplementation interface to determine whether the Event
Model has been implemented by a DOM implementation. The feature string for the
Event Model is "Events" and the version is "2.0". The existence within an implementation of each of the
individual event sets can also be queried using the hasFeature method.
Each event set describes its own feature string in the event set listing.

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.

Cancelable

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.

1.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
EventTarget level or centrally from an EventTarget higher in the document tree.

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

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

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

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

1.3.
Event listener registration

1.3.1.
Event registration interfaces

The EventTarget interface is implemented by all
Nodes in an implementation which supports the DOM Event
Model. Therefore, this interface can be obtained by using
binding-specific casting methods on an instance of the Node
interface. The interface allows registration and removal of
EventListeners on an EventTarget and dispatch
of events to that EventTarget.

This method allows the registration of event listeners on the event target.
If an EventListener is added to an EventTarget while it is
processing an event, it will not be triggered by the current actions but may be
triggered during a later stage of event flow, such as the bubbling phase.
If multiple identical EventListeners are registered on the same
EventTarget with the same parameters the duplicate instances are discarded.
They do not cause the EventListener to be called twice and since they are
discarded they do not need to be removed with the removeEventListener method.

The listener parameter takes an interface implemented by
the user which contains the methods to be called when the event occurs.

useCapture of type
boolean

If true, useCapture indicates that the user wishes to initiate
capture. After initiating capture, all events of the specified type will be
dispatched to the registered EventListener before being dispatched to any
EventTargets beneath them in the tree. Events which are bubbling upward
through the tree will not trigger an EventListener designated to use
capture.

This method allows the dispatch of events into the implementations event model. Events
dispatched in this manner will have the same capturing and bubbling behavior as events
dispatched directly by the implementation. The target of the event is the
EventTarget on which dispatchEvent is called.

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

This method allows the removal of event listeners from the event target. If an
EventListener is removed from an EventTarget while it is
processing an event, it will not be triggered by the current actions. EventListeners
can never be invoked after being removed.
Calling removeEventListener with arguments which do not identify any
currently registered EventListener on the EventTarget
has no effect.

The EventListener parameter indicates the EventListener
to be removed.

useCapture of type
boolean

Specifies whether the EventListener being removed was registered as a
capturing listener or not. If a listener was registered twice, one with capture and one
without, each must be removed separately. Removal of a capturing listener does not
affect a non-capturing version of the same listener, and vice versa.

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

When a Node is copied using the cloneNode method
the EventListeners attached to the source Node are
not attached to the copied Node. If the user wishes the same
EventListeners to be added to the newly created copy the user must add them manually.

The Event contains contextual information about the
event. It also contains the stopPropagation and
preventDefault methods which are used in determining the event's flow and default
action.

No Return Value

No Exceptions

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

1.4.
Event interface

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.

Used to specify the time (in milliseconds relative
to the epoch) at which the event was created. Due to the fact that some
systems may not provide this information the value of
timeStamp may be not available for all events. When not
available, a value of 0 will be returned. Examples of epoch time are
the time of the system start or 0:0:0 UTC 1st January 1970.

The initEvent method is used to initialize the value of an Event created through
the DocumentEvent interface. This method may only be called before the Event has
been dispatched via the dispatchEvent method, though it may be called multiple times during that
phase if necessary. If called multiple times the final invocation takes precedence. If called from a
subclass of Event interface only the values specified in the initEvent method are
modified, all other attributes are left unchanged.

Parameters

eventTypeArg of type
DOMString

Specifies the event type. This type may be any event type currently
defined in this specification or a new event type.. The string must
be an XML name.
Any new event type must not begin with any upper, lower, or mixed case version
of the string "DOM". This prefix is reserved for future DOM event sets. 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.

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. If, during any stage of event flow,
the preventDefault method is called the event is canceled.
Any default action associated with the event will not occur. Calling this method
for a non-cancelable event has no effect. Once preventDefault has been
called it will remain in effect throughout the remainder of the event's propagation. This
method may be used during any stage of event flow.

The stopPropagation method is used prevent further propagation of an event during
event flow. If this method is called by any EventListener the event will cease
propagating through the tree. The event will complete dispatch to all listeners on the current
EventTarget before event flow stops. This method may be used during any stage of
event flow.

1.5.
DocumentEvent interface

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

The eventType parameter specifies the type of Event interface
to be created. If the Event interface specified is supported by the implementation
this method will return a new Event of the interface type requested. If the
Event is to be dispatched via the dispatchEvent method the
appropriate event init method must be called after creation in order to initialize
the Event's values. As an example, a user wishing to synthesize some kind of
UIEvent would call createEvent with the parameter "UIEvents". The
initUIEvent method could then be called on the newly created UIEvent
to set the specific type of UIEvent to be dispatched and set its context information.
The createEvent method is used in creating Events when it is either
inconvenient or unnecessary for the
user to create an Event themselves. In cases where the implementation provided
Event is insufficient, users may supply their own Event
implementations for use with the dispatchEvent method.

NOT_SUPPORTED_ERR: Raised if the implementation does not support
the type of Event interface requested

1.6.
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 including lower level device dependent events, a set
of UI logical events, and a set 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 sets. 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.

1.6.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 DOM
Level 0 browsers.

A DOM consumer can use the hasFeature of the
DOMImplementation interface to determine whether the User Interface
event set has been implemented by a DOM implementation. The feature string
for this event set is "UIEvents" and the version is "2.0". This string is also used with the createEvent
method.

The initUIEvent method is used to initialize the value of a UIEvent created through
the DocumentEvent interface. This method may only be called before the UIEvent has
been dispatched via the dispatchEvent method, though it may be called multiple times during that
phase if necessary. If called multiple times, the final invocation takes precedence.

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

DOMFocusOut

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

DOMActivate

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)

1.6.2.
Mouse event types

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

A DOM consumer can use the hasFeature of the
DOMImplementation interface to determine whether the User Interface
event set has been implemented by a DOM implementation. The feature string
for this event set is "MouseEvents" and the version is "2.0". This string is also used with the createEvent
method.

The detail attribute inherited from UIEvent
indicates the number of times a mouse button has been pressed and
released over the same screen location during a user action. The
attribute value is 1 when the user begins this action and increments by 1
for each full sequence of pressing and releasing. If the user moves the
mouse between the mousedown and mouseup the value will be set to 0,
indicating that no click is occurring.

In the case of nested elements mouse events are always targeted at the
most deeply nested element. Ancestors of the targeted element may use
bubbling to obtain notification of mouse events which occur within its
descendent elements.

During mouse events caused by the depression or release of a mouse
button, button is used to indicate which mouse button
changed state. The values for button range from zero to indicate
the left button of the mouse, one to indicate the middle button if present, and
two to indicate the right button. For mice configured for left handed use in which
the button actions are reversed the values are instead read from right to left.

Used to identify a secondary EventTarget related
to a UI event. Currently this attribute is used with the mouseover event to indicate the
EventTarget which the pointing device exited and with the mouseout event to indicate the
EventTarget which the pointing device entered.

The initMouseEvent method is used to initialize the value of a MouseEvent created through
the DocumentEvent interface. This method may only be called before the MouseEvent has
been dispatched via the dispatchEvent method, though it may be called multiple times during that
phase if necessary. If called multiple times, the final invocation takes precedence.

1.6.3.
Key events

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

1.6.4.
Mutation event types

The mutation event set 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 consumer can use the hasFeature of the
DOMImplementation interface to determine whether the mutation
event set has been implemented by a DOM implementation. The feature string
for this event set is "MutationEvents" and the version is "2.0". This string is also used with the createEvent
method.

relatedNode is used to identify a secondary node related to a mutation event.
For example, if a mutation event is dispatched to a node indicating that its parent
has changed, the relatedNode is the changed parent. If an event is instead
dispatched to a subtree indicating a node was changed within it, the relatedNode
is the changed node. In the case of the DOMAttrModified event it indicates the Attr
node which was modified, added, or removed.

The initMutationEvent method is used to initialize the value of a MutationEvent created through
the DocumentEvent interface. This method may only be called before the MutationEvent has
been dispatched via the dispatchEvent method, though it may be called multiple times during that
phase if necessary. If called multiple times, the final invocation takes precedence.

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

DOMNodeInserted

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

DOMNodeRemoved

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

DOMNodeRemovedFromDocument

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

DOMNodeInsertedIntoDocument

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

DOMAttrModified

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

DOMCharacterDataModified

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

1.6.5.
HTML event types

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

A DOM consumer can use the hasFeature of the
DOMImplementation interface to determine whether the HTML
event set has been implemented by a DOM implementation. The feature string
for this event set is "HTMLEvents" and the version is "2.0". This string is also used with the createEvent
method.

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

The different types of such events that can occur are:

load

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

unload

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

abort

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

error

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

select

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

change

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

submit

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

Bubbles: Yes

Cancelable: Yes

Context Info: None

reset

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

Bubbles: Yes

Cancelable: No

Context Info: None

focus

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

blur

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.