<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--
Generated: Thu Nov 09 17:43:59 EST 2000 jfouffa.w3.org
-->
<html lang='en' xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Document Object Model Events</title>
<link rel='stylesheet' type='text/css' href='./spec.css' />
<link rel='stylesheet' type='text/css' href='W3C-REC.css' />
<link rel='next' href='idl-definitions.html' />
<link rel='contents' href='Overview.html#contents' />
<link rel='index' href='def-index.html' />
<link rel='previous' href='copyright-notice.html' />
</head>
<body>
<div class='navbar' align='center'><a accesskey='p'
href='copyright-notice.html'>previous</a> <a accesskey='n'
href='idl-definitions.html'>next</a> <a accesskey='c'
href='Overview.html#contents'>contents</a> <a accesskey='i'
href='def-index.html'>index</a>
<hr title='Navigation area separator' />
</div>
<div class='noprint' style='text-align: right'>
<p style='font-family: monospace;font-size:small'>13 November,
2000</p>
</div>
<div class='div1'><a id="Events" name='Events'></a>
<h1 id='Events-h1' class='div1'>1. Document Object Model
Events</h1>
<dl>
<dt><i>Editors</i></dt>
<dd>Tom Pixley, Netscape Communications Corp.</dd>
</dl>
<div class='noprint'>
<h2 id='table-of-contents'>Table of contents</h2>
<ul class='toc'>
<li class='tocline3'><a class='tocxref'
href='#Events-overview'>1.1. Overview of the DOM Level 2 Event
Model</a>
<ul class='toc'>
<li class='tocline4'><a class='tocxref'
href='#Events-overview-terminology'>1.1.1. Terminology</a></li>
</ul>
</li>
<li class='tocline3'><a class='tocxref' href='#Events-flow'>1.2.
Description of event flow</a>
<ul class='toc'>
<li class='tocline4'><a class='tocxref'
href='#Events-flow-basic'>1.2.1. Basic event flow</a></li>
<li class='tocline4'><a class='tocxref'
href='#Events-flow-capture'>1.2.2. Event capture</a></li>
<li class='tocline4'><a class='tocxref'
href='#Events-flow-bubbling'>1.2.3. Event bubbling</a></li>
<li class='tocline4'><a class='tocxref'
href='#Events-flow-cancelation'>1.2.4. Event cancelation</a></li>
</ul>
</li>
<li class='tocline3'><a class='tocxref'
href='#Events-registration'>1.3. Event listener registration</a>
<ul class='toc'>
<li class='tocline4'><a class='tocxref'
href='#Events-Registration-interfaces'>1.3.1. Event registration
interfaces</a>
<ul>
<li class='tocline5'><a href='#Events-EventTarget'>EventTarget</a>,
<a href='#Events-EventListener'>EventListener</a></li>
</ul>
</li>
<li class='tocline4'><a class='tocxref'
href='#Events-registration-html40'>1.3.2. Interaction with HTML 4.0
event listeners</a></li>
</ul>
</li>
<li class='tocline3'><a class='tocxref'
href='#Events-interface'>1.4. Event interface</a>
<ul class='toc'>
<li class='tocline4'><a href='#Events-Event'>Event</a>, <a
href='#Events-EventException'>EventException</a>, <a
href='#Events-EventException-EventExceptionCode'>EventExceptionCode</a></li>
</ul>
</li>
<li class='tocline3'><a class='tocxref'
href='#Events-document'>1.5. DocumentEvent interface</a>
<ul class='toc'>
<li class='tocline4'><a
href='#Events-DocumentEvent'>DocumentEvent</a></li>
</ul>
</li>
<li class='tocline3'><a class='tocxref'
href='#Events-eventgroupings'>1.6. Event module definitions</a>
<ul class='toc'>
<li class='tocline4'><a class='tocxref'
href='#Events-eventgroupings-uievents'>1.6.1. User Interface event
types</a>
<ul>
<li class='tocline5'><a href='#Events-UIEvent'>UIEvent</a></li>
</ul>
</li>
<li class='tocline4'><a class='tocxref'
href='#Events-eventgroupings-mouseevents'>1.6.2. Mouse event
types</a>
<ul>
<li class='tocline5'><a
href='#Events-MouseEvent'>MouseEvent</a></li>
</ul>
</li>
<li class='tocline4'><a class='tocxref'
href='#Events-eventgroupings-keyevents'>1.6.3. Key events</a></li>
<li class='tocline4'><a class='tocxref'
href='#Events-eventgroupings-mutationevents'>1.6.4. Mutation event
types</a>
<ul>
<li class='tocline5'><a
href='#Events-MutationEvent'>MutationEvent</a></li>
</ul>
</li>
<li class='tocline4'><a class='tocxref'
href='#Events-eventgroupings-htmlevents'>1.6.5. HTML event
types</a></li>
</ul>
</li>
</ul>
</div>
<div class='div2'><a id="Events-overview"
name='Events-overview'></a>
<h2 id='Events-overview-h2' class='div2'>1.1. Overview of the DOM
Level 2 Event Model</h2>
<p>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.</p>
<p>The second goal of the event model is to provide a common subset
of the current event systems used in <a
href='glossary.html#dt-DOM-Level-0'><em>DOM Level 0</em></a>
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.</p>
<p>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.</p>
<p>A DOM application may use the <code>hasFeature(feature,
version)</code> method of the <code>DOMImplementation</code>
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 [<a class='noxref'
href='references.html#DOMCore'>DOM Level 2 Core</a>]. Please, refer
to additional information about <a
href='http://www.w3.org/TR/DOM-Level-2-Core/introduction.html#ID-Conformance'>
<em>conformance</em></a> in the DOM Level 2 Core specification [<a
class='noxref' href='references.html#DOMCore'>DOM Level 2
Core</a>].</p>
<p>Each event module describes its own feature string in the event
module listing.</p>
<div class='div3'><a id="Events-overview-terminology"
name='Events-overview-terminology'></a>
<h3 id='Events-overview-terminology-h3' class='div3'>1.1.1.
Terminology</h3>
<dl>
<dt><b>UI events</b></dt>
<dd>User interface events. These events are generated by user
interaction through an external device (mouse, keyboard, etc.)</dd>
<dt><b>UI Logical events</b></dt>
<dd>Device independent user interface events such as focus change
messages or element triggering notifications.</dd>
<dt><b>Mutation events</b></dt>
<dd>Events caused by any action which modifies the structure of the
document.</dd>
<dt><b>Capturing</b></dt>
<dd>The process by which an event can be handled by one of the
event's target's <a
href='glossary.html#dt-ancestor'><em>ancestors</em></a> before
being handled by the event's target.</dd>
<dt><b>Bubbling</b></dt>
<dd>The process by which an event propagates upward through its <a
href='glossary.html#dt-ancestor'><em>ancestors</em></a> after being
handled by the event's target.</dd>
<dt><b>Cancelable</b></dt>
<dd>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.</dd>
</dl>
</div>
<!-- div3 Events-overview-terminology --></div>
<!-- div2 Events-overview -->
<div class='div2'><a id="Events-flow" name='Events-flow'></a>
<h2 id='Events-flow-h2' class='div2'>1.2. Description of event
flow</h2>
<p>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 <code>EventTarget</code> level or centrally from an <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
higher in the document tree.</p>
<div class='div3'><a id="Events-flow-basic"
name='Events-flow-basic'></a>
<h3 id='Events-flow-basic-h3' class='div3'>1.2.1. Basic event
flow</h3>
<p>Each event has an <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
toward which the event is directed by the DOM implementation. This
<a class='noxref'
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
is specified in the <a
href='events.html#Events-Event'><code>Event</code></a>'s
<code>target</code> attribute. When the event reaches the target,
any event listeners registered on the <a class='noxref'
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
are triggered. Although all <a
href='events.html#Events-EventListener'><code>EventListeners</code></a>
on the <a class='noxref'
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
are guaranteed to be triggered by any event which is received by
that <code>EventTarget</code>, no specification is made as to the
order in which they will receive the event with regards to the
other <a
href='events.html#Events-EventListener'><code>EventListeners</code></a>
on the <a class='noxref'
href='events.html#Events-EventTarget'><code>EventTarget</code></a>.
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.</p>
<p>Any exceptions thrown inside an <a
href='events.html#Events-EventListener'><code>EventListener</code></a>
will not stop propagation of the event. It will continue processing
any additional <a class='noxref'
href='events.html#Events-EventListener'><code>EventListener</code></a>
in the described manner.</p>
<p>It is expected that actions taken by <a
href='events.html#Events-EventListener'><code>EventListener</code></a>s
may cause additional events to fire. Additional events should be
handled in a synchronous manner and may cause reentrancy into the
event model.</p>
</div>
<!-- div3 Events-flow-basic -->
<div class='div3'><a id="Events-flow-capture"
name='Events-flow-capture'></a>
<h3 id='Events-flow-capture-h3' class='div3'>1.2.2. Event
capture</h3>
<p>Event capture is the process by which an EventListener
registered on an <a
href='glossary.html#dt-ancestor'><em>ancestor</em></a> 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 <code>Document</code>, downward, making it
the symmetrical opposite of bubbling which is described below. The
chain of <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>s
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.</p>
<p>An <a
href='events.html#Events-EventListener'><code>EventListener</code></a>
being registered on an <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
may choose to have that <a class='noxref'
href='events.html#Events-EventListener'><code>EventListener</code></a>
capture events by specifying the <code>useCapture</code> parameter
of the <code>addEventListener</code> method to be
<code>true</code>. Thereafter, when an event of the given type is
dispatched toward a <a
href='glossary.html#dt-descendant'><em>descendant</em></a> 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 <a class='noxref'
href='events.html#Events-EventListener'><code>EventListener</code></a>
will not be triggered by events dispatched directly to the <a
class='noxref'
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
upon which it is registered.</p>
<p>If the capturing <a
href='events.html#Events-EventListener'><code>EventListener</code></a>
wishes to prevent further processing of the event from occurring it
may call the <code>stopProgagation</code> method of the <a
href='events.html#Events-Event'><code>Event</code></a> interface.
This will prevent further dispatch of the event, although
additional <a class='noxref'
href='events.html#Events-EventListener'><code>EventListeners</code></a>
registered at the same hierarchy level will still receive the
event. Once an event's <code>stopPropagation</code> method has been
called, further calls to that method have no additional effect. If
no additional capturers exist and <code>stopPropagation</code> has
not been called, the event triggers the appropriate <a
class='noxref'
href='events.html#Events-EventListener'><code>EventListeners</code></a>
on the target itself.</p>
<p>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 <a href='glossary.html#dt-descendant'><em>descendants</em></a>
of the capturing <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>.
It does not allow interception of events targeted to the capturer's
<a href='glossary.html#dt-ancestor'><em>ancestors</em></a>, its <a
href='glossary.html#dt-sibling'><em>siblings</em></a>, or its
sibling's <a
href='glossary.html#dt-descendant'><em>descendants</em></a>.
Secondly, event capture is not specified for a single <a
class='noxref'
href='events.html#Events-EventTarget'><code>EventTarget</code></a>,
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 <a
href='glossary.html#dt-descendant'><em>descendants</em></a>.</p>
</div>
<!-- div3 Events-flow-capture -->
<div class='div3'><a id="Events-flow-bubbling"
name='Events-flow-bubbling'></a>
<h3 id='Events-flow-bubbling-h3' class='div3'>1.2.3. Event
bubbling</h3>
<p>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 <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
and any event listeners found there are triggered. Bubbling events
will then trigger any additional event listeners found by following
the <a class='noxref'
href='events.html#Events-EventTarget'><code>EventTarget</code></a>'s
parent chain upward, checking for any event listeners registered on
each successive <a class='noxref'
href='events.html#Events-EventTarget'><code>EventTarget</code></a>.
This upward propagation will continue up to and including the
<code>Document</code>. <a
href='events.html#Events-EventListener'><code>EventListener</code></a>s
registered as capturers will not be triggered during this phase.
The chain of <a class='noxref'
href='events.html#Events-EventTarget'><code>EventTarget</code></a>s
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.</p>
<p>Any event handler may choose to prevent further event
propagation by calling the <code>stopPropagation</code> method of
the <a href='events.html#Events-Event'><code>Event</code></a>
interface. If any <a
href='events.html#Events-EventListener'><code>EventListener</code></a>
calls this method, all additional <a class='noxref'
href='events.html#Events-EventListener'><code>EventListeners</code></a>
on the current <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
will be triggered but bubbling will cease at that level. Only one
call to <code>stopPropagation</code> is required to prevent further
bubbling.</p>
</div>
<!-- div3 Events-flow-bubbling -->
<div class='div3'><a id="Events-flow-cancelation"
name='Events-flow-cancelation'></a>
<h3 id='Events-flow-cancelation-h3' class='div3'>1.2.4. Event
cancelation</h3>
<p>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.</p>
<p>Cancelation is accomplished by calling the <a
href='events.html#Events-Event'><code>Event</code></a>'s
<code>preventDefault</code> method. If one or more <a
href='events.html#Events-EventListener'><code>EventListeners</code></a>
call <code>preventDefault</code> during any phase of event flow the
default action will be canceled.</p>
<p>Different implementations will specify their own default
actions, if any, associated with each event. The DOM does not
attempt to specify these actions.</p>
</div>
<!-- div3 Events-flow-cancelation --></div>
<!-- div2 Events-flow -->
<div class='div2'><a id="Events-registration"
name='Events-registration'></a>
<h2 id='Events-registration-h2' class='div2'>1.3. Event listener
registration</h2>
<div class='div3'><a id="Events-Registration-interfaces"
name='Events-Registration-interfaces'></a>
<h3 id='Events-Registration-interfaces-h3' class='div3'>1.3.1.
Event registration interfaces</h3>
<dl>
<dt><b>Interface <i><a id="Events-EventTarget"
name='Events-EventTarget'>EventTarget</a></i></b> (introduced in <b
class='since'>DOM Level 2</b>)</dt>
<dd>
<p>The <code>EventTarget</code> interface is implemented by all
<code>Nodes</code> 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
<code>Node</code> interface. The interface allows registration and
removal of <a
href='events.html#Events-EventListener'><code>EventListeners</code></a>
on an <code>EventTarget</code> and dispatch of events to that
<code>EventTarget</code>.</p>
<dl>
<dt><br />
<b>IDL Definition</b></dt>
<dd>
<div class='idl-code'>
<pre>
// 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);
boolean dispatchEvent(in Event evt)
raises(EventException);
};
</pre>
</div>
<br />
</dd>
<dt><b>Methods</b></dt>
<dd>
<dl>
<dt><code class='method-name'><a
id="Events-EventTarget-addEventListener"
name='Events-EventTarget-addEventListener'>addEventListener</a></code></dt>
<dd>
<div class='method'>This method allows the registration of event
listeners on the event target. If an <a
href='events.html#Events-EventListener'><code>EventListener</code></a>
is added to an <code>EventTarget</code> 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.<br />
If multiple identical <a
href='events.html#Events-EventListener'><code>EventListener</code></a>s
are registered on the same <code>EventTarget</code> with the same
parameters the duplicate instances are discarded. They do not cause
the <a class='noxref'
href='events.html#Events-EventListener'><code>EventListener</code></a>
to be called twice and since they are discarded they do not need to
be removed with the <code>removeEventListener</code> method.
<div class='parameters'><b>Parameters</b>
<div class='paramtable'>
<dl>
<dt><code class='parameter-name'>type</code> of type
<code>DOMString</code></dt>
<dd>The event type for which the user is registering<br />
</dd>
<dt><code class='parameter-name'>listener</code> of type <a
href='events.html#Events-EventListener'><code>EventListener</code></a></dt>
<dd>The <code>listener</code> parameter takes an interface
implemented by the user which contains the methods to be called
when the event occurs.<br />
</dd>
<dt><code class='parameter-name'>useCapture</code> of type
<code>boolean</code></dt>
<dd>If true, <code>useCapture</code> indicates that the user wishes
to initiate capture. After initiating capture, all events of the
specified type will be dispatched to the registered <a
class='noxref'
href='events.html#Events-EventListener'><code>EventListener</code></a>
before being dispatched to any <code>EventTargets</code> beneath
them in the tree. Events which are bubbling upward through the tree
will not trigger an <a class='noxref'
href='events.html#Events-EventListener'><code>EventListener</code></a>
designated to use capture.<br />
</dd>
</dl>
</div>
</div>
<!-- parameters -->
<div><b>No Return Value</b></div>
<div><b>No Exceptions</b></div>
</div>
<!-- method -->
</dd>
<dt><code class='method-name'><a
id="Events-EventTarget-dispatchEvent"
name='Events-EventTarget-dispatchEvent'>dispatchEvent</a></code></dt>
<dd>
<div class='method'>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 <code>EventTarget</code> on which <code>dispatchEvent</code>
is called.
<div class='parameters'><b>Parameters</b>
<div class='paramtable'>
<dl>
<dt><code class='parameter-name'>evt</code> of type <a
href='events.html#Events-Event'><code>Event</code></a></dt>
<dd>Specifies the event type, behavior, and contextual information
to be used in processing the event.<br />
</dd>
</dl>
</div>
</div>
<!-- parameters -->
<div class='return'><b>Return Value</b>
<div class='returntable'>
<table
summary='Layout table: the first cell contains the type of the return value, the second contains a short description'
border='0'>
<tr>
<td valign='top'>
<p><code>boolean</code></p>
</td>
<td>
<p>The return value of <code>dispatchEvent</code> indicates whether
any of the listeners which handled the event called
<code>preventDefault</code>. If <code>preventDefault</code> was
called the value is false, else the value is true.</p>
</td>
</tr>
</table>
</div>
</div>
<!-- return -->
<div class='exceptions'><b>Exceptions</b>
<div class='exceptiontable'>
<table
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
border='0'>
<tr>
<td valign='top'>
<p><a
href='events.html#Events-EventException'><code>EventException</code></a></p>
</td>
<td>
<p>UNSPECIFIED_EVENT_TYPE_ERR: Raised if the <a
href='events.html#Events-Event'><code>Event</code></a>'s type was
not specified by initializing the event before
<code>dispatchEvent</code> was called. Specification of the <a
class='noxref'
href='events.html#Events-Event'><code>Event</code></a>'s type as
<code>null</code> or an empty string will also trigger this
exception.</p>
</td>
</tr>
</table>
</div>
</div>
<!-- exceptions -->
</div>
<!-- method -->
</dd>
<dt><code class='method-name'><a
id="Events-EventTarget-removeEventListener"
name='Events-EventTarget-removeEventListener'>removeEventListener</a></code></dt>
<dd>
<div class='method'>This method allows the removal of event
listeners from the event target. If an <a
href='events.html#Events-EventListener'><code>EventListener</code></a>
is removed from an <code>EventTarget</code> while it is processing
an event, it will not be triggered by the current actions. <a
class='noxref'
href='events.html#Events-EventListener'><code>EventListener</code></a>s
can never be invoked after being removed.<br />
Calling <code>removeEventListener</code> with arguments which do
not identify any currently registered <a
href='events.html#Events-EventListener'><code>EventListener</code></a>
on the <code>EventTarget</code> has no effect.
<div class='parameters'><b>Parameters</b>
<div class='paramtable'>
<dl>
<dt><code class='parameter-name'>type</code> of type
<code>DOMString</code></dt>
<dd>Specifies the event type of the <a
href='events.html#Events-EventListener'><code>EventListener</code></a>
being removed.<br />
</dd>
<dt><code class='parameter-name'>listener</code> of type <a
href='events.html#Events-EventListener'><code>EventListener</code></a></dt>
<dd>The <a class='noxref'
href='events.html#Events-EventListener'><code>EventListener</code></a>
parameter indicates the <code>EventListener</code> to be
removed.<br />
</dd>
<dt><code class='parameter-name'>useCapture</code> of type
<code>boolean</code></dt>
<dd>Specifies whether the <a class='noxref'
href='events.html#Events-EventListener'><code>EventListener</code></a>
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.<br />
</dd>
</dl>
</div>
</div>
<!-- parameters -->
<div><b>No Return Value</b></div>
<div><b>No Exceptions</b></div>
</div>
<!-- method -->
</dd>
</dl>
</dd>
</dl>
</dd>
<dt><b>Interface <i><a id="Events-EventListener"
name='Events-EventListener'>EventListener</a></i></b> (introduced
in <b class='since'>DOM Level 2</b>)</dt>
<dd>
<p>The <code>EventListener</code> interface is the primary method
for handling events. Users implement the <code>EventListener</code>
interface and register their listener on an <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
using the <code>AddEventListener</code> method. The users should
also remove their <code>EventListener</code> from its <a
class='noxref'
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
after they have completed using the listener.</p>
<p>When a <code>Node</code> is copied using the
<code>cloneNode</code> method the <code>EventListener</code>s
attached to the source <code>Node</code> are not attached to the
copied <code>Node</code>. If the user wishes the same
<code>EventListener</code>s to be added to the newly created copy
the user must add them manually.</p>
<dl>
<dt><br />
<b>IDL Definition</b></dt>
<dd>
<div class='idl-code'>
<pre>
// Introduced in DOM Level 2:
interface EventListener {
void handleEvent(in Event evt);
};
</pre>
</div>
<br />
</dd>
<dt><b>Methods</b></dt>
<dd>
<dl>
<dt><code class='method-name'><a
id="Events-EventListener-handleEvent"
name='Events-EventListener-handleEvent'>handleEvent</a></code></dt>
<dd>
<div class='method'>This method is called whenever an event occurs
of the type for which the <code>EventListener</code> interface was
registered.
<div class='parameters'><b>Parameters</b>
<div class='paramtable'>
<dl>
<dt><code class='parameter-name'>evt</code> of type <a
href='events.html#Events-Event'><code>Event</code></a></dt>
<dd>The <a class='noxref'
href='events.html#Events-Event'><code>Event</code></a> contains
contextual information about the event. It also contains the
<code>stopPropagation</code> and <code>preventDefault</code>
methods which are used in determining the event's flow and default
action.<br />
</dd>
</dl>
</div>
</div>
<!-- parameters -->
<div><b>No Return Value</b></div>
<div><b>No Exceptions</b></div>
</div>
<!-- method -->
</dd>
</dl>
</dd>
</dl>
</dd>
</dl>
</div>
<!-- div3 Events-Registration-interfaces -->
<div class='div3'><a id="Events-registration-html40"
name='Events-registration-html40'></a>
<h3 id='Events-registration-html40-h3' class='div3'>1.3.2.
Interaction with HTML 4.0 event listeners</h3>
<p>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 <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>.
To achieve this, event listeners are no longer stored as attribute
values.</p>
<p>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 <code>EventListener</code>
on the <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>.
The value of <code>useCapture</code> defaults to
<code>false</code>. This <a
href='events.html#Events-EventListener'><code>EventListener</code></a>
behaves in the same manner as any other <a class='noxref'
href='events.html#Events-EventListener'><code>EventListeners</code></a>
which may be registered on the <a class='noxref'
href='events.html#Events-EventTarget'><code>EventTarget</code></a>.
If the attribute representing the event listener is changed, this
may be viewed as the removal of the previously registered <a
class='noxref'
href='events.html#Events-EventListener'><code>EventListener</code></a>
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.</p>
</div>
<!-- div3 Events-registration-html40 --></div>
<!-- div2 Events-registration -->
<div class='div2'><a id="Events-interface"
name='Events-interface'></a>
<h2 id='Events-interface-h2' class='div2'>1.4. Event interface</h2>
<dl>
<dt><b>Interface <i><a id="Events-Event"
name='Events-Event'>Event</a></i></b> (introduced in <b
class='since'>DOM Level 2</b>)</dt>
<dd>
<p>The <code>Event</code> interface is used to provide contextual
information about an event to the handler processing the event. An
object which implements the <code>Event</code> 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 <code>Event</code> 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.</p>
<dl>
<dt><br />
<b>IDL Definition</b></dt>
<dd>
<div class='idl-code'>
<pre>
// 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);
};
</pre>
</div>
<br />
</dd>
<dt><b>Definition group <i><a id="Events-Event-eventPhaseType"
name='Events-Event-eventPhaseType'>PhaseType</a></i></b></dt>
<dd>
<p>An integer indicating which phase of event flow is being
processed.</p>
<dl>
<dt><b>Defined Constants</b></dt>
<dd>
<dl>
<dt><code class='constant-name'>AT_TARGET</code></dt>
<dd>The event is currently being evaluated at the target <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>.</dd>
<dt><code class='constant-name'>BUBBLING_PHASE</code></dt>
<dd>The current event phase is the bubbling phase.</dd>
<dt><code class='constant-name'>CAPTURING_PHASE</code></dt>
<dd>The current event phase is the capturing phase.</dd>
</dl>
</dd>
</dl>
</dd>
<dt><b>Attributes</b></dt>
<dd>
<dl>
<dt><code class='attribute-name'><a id="Events-Event-canBubble"
name='Events-Event-canBubble'>bubbles</a></code> of type
<code>boolean</code>, readonly</dt>
<dd>Used to indicate whether or not an event is a bubbling event.
If the event can bubble the value is true, else the value is
false.<br />
</dd>
<dt><code class='attribute-name'><a id="Events-Event-canCancel"
name='Events-Event-canCancel'>cancelable</a></code> of type
<code>boolean</code>, readonly</dt>
<dd>Used to indicate whether or not an event can have its default
action prevented. If the default action can be prevented the value
is true, else the value is false.<br />
</dd>
<dt><code class='attribute-name'><a id="Events-Event-currentTarget"
name='Events-Event-currentTarget'>currentTarget</a></code> of type
<a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>,
readonly</dt>
<dd>Used to indicate the <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
whose <a
href='events.html#Events-EventListener'><code>EventListeners</code></a>
are currently being processed. This is particularly useful during
capturing and bubbling.<br />
</dd>
<dt><code class='attribute-name'><a id="Events-Event-eventPhase"
name='Events-Event-eventPhase'>eventPhase</a></code> of type
<code>unsigned short</code>, readonly</dt>
<dd>Used to indicate which phase of event flow is currently being
evaluated.<br />
</dd>
<dt><code class='attribute-name'><a id="Events-Event-target"
name='Events-Event-target'>target</a></code> of type <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>,
readonly</dt>
<dd>Used to indicate the <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
to which the event was originally dispatched.<br />
</dd>
<dt><code class='attribute-name'><a id="Events-Event-timeStamp"
name='Events-Event-timeStamp'>timeStamp</a></code> of type
<code>DOMTimeStamp</code>, readonly</dt>
<dd>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
<code>timeStamp</code> 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.<br />
</dd>
<dt><code class='attribute-name'><a id="Events-Event-type"
name='Events-Event-type'>type</a></code> of type
<code>DOMString</code>, readonly</dt>
<dd>The name of the event (case-insensitive). The name must be an
<a href='glossary.html#dt-XML-name'><em>XML name</em></a>.<br />
</dd>
</dl>
</dd>
<dt><b>Methods</b></dt>
<dd>
<dl>
<dt><code class='method-name'><a id="Events-Event-initEvent"
name='Events-Event-initEvent'>initEvent</a></code></dt>
<dd>
<div class='method'>The <code>initEvent</code> method is used to
initialize the value of an <code>Event</code> created through the
<a
href='events.html#Events-DocumentEvent'><code>DocumentEvent</code></a>
interface. This method may only be called before the
<code>Event</code> has been dispatched via the
<code>dispatchEvent</code> 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
<code>Event</code> interface only the values specified in the
<code>initEvent</code> method are modified, all other attributes
are left unchanged.
<div class='parameters'><b>Parameters</b>
<div class='paramtable'>
<dl>
<dt><code class='parameter-name'>eventTypeArg</code> of type
<code>DOMString</code></dt>
<dd>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 <a href='glossary.html#dt-XML-name'><em>XML
name</em></a>.<br />
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.<br />
</dd>
<dt><code class='parameter-name'>canBubbleArg</code> of type
<code>boolean</code></dt>
<dd>Specifies whether or not the event can bubble.<br />
</dd>
<dt><code class='parameter-name'>cancelableArg</code> of type
<code>boolean</code></dt>
<dd>Specifies whether or not the event's default action can be
prevented.<br />
</dd>
</dl>
</div>
</div>
<!-- parameters -->
<div><b>No Return Value</b></div>
<div><b>No Exceptions</b></div>
</div>
<!-- method -->
</dd>
<dt><code class='method-name'><a id="Events-Event-preventDefault"
name='Events-Event-preventDefault'>preventDefault</a></code></dt>
<dd>
<div class='method'>If an event is cancelable, the
<code>preventDefault</code> 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 <code>preventDefault</code>
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
<code>preventDefault</code> 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.
<div><b>No Parameters</b></div>
<div><b>No Return Value</b></div>
<div><b>No Exceptions</b></div>
</div>
<!-- method -->
</dd>
<dt><code class='method-name'><a id="Events-Event-stopPropagation"
name='Events-Event-stopPropagation'>stopPropagation</a></code></dt>
<dd>
<div class='method'>The <code>stopPropagation</code> method is used
prevent further propagation of an event during event flow. If this
method is called by any <a
href='events.html#Events-EventListener'><code>EventListener</code></a>
the event will cease propagating through the tree. The event will
complete dispatch to all listeners on the current <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
before event flow stops. This method may be used during any stage
of event flow.
<div><b>No Parameters</b></div>
<div><b>No Return Value</b></div>
<div><b>No Exceptions</b></div>
</div>
<!-- method -->
</dd>
</dl>
</dd>
</dl>
</dd>
<dt><b>Exception <i><a id="Events-EventException"
name='Events-EventException'>EventException</a></i></b> introduced
in <b class='version'>DOM Level 2</b></dt>
<dd>
<p>Event operations may throw an <a
href='events.html#Events-EventException'><code>EventException</code></a>
as specified in their method descriptions.</p>
<dl>
<dt><br />
<b>IDL Definition</b></dt>
<dd>
<div class='idl-code'>
<pre>
// Introduced in DOM Level 2:
exception EventException {
unsigned short code;
};
// EventExceptionCode
const unsigned short UNSPECIFIED_EVENT_TYPE_ERR = 0;
</pre>
</div>
<br />
</dd>
<dt><b>Definition group <i><a
id="Events-EventException-EventExceptionCode"
name='Events-EventException-EventExceptionCode'>EventExceptionCode</a></i></b></dt>
<dd>
<p>An integer indicating the type of error generated.</p>
<dl>
<dt><b>Defined Constants</b></dt>
<dd>
<dl>
<dt><code
class='constant-name'>UNSPECIFIED_EVENT_TYPE_ERR</code></dt>
<dd>If the <a
href='events.html#Events-Event'><code>Event</code></a>'s type was
not specified by initializing the event before the method was
called. Specification of the Event's type as <code>null</code> or
an empty string will also trigger this exception.</dd>
</dl>
</dd>
</dl>
</dd>
</dl>
</dd>
</dl>
</div>
<!-- div2 Events-interface -->
<div class='div2'><a id="Events-document"
name='Events-document'></a>
<h2 id='Events-document-h2' class='div2'>1.5. DocumentEvent
interface</h2>
<dl>
<dt><b>Interface <i><a id="Events-DocumentEvent"
name='Events-DocumentEvent'>DocumentEvent</a></i></b> (introduced
in <b class='since'>DOM Level 2</b>)</dt>
<dd>
<p>The <code>DocumentEvent</code> interface provides a mechanism by
which the user can create an Event of a type supported by the
implementation. It is expected that the <code>DocumentEvent</code>
interface will be implemented on the same object which implements
the <code>Document</code> interface in an implementation which
supports the Event model.</p>
<dl>
<dt><br />
<b>IDL Definition</b></dt>
<dd>
<div class='idl-code'>
<pre>
// Introduced in DOM Level 2:
interface DocumentEvent {
Event createEvent(in DOMString eventType)
raises(DOMException);
};
</pre>
</div>
<br />
</dd>
<dt><b>Methods</b></dt>
<dd>
<dl>
<dt><code class='method-name'><a
id="Events-DocumentEvent-createEvent"
name='Events-DocumentEvent-createEvent'>createEvent</a></code></dt>
<dd>
<div class='method'>
<div class='parameters'><b>Parameters</b>
<div class='paramtable'>
<dl>
<dt><code class='parameter-name'>eventType</code> of type
<code>DOMString</code></dt>
<dd>The <code>eventType</code> parameter specifies the type of <a
href='events.html#Events-Event'><code>Event</code></a> interface to
be created. If the <a class='noxref'
href='events.html#Events-Event'><code>Event</code></a> interface
specified is supported by the implementation this method will
return a new <a class='noxref'
href='events.html#Events-Event'><code>Event</code></a> of the
interface type requested. If the <a class='noxref'
href='events.html#Events-Event'><code>Event</code></a> is to be
dispatched via the <code>dispatchEvent</code> method the
appropriate event init method must be called after creation in
order to initialize the <a class='noxref'
href='events.html#Events-Event'><code>Event</code></a>'s values. As
an example, a user wishing to synthesize some kind of <a
href='events.html#Events-UIEvent'><code>UIEvent</code></a> would
call <code>createEvent</code> with the parameter "UIEvents". The
<code>initUIEvent</code> method could then be called on the newly
created <a class='noxref'
href='events.html#Events-UIEvent'><code>UIEvent</code></a> to set
the specific type of UIEvent to be dispatched and set its context
information.<br />
The <code>createEvent</code> method is used in creating <a
href='events.html#Events-Event'><code>Event</code></a>s when it is
either inconvenient or unnecessary for the user to create an <a
class='noxref'
href='events.html#Events-Event'><code>Event</code></a> themselves.
In cases where the implementation provided <a class='noxref'
href='events.html#Events-Event'><code>Event</code></a> is
insufficient, users may supply their own <a class='noxref'
href='events.html#Events-Event'><code>Event</code></a>
implementations for use with the <code>dispatchEvent</code>
method.<br />
</dd>
</dl>
</div>
</div>
<!-- parameters -->
<div class='return'><b>Return Value</b>
<div class='returntable'>
<table
summary='Layout table: the first cell contains the type of the return value, the second contains a short description'
border='0'>
<tr>
<td valign='top'>
<p><a href='events.html#Events-Event'><code>Event</code></a></p>
</td>
<td>
<p>The newly created <a class='noxref'
href='events.html#Events-Event'><code>Event</code></a></p>
</td>
</tr>
</table>
</div>
</div>
<!-- return -->
<div class='exceptions'><b>Exceptions</b>
<div class='exceptiontable'>
<table
summary='Layout table: the first cell contains the type of the exception, the second contains the specific error code and a short description'
border='0'>
<tr>
<td valign='top'>
<p><code>DOMException</code></p>
</td>
<td>
<p>NOT_SUPPORTED_ERR: Raised if the implementation does not support
the type of <a
href='events.html#Events-Event'><code>Event</code></a> interface
requested</p>
</td>
</tr>
</table>
</div>
</div>
<!-- exceptions -->
</div>
<!-- method -->
</dd>
</dl>
</dd>
</dl>
</dd>
</dl>
</div>
<!-- div2 Events-document -->
<div class='div2'><a id="Events-eventgroupings"
name='Events-eventgroupings'></a>
<h2 id='Events-eventgroupings-h2' class='div2'>1.6. Event module
definitions</h2>
<p>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.</p>
<div class='div3'><a id="Events-eventgroupings-uievents"
name='Events-eventgroupings-uievents'></a>
<h3 id='Events-eventgroupings-uievents-h3' class='div3'>1.6.1. User
Interface event types</h3>
<p>The User Interface event module is composed of events listed in
HTML 4.0 and additional events which are supported in <a
href='glossary.html#dt-DOM-Level-0'><em>DOM Level 0</em></a>
browsers.</p>
<p>A DOM application may use the <code>hasFeature(feature,
version)</code> method of the <code>DOMImplementation</code>
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 [<a class='noxref'
href='references.html#DOMViews'>DOM Level 2 Views</a>]. Please,
refer to additional information about <a
href='http://www.w3.org/TR/DOM-Level-2-Core/introduction.html#ID-Conformance'>
<em>conformance</em></a> in the DOM Level 2 Core specification [<a
class='noxref' href='references.html#DOMCore'>DOM Level 2
Core</a>].</p>
<p><b>Note:</b> To create an instance of the <a
href='events.html#Events-UIEvent'><code>UIEvent</code></a>
interface, use the feature string "UIEvents" as the value of the
input parameter used with the <code>createEvent</code> method of
the <a
href='events.html#Events-DocumentEvent'><code>DocumentEvent</code></a>
interface.</p>
<dl>
<dt><b>Interface <i><a id="Events-UIEvent"
name='Events-UIEvent'>UIEvent</a></i></b> (introduced in <b
class='since'>DOM Level 2</b>)</dt>
<dd>
<p>The <code>UIEvent</code> interface provides specific contextual
information associated with User Interface events.</p>
<dl>
<dt><br />
<b>IDL Definition</b></dt>
<dd>
<div class='idl-code'>
<pre>
// 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);
};
</pre>
</div>
<br />
</dd>
<dt><b>Attributes</b></dt>
<dd>
<dl>
<dt><code class='attribute-name'><a id="Events-UIEvent-detail"
name='Events-UIEvent-detail'>detail</a></code> of type
<code>long</code>, readonly</dt>
<dd>Specifies some detail information about the <a
href='events.html#Events-Event'><code>Event</code></a>, depending
on the type of event.<br />
</dd>
<dt><code class='attribute-name'><a id="Events-UIEvent-view"
name='Events-UIEvent-view'>view</a></code> of type
<code>views::AbstractView</code>, readonly</dt>
<dd>The <code>view</code> attribute identifies the
<code>AbstractView</code> from which the event was generated.<br />
</dd>
</dl>
</dd>
<dt><b>Methods</b></dt>
<dd>
<dl>
<dt><code class='method-name'><a id="Events-Event-initUIEvent"
name='Events-Event-initUIEvent'>initUIEvent</a></code></dt>
<dd>
<div class='method'>The <code>initUIEvent</code> method is used to
initialize the value of a <code>UIEvent</code> created through the
<a
href='events.html#Events-DocumentEvent'><code>DocumentEvent</code></a>
interface. This method may only be called before the
<code>UIEvent</code> has been dispatched via the
<code>dispatchEvent</code> method, though it may be called multiple
times during that phase if necessary. If called multiple times, the
final invocation takes precedence.
<div class='parameters'><b>Parameters</b>
<div class='paramtable'>
<dl>
<dt><code class='parameter-name'>typeArg</code> of type
<code>DOMString</code></dt>
<dd>Specifies the event type.<br />
</dd>
<dt><code class='parameter-name'>canBubbleArg</code> of type
<code>boolean</code></dt>
<dd>Specifies whether or not the event can bubble.<br />
</dd>
<dt><code class='parameter-name'>cancelableArg</code> of type
<code>boolean</code></dt>
<dd>Specifies whether or not the event's default action can be
prevented.<br />
</dd>
<dt><code class='parameter-name'>viewArg</code> of type
<code>views::AbstractView</code></dt>
<dd>Specifies the <a
href='events.html#Events-Event'><code>Event</code></a>'s
<code>AbstractView</code>.<br />
</dd>
<dt><code class='parameter-name'>detailArg</code> of type
<code>long</code></dt>
<dd>Specifies the <a
href='events.html#Events-Event'><code>Event</code></a>'s
detail.<br />
</dd>
</dl>
</div>
</div>
<!-- parameters -->
<div><b>No Return Value</b></div>
<div><b>No Exceptions</b></div>
</div>
<!-- method -->
</dd>
</dl>
</dd>
</dl>
</dd>
</dl>
<p>The different types of such events that can occur are:</p>
<dl>
<dt><b>DOMFocusIn</b></dt>
<dd>The DOMFocusIn event occurs when an <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
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 <a
class='noxref'
href='events.html#Events-EventTarget'><code>EventTarget</code></a>,
not just FORM controls.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: No</li>
<li>Context Info: None</li>
</ul>
</dd>
<dt><b>DOMFocusOut</b></dt>
<dd>The DOMFocusOut event occurs when a <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
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 <a
class='noxref'
href='events.html#Events-EventTarget'><code>EventTarget</code></a>,
not just FORM controls.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: No</li>
<li>Context Info: None</li>
</ul>
</dd>
<dt><b>DOMActivate</b></dt>
<dd>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).
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: Yes</li>
<li>Context Info: detail (the numerical value)</li>
</ul>
</dd>
</dl>
</div>
<!-- div3 Events-eventgroupings-uievents -->
<div class='div3'><a id="Events-eventgroupings-mouseevents"
name='Events-eventgroupings-mouseevents'></a>
<h3 id='Events-eventgroupings-mouseevents-h3' class='div3'>1.6.2.
Mouse event types</h3>
<p>The Mouse event module is composed of events listed in HTML 4.0
and additional events which are supported in <a
href='glossary.html#dt-DOM-Level-0'><em>DOM Level 0</em></a>
browsers. This event module is specifically designed for use with
mouse input devices.</p>
<p>A DOM application may use the <code>hasFeature(feature,
version)</code> method of the <code>DOMImplementation</code>
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 <a
href='http://www.w3.org/TR/DOM-Level-2-Core/introduction.html#ID-Conformance'>
<em>conformance</em></a> in the DOM Level 2 Core specification [<a
class='noxref' href='references.html#DOMCore'>DOM Level 2
Core</a>].</p>
<p><b>Note:</b> To create an instance of the <a
href='events.html#Events-MouseEvent'><code>MouseEvent</code></a>
interface, use the feature string "MouseEvents" as the value of the
input parameter used with the <code>createEvent</code> method of
the <a
href='events.html#Events-DocumentEvent'><code>DocumentEvent</code></a>
interface.</p>
<dl>
<dt><b>Interface <i><a id="Events-MouseEvent"
name='Events-MouseEvent'>MouseEvent</a></i></b> (introduced in <b
class='since'>DOM Level 2</b>)</dt>
<dd>
<p>The <code>MouseEvent</code> interface provides specific
contextual information associated with Mouse events.</p>
<p>The <code>detail</code> attribute inherited from <a
href='events.html#Events-UIEvent'><code>UIEvent</code></a>
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.</p>
<p>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.</p>
<dl>
<dt><br />
<b>IDL Definition</b></dt>
<dd>
<div class='idl-code'>
<pre>
// Introduced in DOM Level 2:
interface MouseEvent : UIEvent {
readonly attribute long screenX;
readonly attribute long screenY;
readonly attribute long clientX;
readonly attribute long clientY;
readonly attribute boolean ctrlKey;
readonly attribute boolean shiftKey;
readonly attribute boolean altKey;
readonly attribute boolean metaKey;
readonly attribute unsigned short button;
readonly attribute EventTarget relatedTarget;
void initMouseEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in views::AbstractView viewArg,
in long detailArg,
in long screenXArg,
in long screenYArg,
in long clientXArg,
in long clientYArg,
in boolean ctrlKeyArg,
in boolean altKeyArg,
in boolean shiftKeyArg,
in boolean metaKeyArg,
in unsigned short buttonArg,
in EventTarget relatedTargetArg);
};
</pre>
</div>
<br />
</dd>
<dt><b>Attributes</b></dt>
<dd>
<dl>
<dt><code class='attribute-name'><a id="Events-MouseEvent-altKey"
name='Events-MouseEvent-altKey'>altKey</a></code> of type
<code>boolean</code>, readonly</dt>
<dd>Used to indicate whether the 'alt' key was depressed during the
firing of the event. On some platforms this key may map to an
alternative key name.<br />
</dd>
<dt><code class='attribute-name'><a id="Events-MouseEvent-button"
name='Events-MouseEvent-button'>button</a></code> of type
<code>unsigned short</code>, readonly</dt>
<dd>During mouse events caused by the depression or release of a
mouse button, <code>button</code> is used to indicate which mouse
button changed state. The values for <code>button</code> 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.<br />
</dd>
<dt><code class='attribute-name'><a id="Events-MouseEvent-clientX"
name='Events-MouseEvent-clientX'>clientX</a></code> of type
<code>long</code>, readonly</dt>
<dd>The horizontal coordinate at which the event occurred relative
to the DOM implementation's client area.<br />
</dd>
<dt><code class='attribute-name'><a id="Events-MouseEvent-clientY"
name='Events-MouseEvent-clientY'>clientY</a></code> of type
<code>long</code>, readonly</dt>
<dd>The vertical coordinate at which the event occurred relative to
the DOM implementation's client area.<br />
</dd>
<dt><code class='attribute-name'><a id="Events-MouseEvent-ctrlKey"
name='Events-MouseEvent-ctrlKey'>ctrlKey</a></code> of type
<code>boolean</code>, readonly</dt>
<dd>Used to indicate whether the 'ctrl' key was depressed during
the firing of the event.<br />
</dd>
<dt><code class='attribute-name'><a id="Events-MouseEvent-metaKey"
name='Events-MouseEvent-metaKey'>metaKey</a></code> of type
<code>boolean</code>, readonly</dt>
<dd>Used to indicate whether the 'meta' key was depressed during
the firing of the event. On some platforms this key may map to an
alternative key name.<br />
</dd>
<dt><code class='attribute-name'><a
id="Events-MouseEvent-relatedTarget"
name='Events-MouseEvent-relatedTarget'>relatedTarget</a></code> of
type <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>,
readonly</dt>
<dd>Used to identify a secondary <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
related to a UI event. Currently this attribute is used with the
mouseover event to indicate the <a class='noxref'
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
which the pointing device exited and with the mouseout event to
indicate the <a class='noxref'
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
which the pointing device entered.<br />
</dd>
<dt><code class='attribute-name'><a id="Events-MouseEvent-screenX"
name='Events-MouseEvent-screenX'>screenX</a></code> of type
<code>long</code>, readonly</dt>
<dd>The horizontal coordinate at which the event occurred relative
to the origin of the screen coordinate system.<br />
</dd>
<dt><code class='attribute-name'><a id="Events-MouseEvent-screenY"
name='Events-MouseEvent-screenY'>screenY</a></code> of type
<code>long</code>, readonly</dt>
<dd>The vertical coordinate at which the event occurred relative to
the origin of the screen coordinate system.<br />
</dd>
<dt><code class='attribute-name'><a id="Events-MouseEvent-shiftKey"
name='Events-MouseEvent-shiftKey'>shiftKey</a></code> of type
<code>boolean</code>, readonly</dt>
<dd>Used to indicate whether the 'shift' key was depressed during
the firing of the event.<br />
</dd>
</dl>
</dd>
<dt><b>Methods</b></dt>
<dd>
<dl>
<dt><code class='method-name'><a id="Events-Event-initMouseEvent"
name='Events-Event-initMouseEvent'>initMouseEvent</a></code></dt>
<dd>
<div class='method'>The <code>initMouseEvent</code> method is used
to initialize the value of a <code>MouseEvent</code> created
through the <a
href='events.html#Events-DocumentEvent'><code>DocumentEvent</code></a>
interface. This method may only be called before the
<code>MouseEvent</code> has been dispatched via the
<code>dispatchEvent</code> method, though it may be called multiple
times during that phase if necessary. If called multiple times, the
final invocation takes precedence.
<div class='parameters'><b>Parameters</b>
<div class='paramtable'>
<dl>
<dt><code class='parameter-name'>typeArg</code> of type
<code>DOMString</code></dt>
<dd>Specifies the event type.<br />
</dd>
<dt><code class='parameter-name'>canBubbleArg</code> of type
<code>boolean</code></dt>
<dd>Specifies whether or not the event can bubble.<br />
</dd>
<dt><code class='parameter-name'>cancelableArg</code> of type
<code>boolean</code></dt>
<dd>Specifies whether or not the event's default action can be
prevented.<br />
</dd>
<dt><code class='parameter-name'>viewArg</code> of type
<code>views::AbstractView</code></dt>
<dd>Specifies the <a
href='events.html#Events-Event'><code>Event</code></a>'s
<code>AbstractView</code>.<br />
</dd>
<dt><code class='parameter-name'>detailArg</code> of type
<code>long</code></dt>
<dd>Specifies the <a
href='events.html#Events-Event'><code>Event</code></a>'s mouse
click count.<br />
</dd>
<dt><code class='parameter-name'>screenXArg</code> of type
<code>long</code></dt>
<dd>Specifies the <a
href='events.html#Events-Event'><code>Event</code></a>'s screen x
coordinate<br />
</dd>
<dt><code class='parameter-name'>screenYArg</code> of type
<code>long</code></dt>
<dd>Specifies the <a
href='events.html#Events-Event'><code>Event</code></a>'s screen y
coordinate<br />
</dd>
<dt><code class='parameter-name'>clientXArg</code> of type
<code>long</code></dt>
<dd>Specifies the <a
href='events.html#Events-Event'><code>Event</code></a>'s client x
coordinate<br />
</dd>
<dt><code class='parameter-name'>clientYArg</code> of type
<code>long</code></dt>
<dd>Specifies the <a
href='events.html#Events-Event'><code>Event</code></a>'s client y
coordinate<br />
</dd>
<dt><code class='parameter-name'>ctrlKeyArg</code> of type
<code>boolean</code></dt>
<dd>Specifies whether or not control key was depressed during the
<a href='events.html#Events-Event'><code>Event</code></a>.<br />
</dd>
<dt><code class='parameter-name'>altKeyArg</code> of type
<code>boolean</code></dt>
<dd>Specifies whether or not alt key was depressed during the <a
href='events.html#Events-Event'><code>Event</code></a>.<br />
</dd>
<dt><code class='parameter-name'>shiftKeyArg</code> of type
<code>boolean</code></dt>
<dd>Specifies whether or not shift key was depressed during the <a
href='events.html#Events-Event'><code>Event</code></a>.<br />
</dd>
<dt><code class='parameter-name'>metaKeyArg</code> of type
<code>boolean</code></dt>
<dd>Specifies whether or not meta key was depressed during the <a
href='events.html#Events-Event'><code>Event</code></a>.<br />
</dd>
<dt><code class='parameter-name'>buttonArg</code> of type
<code>unsigned short</code></dt>
<dd>Specifies the <a
href='events.html#Events-Event'><code>Event</code></a>'s mouse
button.<br />
</dd>
<dt><code class='parameter-name'>relatedTargetArg</code> of type <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a></dt>
<dd>Specifies the <a
href='events.html#Events-Event'><code>Event</code></a>'s related <a
class='noxref'
href='events.html#Events-EventTarget'><code>EventTarget</code></a>.<br />
</dd>
</dl>
</div>
</div>
<!-- parameters -->
<div><b>No Return Value</b></div>
<div><b>No Exceptions</b></div>
</div>
<!-- method -->
</dd>
</dl>
</dd>
</dl>
</dd>
</dl>
<p>The different types of Mouse events that can occur are:</p>
<dl>
<dt><b>click</b></dt>
<dd>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:
<div class='eg'>
<pre>
mousedown
mouseup
click
</pre>
</div>
If multiple clicks occur at the same screen location, the sequence
repeats with the <code>detail</code> attribute incrementing with
each repetition. This event is valid for most elements.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: Yes</li>
<li>Context Info: screenX, screenY, clientX, clientY, altKey,
ctrlKey, shiftKey, metaKey, button, detail</li>
</ul>
</dd>
<dt><b>mousedown</b></dt>
<dd>The mousedown event occurs when the pointing device button is
pressed over an element. This event is valid for most elements.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: Yes</li>
<li>Context Info: screenX, screenY, clientX, clientY, altKey,
ctrlKey, shiftKey, metaKey, button, detail</li>
</ul>
</dd>
<dt><b>mouseup</b></dt>
<dd>The mouseup event occurs when the pointing device button is
released over an element. This event is valid for most elements.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: Yes</li>
<li>Context Info: screenX, screenY, clientX, clientY, altKey,
ctrlKey, shiftKey, metaKey, button, detail</li>
</ul>
</dd>
<dt><b>mouseover</b></dt>
<dd>The mouseover event occurs when the pointing device is moved
onto an element. This event is valid for most elements.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: Yes</li>
<li>Context Info: screenX, screenY, clientX, clientY, altKey,
ctrlKey, shiftKey, metaKey, relatedTarget indicates the <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
the pointing device is exiting.</li>
</ul>
</dd>
<dt><b>mousemove</b></dt>
<dd>The mousemove event occurs when the pointing device is moved
while it is over an element. This event is valid for most elements.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: No</li>
<li>Context Info: screenX, screenY, clientX, clientY, altKey,
ctrlKey, shiftKey, metaKey</li>
</ul>
</dd>
<dt><b>mouseout</b></dt>
<dd>The mouseout event occurs when the pointing device is moved
away from an element. This event is valid for most elements..
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: Yes</li>
<li>Context Info: screenX, screenY, clientX, clientY, altKey,
ctrlKey, shiftKey, metaKey, relatedTarget indicates the <a
href='events.html#Events-EventTarget'><code>EventTarget</code></a>
the pointing device is entering.</li>
</ul>
</dd>
</dl>
</div>
<!-- div3 Events-eventgroupings-mouseevents -->
<div class='div3'><a id="Events-eventgroupings-keyevents"
name='Events-eventgroupings-keyevents'></a>
<h3 id='Events-eventgroupings-keyevents-h3' class='div3'>1.6.3. Key
events</h3>
<p>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.</p>
</div>
<!-- div3 Events-eventgroupings-keyevents -->
<div class='div3'><a id="Events-eventgroupings-mutationevents"
name='Events-eventgroupings-mutationevents'></a>
<h3 id='Events-eventgroupings-mutationevents-h3' class='div3'>
1.6.4. Mutation event types</h3>
<p>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.</p>
<p>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.</p>
<p>A DOM application may use the <code>hasFeature(feature,
version)</code> method of the <code>DOMImplementation</code>
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 <a
href='http://www.w3.org/TR/DOM-Level-2-Core/introduction.html#ID-Conformance'>
<em>conformance</em></a> in the DOM Level 2 Core specification [<a
class='noxref' href='references.html#DOMCore'>DOM Level 2
Core</a>].</p>
<p><b>Note:</b> To create an instance of the <a
href='events.html#Events-MutationEvent'><code>MutationEvent</code></a>
interface, use the feature string "MutationEvents" as the value of
the input parameter used with the <code>createEvent</code> method
of the <a
href='events.html#Events-DocumentEvent'><code>DocumentEvent</code></a>
interface.</p>
<dl>
<dt><b>Interface <i><a id="Events-MutationEvent"
name='Events-MutationEvent'>MutationEvent</a></i></b> (introduced
in <b class='since'>DOM Level 2</b>)</dt>
<dd>
<p>The <code>MutationEvent</code> interface provides specific
contextual information associated with Mutation events.</p>
<dl>
<dt><br />
<b>IDL Definition</b></dt>
<dd>
<div class='idl-code'>
<pre>
// Introduced in DOM Level 2:
interface MutationEvent : Event {
// attrChangeType
const unsigned short MODIFICATION = 1;
const unsigned short ADDITION = 2;
const unsigned short REMOVAL = 3;
readonly attribute Node relatedNode;
readonly attribute DOMString prevValue;
readonly attribute DOMString newValue;
readonly attribute DOMString attrName;
readonly attribute unsigned short attrChange;
void initMutationEvent(in DOMString typeArg,
in boolean canBubbleArg,
in boolean cancelableArg,
in Node relatedNodeArg,
in DOMString prevValueArg,
in DOMString newValueArg,
in DOMString attrNameArg,
in unsigned short attrChangeArg);
};
</pre>
</div>
<br />
</dd>
<dt><b>Definition group <i><a
id="Events-MutationEvent-attrChangeType"
name='Events-MutationEvent-attrChangeType'>attrChangeType</a></i></b></dt>
<dd>
<p>An integer indicating in which way the <code>Attr</code> was
changed.</p>
<dl>
<dt><b>Defined Constants</b></dt>
<dd>
<dl>
<dt><code class='constant-name'>ADDITION</code></dt>
<dd>The <code>Attr</code> was just added.</dd>
<dt><code class='constant-name'>MODIFICATION</code></dt>
<dd>The <code>Attr</code> was modified in place.</dd>
<dt><code class='constant-name'>REMOVAL</code></dt>
<dd>The <code>Attr</code> was just removed.</dd>
</dl>
</dd>
</dl>
</dd>
<dt><b>Attributes</b></dt>
<dd>
<dl>
<dt><code class='attribute-name'><a
id="Events-MutationEvent-attrChange"
name='Events-MutationEvent-attrChange'>attrChange</a></code> of
type <code>unsigned short</code>, readonly</dt>
<dd><code>attrChange</code> indicates the type of change which
triggered the DOMAttrModified event. The values can be
<code>MODIFICATION</code>, <code>ADDITION</code>, or
<code>REMOVAL</code>.<br />
</dd>
<dt><code class='attribute-name'><a
id="Events-MutationEvent-attrName"
name='Events-MutationEvent-attrName'>attrName</a></code> of type
<code>DOMString</code>, readonly</dt>
<dd><code>attrName</code> indicates the name of the changed
<code>Attr</code> node in a DOMAttrModified event.<br />
</dd>
<dt><code class='attribute-name'><a
id="Events-MutationEvent-newValue"
name='Events-MutationEvent-newValue'>newValue</a></code> of type
<code>DOMString</code>, readonly</dt>
<dd><code>newValue</code> indicates the new value of the
<code>Attr</code> node in DOMAttrModified events, and of the
<code>CharacterData</code> node in DOMCharDataModified
events.<br />
</dd>
<dt><code class='attribute-name'><a
id="Events-MutationEvent-prevValue"
name='Events-MutationEvent-prevValue'>prevValue</a></code> of type
<code>DOMString</code>, readonly</dt>
<dd><code>prevValue</code> indicates the previous value of the
<code>Attr</code> node in DOMAttrModified events, and of the
<code>CharacterData</code> node in DOMCharDataModified
events.<br />
</dd>
<dt><code class='attribute-name'><a
id="Events-MutationEvent-relatedNode"
name='Events-MutationEvent-relatedNode'>relatedNode</a></code> of
type <code>Node</code>, readonly</dt>
<dd><code>relatedNode</code> 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
<code>relatedNode</code> is the changed parent. If an event is
instead dispatched to a subtree indicating a node was changed
within it, the <code>relatedNode</code> is the changed node. In the
case of the DOMAttrModified event it indicates the
<code>Attr</code> node which was modified, added, or removed.<br />
</dd>
</dl>
</dd>
<dt><b>Methods</b></dt>
<dd>
<dl>
<dt><code class='method-name'><a
id="Events-Event-initMutationEvent"
name='Events-Event-initMutationEvent'>initMutationEvent</a></code></dt>
<dd>
<div class='method'>The <code>initMutationEvent</code> method is
used to initialize the value of a <code>MutationEvent</code>
created through the <a
href='events.html#Events-DocumentEvent'><code>DocumentEvent</code></a>
interface. This method may only be called before the
<code>MutationEvent</code> has been dispatched via the
<code>dispatchEvent</code> method, though it may be called multiple
times during that phase if necessary. If called multiple times, the
final invocation takes precedence.
<div class='parameters'><b>Parameters</b>
<div class='paramtable'>
<dl>
<dt><code class='parameter-name'>typeArg</code> of type
<code>DOMString</code></dt>
<dd>Specifies the event type.<br />
</dd>
<dt><code class='parameter-name'>canBubbleArg</code> of type
<code>boolean</code></dt>
<dd>Specifies whether or not the event can bubble.<br />
</dd>
<dt><code class='parameter-name'>cancelableArg</code> of type
<code>boolean</code></dt>
<dd>Specifies whether or not the event's default action can be
prevented.<br />
</dd>
<dt><code class='parameter-name'>relatedNodeArg</code> of type
<code>Node</code></dt>
<dd>Specifies the <a
href='events.html#Events-Event'><code>Event</code></a>'s related
Node.<br />
</dd>
<dt><code class='parameter-name'>prevValueArg</code> of type
<code>DOMString</code></dt>
<dd>Specifies the <a
href='events.html#Events-Event'><code>Event</code></a>'s
<code>prevValue</code> attribute. This value may be null.<br />
</dd>
<dt><code class='parameter-name'>newValueArg</code> of type
<code>DOMString</code></dt>
<dd>Specifies the <a
href='events.html#Events-Event'><code>Event</code></a>'s
<code>newValue</code> attribute. This value may be null.<br />
</dd>
<dt><code class='parameter-name'>attrNameArg</code> of type
<code>DOMString</code></dt>
<dd>Specifies the <a
href='events.html#Events-Event'><code>Event</code></a>'s
<code>attrName</code> attribute. This value may be null.<br />
</dd>
<dt><code class='parameter-name'>attrChangeArg</code> of type
<code>unsigned short</code></dt>
<dd>Specifies the <a
href='events.html#Events-Event'><code>Event</code></a>'s
<code>attrChange</code> attribute<br />
</dd>
</dl>
</div>
</div>
<!-- parameters -->
<div><b>No Return Value</b></div>
<div><b>No Exceptions</b></div>
</div>
<!-- method -->
</dd>
</dl>
</dd>
</dl>
</dd>
</dl>
<p>The different types of Mutation events that can occur are:</p>
<dl>
<dt><b>DOMSubtreeModified</b></dt>
<dd>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.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: No</li>
<li>Context Info: None</li>
</ul>
</dd>
<dt><b>DOMNodeInserted</b></dt>
<dd>Fired when a node has been added as a <a
href='glossary.html#dt-child'><em>child</em></a> of another node.
This event is dispatched after the insertion has taken place. The
target of this event is the node being inserted.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: No</li>
<li>Context Info: relatedNode holds the parent node</li>
</ul>
</dd>
<dt><b>DOMNodeRemoved</b></dt>
<dd>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.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: No</li>
<li>Context Info: relatedNode holds the parent node</li>
</ul>
</dd>
<dt><b>DOMNodeRemovedFromDocument</b></dt>
<dd>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.
<ul>
<li>Bubbles: No</li>
<li>Cancelable: No</li>
<li>Context Info: None</li>
</ul>
</dd>
<dt><b>DOMNodeInsertedIntoDocument</b></dt>
<dd>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.
<ul>
<li>Bubbles: No</li>
<li>Cancelable: No</li>
<li>Context Info: None</li>
</ul>
</dd>
<dt><b>DOMAttrModified</b></dt>
<dd>Fired after an <code>Attr</code> has been modified on a node.
The target of this event is the <code>Node</code> whose
<code>Attr</code> changed. The value of attrChange indicates
whether the <code>Attr</code> was modified, added, or removed. The
value of relatedNode indicates the <code>Attr</code> node whose
value has been affected. It is expected that string based
replacement of an <code>Attr</code> value will be viewed as a
modification of the <code>Attr</code> since its identity does not
change. Subsequently replacement of the <code>Attr</code> node with
a different <code>Attr</code> node is viewed as the removal of the
first <code>Attr</code> node and the addition of the second.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: No</li>
<li>Context Info: attrName, attrChange, prevValue, newValue,
relatedNode</li>
</ul>
</dd>
<dt><b>DOMCharacterDataModified</b></dt>
<dd>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.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: No</li>
<li>Context Info: prevValue, newValue</li>
</ul>
</dd>
</dl>
</div>
<!-- div3 Events-eventgroupings-mutationevents -->
<div class='div3'><a id="Events-eventgroupings-htmlevents"
name='Events-eventgroupings-htmlevents'></a>
<h3 id='Events-eventgroupings-htmlevents-h3' class='div3'>1.6.5.
HTML event types</h3>
<p>The HTML event module is composed of events listed in HTML 4.0
and additional events which are supported in <a
href='glossary.html#dt-DOM-Level-0'><em>DOM Level 0</em></a>
browsers.</p>
<p>A DOM application may use the <code>hasFeature(feature,
version)</code> method of the <code>DOMImplementation</code>
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 <a
href='http://www.w3.org/TR/DOM-Level-2-Core/introduction.html#ID-Conformance'>
<em>conformance</em></a> in the DOM Level 2 Core specification [<a
class='noxref' href='references.html#DOMCore'>DOM Level 2
Core</a>].</p>
<p><b>Note:</b> To create an instance of the <a
href='events.html#Events-Event'><code>Event</code></a> interface
for the HTML event module, use the feature string "HTMLEvents" as
the value of the input parameter used with the
<code>createEvent</code> method of the <a
href='events.html#Events-DocumentEvent'><code>DocumentEvent</code></a>
interface.</p>
<p>The HTML events use the base DOM Event interface to pass
contextual information.</p>
<p>The different types of such events that can occur are:</p>
<dl>
<dt><b>load</b></dt>
<dd>The load event occurs when the DOM implementation finishes
loading all content within a document, all frames within a
FRAMESET, or an OBJECT element.
<ul>
<li>Bubbles: No</li>
<li>Cancelable: No</li>
<li>Context Info: None</li>
</ul>
</dd>
<dt><b>unload</b></dt>
<dd>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.
<ul>
<li>Bubbles: No</li>
<li>Cancelable: No</li>
<li>Context Info: None</li>
</ul>
</dd>
<dt><b>abort</b></dt>
<dd>The abort event occurs when page loading is stopped before an
image has been allowed to completely load. This event applies to
OBJECT elements.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: No</li>
<li>Context Info: None</li>
</ul>
</dd>
<dt><b>error</b></dt>
<dd>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.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: No</li>
<li>Context Info: None</li>
</ul>
</dd>
<dt><b>select</b></dt>
<dd>The select event occurs when a user selects some text in a text
field. This event is valid for INPUT and TEXTAREA elements.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: No</li>
<li>Context Info: None</li>
</ul>
</dd>
<dt><b>change</b></dt>
<dd>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.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: No</li>
<li>Context Info: None</li>
</ul>
</dd>
<dt><b>submit</b></dt>
<dd>The submit event occurs when a form is submitted. This event
only applies to the FORM element.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: Yes</li>
<li>Context Info: None</li>
</ul>
</dd>
<dt><b>reset</b></dt>
<dd>The reset event occurs when a form is reset. This event only
applies to the FORM element.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: No</li>
<li>Context Info: None</li>
</ul>
</dd>
<dt><b>focus</b></dt>
<dd>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.
<ul>
<li>Bubbles: No</li>
<li>Cancelable: No</li>
<li>Context Info: None</li>
</ul>
</dd>
<dt><b>blur</b></dt>
<dd>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.
<ul>
<li>Bubbles: No</li>
<li>Cancelable: No</li>
<li>Context Info: None</li>
</ul>
</dd>
<dt><b>resize</b></dt>
<dd>The resize event occurs when a document view is resized.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: No</li>
<li>Context Info: None</li>
</ul>
</dd>
<dt><b>scroll</b></dt>
<dd>The scroll event occurs when a document view is scrolled.
<ul>
<li>Bubbles: Yes</li>
<li>Cancelable: No</li>
<li>Context Info: None</li>
</ul>
</dd>
</dl>
</div>
<!-- div3 Events-eventgroupings-htmlevents --></div>
<!-- div2 Events-eventgroupings --></div>
<!-- div1 Events -->
<div class='navbar' align='center'>
<hr title='Navigation area separator' />
<a accesskey='p' href='copyright-notice.html'>previous</a>
<a accesskey='n' href='idl-definitions.html'>next</a> <a
accesskey='c' href='Overview.html#contents'>contents</a> <a
accesskey='i' href='def-index.html'>index</a></div>
</body>
</html>
distrib
>
Mandriva
>
2008.1
>
x86_64
>
media
>
main-release
>
by-pkgid
>
c9ab6176cdb3bd12c388e27bee18050a
>
files
>
46
