82b88df622
http://www.w3.org/DOM/DOMTM git-svn-id: https://svn.apache.org/repos/asf/xml/commons/trunk@225913 13f79535-47bb-0310-9956-ffa450edef68
2716 lines
83 KiB
HTML
2716 lines
83 KiB
HTML
<!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>
|
|
|