--- a/html/DOM3-Events.html Tue May 27 16:38:35 2014 -0700
+++ b/html/DOM3-Events.html Tue May 27 17:04:25 2014 -0700
@@ -385,6 +385,11 @@
event target</a> in the document while the event object is being dispatched. Such changes do not affect the propagation path.</p>
</div>
+ <p>Note that event listeners are not copied over when <code>Node</code> are copied using methods such as
+ <code>Node.cloneNode</code> or <code>Range.cloneContents</code>
+ [<cite><a class="informative" href="#references-DOMRange">DOM Range</a></cite>].
+ </p>
+
<p>Exceptions thrown inside event listeners MUST NOT stop the propagation of the event or affect the
<a class="def" href="#glossary-propagation-path">propagation path</a>. The exception itself MUST NOT propagate outside the scope of the event
handler.</p>
@@ -467,6 +472,7 @@
<p>Implementations of the DOM event model MUST be reentrant. Event listeners MAY perform actions that cause additional events to be dispatched. Such events are handled
in a synchronous manner, the event propagation that causes the event listener to be triggered MUST resume only after the event dispatch of the new event is completed.</p>
+
</section> <!-- event-flow -->
<section id="event-flow-default-cancel">
@@ -823,604 +829,6 @@
<figcaption>Graphical representation of the DOM3 Events interface inheritance</figcaption>
</figure>
- <section id="interface-Event">
- <h2>Interface Event</h2>
-
- <p class="intro-dom">Introduced in DOM Level 2</p>
-
- <p>The <code>Event</code> interface provides basic contextual information about an event to
- all registered <a class="def" href="#glossary-event-handler">event handlers</a>.
- Specific events can also implement other derived interfaces, for example the
- <a href="#interface-UIEvent"><code>UIEvent</code></a>
- and
- <a href="#interface-MouseEvent"><code>MouseEvent</code></a>
- interfaces.
- </p>
-
- <p>To create an instance of the <code>Event</code> interface, use the
- <a href="#widl-DocumentEvent-createEvent"><code>DocumentEvent.createEvent("Event")</code></a>
- method call.
- </p>
-
- <dl class="idl" title="dictionary EventInit">
- <dt>boolean bubbles = false</dt><dd></dd>
- <dt>boolean cancelable = false</dt><dd></dd>
- </dl>
-
- <dl class="idl" title="[Constructor(DOMString typeArg, optional EventInit eventInitDict), Exposed=Window,Worker] interface Event">
- <dt>// PhaseType</dt>
-
- <dt>const unsigned short NONE = 0</dt>
- <dd>
- <p>The current event is not being dispatched, i.e., the <a href="#widl-Event-eventPhase"><code>Event.eventPhase</code></a> is being observed prior to
- calling <a href="#widl-EventTarget-dispatchEvent">EventTarget.dispatchEvent()</a> or following the completion of the
- <a class="def" href="#glossary-phase">event phases</a> of a given <code>Event</code>.</p>
- </dd>
-
- <dt>const unsigned short CAPTURING_PHASE = 1</dt>
- <dd>
- <p>The current event phase is the <a class="def" href="#glossary-capture-phase">capture phase</a>.</p>
- </dd>
-
- <dt>const unsigned short AT_TARGET = 2</dt>
- <dd>
- <p>The current event is in the <a class="def" href="#glossary-target-phase">target phase</a>, i.e., it is being evaluated at the <a class="def"
- href="#glossary-event-target">event target</a>.</p>
- </dd>
-
- <dt>const unsigned short BUBBLING_PHASE = 3</dt>
- <dd>
- <p>The current event phase is the <a class="def" href="#glossary-bubbling-phase">bubbling phase</a>.</p>
- </dd>
-
- <dt>readonly attribute DOMString type</dt>
- <dd>
- <p>The name of the event type. <a href="#conf-specs">Specifications that define events</a>, <a href="#conf-authors">content authors</a>, and <a href="#conf-author-tools">
- authoring tools</a> MUST use case-sensitive event type names.</p>
-
- <p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a> of this attribute MUST be <code>""</code> (the empty string).</p>
- </dd>
-
- <dt>readonly attribute EventTarget? target</dt>
- <dd>
- <p>Used to retrieve the <a class="def" href="#glossary-event-target">event target</a> associated with the <a href="#event-flow">Event dispatch and DOM
- event flow</a>.</p>
-
- <p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a> of this attribute MUST be <code>null</code>.</p>
- </dd>
-
- <dt>readonly attribute EventTarget? currentTarget</dt>
- <dd>
- <p>Used to retrieve the <a class="def" href="#glossary-current-event-target">current event target</a> whose <a href="#interface-EventListener"><code>EventListeners</code></a>
- are currently being processed. This is particularly useful during the capture and bubbling phases.</p>
-
- <p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a> of this attribute MUST be <code>null</code>.</p>
- </dd>
-
- <dt>readonly attribute unsigned short eventPhase</dt>
- <dd>
- <p>Used to indicate the <a href="#event-phase">phase</a> of the event's current propagation path (capture, target, or bubble).
- The event flow phases are defined in <a href="#event-flow">Event dispatch and DOM event flow</a>.</p>
-
- <p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a> of this attribute MUST be <code>0</code> (<code>NONE</code>).</p>
- </dd>
-
- <dt>readonly attribute boolean bubbles</dt>
- <dd>
- <p>Used to indicate whether or not an event is a bubbling event. If the event can bubble the value MUST be <code>true</code>, otherwise the value MUST be
- <code>false</code>.</p>
-
- <p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a> of this attribute MUST be <code>false</code>.</p>
- </dd>
-
- <dt>readonly attribute boolean cancelable</dt>
- <dd>
- <p>Used to indicate whether or not an event can have its
- <a class="def" href="#glossary-default-action">default action</a>
- prevented.
- If the
- <a class="def" href="#glossary-default-action">default action</a>
- can be prevented the value MUST be <code>true</code>, otherwise the value
- MUST be <code>false</code>.
- See <a href="#event-flow-default-cancel">Default actions and cancelable events</a>
- for more information on cancelable events.
- </p>
-
- <p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a>
- of this attribute MUST be <code>false</code>.
- </p>
-
- <p class="note"><strong>Note:</strong>
- Use <code>Event.defaultPrevented</code> to see whether a cancelable event has
- been cancelled or not.
- </p>
- </dd>
-
- <dt>readonly attribute DOMTimeStamp timeStamp</dt>
- <dd>
- <p>Used to specify the time at which the event was created in milliseconds relative to 1970-01-01T00:00:00Z. This value is the <a class="def" href="#glossary-un-initialized-value">
- un-initialized value</a> of this attribute.</p>
- </dd>
-
- <dt>void stopPropagation()</dt>
- <dd>
- <p>Prevents all other
- <a class="def" href="#glossary-event-handler">event listeners</a>
- from being triggered for this event dispatch, <strong>excluding</strong> any remaining
- <a class="def" href="#glossary-candidate-event-handlers">candidate event listeners</a>.
- Once it has been called, further calls to this method have no additional effect.
- </p>
-
- <p class="note" id="note-stopPropagation-default"><strong>Note:</strong>
- This method does not prevent the
- <a class="def" href="#glossary-default-action">default action</a>
- from being invoked — use
- <a href="#widl-Event-preventDefault"><code>Event.preventDefault()</code></a>
- for that effect.
- </p>
- </dd>
-
- <dt>void preventDefault()</dt>
- <dd>
- <p>When this method is invoked, the event MUST be canceled, meaning any
- <a class="def" href="#glossary-default-action">default actions</a>
- normally taken by the implementation as a result of the event MUST NOT occur.
- Default actions which occur prior to the event's dispatch are reverted.
- Calling this method for a non-cancelable event MUST have no effect.
- If an event has more than one
- <a class="def" href="#glossary-default-action">default action</a>,
- each cancelable
- <a class="def" href="#glossary-default-action">default action</a>
- MUST be canceled.
- See <a href="#event-flow-default-cancel">Default actions and cancelable events</a>
- for more information on cancelable events.
- </p>
-
- <p class="note"><strong>Note:</strong>
- This method does not stop the event propagation — use
- <a href="#widl-Event-stopPropagation"><code>Event.stopPropagation()</code></a>
- or
- <a href="#widl-Event-stopImmediatePropagation"><code>Event.stopImmediatePropagation()</code></a>
- for that effect.
- </p>
- </dd>
-
- <dt>void initEvent()</dt>
- <dd>
- <p>Initializes attributes of an <code>Event</code>.
- The <code>Event</code> could have been created through the
- <a href="#widl-DocumentEvent-createEvent"><code>DocumentEvent.createEvent</code></a>
- method or by the implementation in response to a user action.
- For any <code>Event</code> created with the
- <a href="#widl-DocumentEvent-createEvent"><code>DocumentEvent.createEvent</code></a>
- method, this method MUST be called before the <code>Event</code> is dispatched via the
- <a href="#widl-EventTarget-dispatchEvent"><code>EventTarget.dispatchEvent()</code></a>
- method.
- If the method is called several times before invoking
- <a href="#widl-EventTarget-dispatchEvent"><code>EventTarget.dispatchEvent</code></a>,
- only the final invocation takes precedence.
- If this method is called during an invocation of
- <a href="#widl-EventTarget-dispatchEvent"><code>EventTarget.dispatchEvent</code></a>,
- this method MUST do nothing and return immediately.
- If called from a subclass of the <code>Event</code> interface only the values specified in
- this method are modified, all other attributes are left unchanged.
- </p>
-
- <p>This method MUST also reset the event object's internal-propagation and default-action-prevention states.
- This allows an event object to be "reset" before being dispatched multiple times.
- </p>
-
- <div class="example">
- <div class="example-title"></div>
- <p>If an <code>EventListener</code> called <code>stopPropagation()</code> or
- <code>stopImmediatePropagation()</code> during the event's previous dispatch, then after
- calling this method, the event can be re-dispatched (via <code>dispatchEvent</code>) and
- will propagate through all candidate event listeners along its propagation path (as it did
- during the prior dispatch).
- Similarly, if an <code>EventListener</code> called <code>preventDefault()</code>
- during the event's previous dispatch, then after calling this method, the event's
- <code>defaultPrevented</code> property will be <code>false</code>.
- </p>
- </div>
-
- <p class="warning" id="warning-initEvent-untrusted"><strong>Warning!</strong>
- For security reasons, events modified using
- <a href="#widl-Event-initEvent"><code>Event.initEvent()</code></a>
- MUST have an
- <code class="attribute-name"><a href="#widl-Event-isTrusted">isTrusted</a></code>
- attribute value of <code>false</code>.
- See <a href="#trusted-events">trusted events</a> for more details.
- </p>
-
- <p class="note"><strong>Authoring Note:</strong>
- <a class="def" href="#trusted-events">Trusted events</a> can have their
- <a class="def" href="#glossary-event-type">event type</a> and other attributes changed using this method.
- However, this method always converts the <code>Event</code> from a trusted event to an untrusted
- event (e.g., the <a href="#widl-Event-isTrusted"><code>Event.isTrusted</code></a> attribute will return
- <code>false</code>).
- </p>
-
- <p class="note"><strong>Authoring Note:</strong>
- <a class="def" href="#trusted-events">Trusted events</a> are pre-initialized by the implementation
- before being dispatched.
- As a result, it is not necessary to call <code>Event.initEvent()</code> prior to re-dispatching
- the trusted event — however calling
- <a href="#widl-EventTarget-dispatchEvent"><code>EventTarget.dispatchEvent()</code></a> will convert
- the <code>Event</code> from a trusted event to an untrusted event (e.g., the
- <a href="#widl-Event-isTrusted"><code>Event.isTrusted</code></a> attribute will return <code>false</code>).
- </p>
-
- <dl class="parameters">
- <dt>DOMString eventTypeArg</dt>
- <dd>
- <p>Specifies <a href="#widl-Event-type"><code>Event.type</code></a>, the name of the event type.
- </p>
- </dd>
-
- <dt>boolean bubblesArg</dt>
- <dd>
- <p>Specifies <a href="#widl-Event-bubbles"><code>Event.bubbles</code></a>.
- This parameter overrides the intrinsic bubbling behavior of the event.
- </p>
- </dd>
-
- <dt>boolean cancelableArg</dt>
- <dd>
- <p>Specifies <a href="#widl-Event-cancelable"><code>Event.cancelable</code></a>.
- This parameter overrides the intrinsic cancelable behavior of the event.
- </p>
- </dd>
- </dl>
- </dd>
-
- <dt>// Introduced in DOM Level 3</dt>
-
- <dt>void stopImmediatePropagation()</dt>
- <dd>
- <p class="intro-dom">Introduced in DOM Level 3</p>
-
- <p>Prevents all other <a class="def" href="#glossary-event-handler">event listeners</a> from being triggered for this event dispatch, <strong>including</strong> any remaining
- <a class="def" href="#glossary-candidate-event-handlers">candidate event listeners</a>. Once it has been called, further calls to this method have no additional
- effect.</p>
-
- <p class="note"><strong>Note:</strong> This method does not prevent the <a class="def" href="#glossary-default-action">default action</a> from being invoked —
- use <a href="#widl-Event-preventDefault"><code>Event.preventDefault()</code></a> for that effect.</p>
- </dd>
-
- <dt>readonly attribute boolean defaultPrevented</dt>
- <dd>
- <p class="intro-dom">Introduced in DOM Level 3</p>
-
- <p>Used to indicate whether this event has been cancelled or not. <code>Event.defaultPrevented</code> MUST return true if both <a href="#widl-Event-cancelable">
- <code>Event.cancelable</code></a> is <code>true</code> and <a href="#widl-Event-preventDefault"><code>Event.preventDefault()</code></a> has been called for
- this event. Otherwise this attribute MUST return <code>false</code>.</p>
-
- <p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a> of this attribute MUST be <code>false</code>.</p>
-
- <p class="note"><strong>Note:</strong> Calling <a href="#widl-Event-initEvent"><code>Event.initEvent()</code></a> after an event has been dispatched will reset
- the internal default-prevented state of the event.</p>
- </dd>
-
- <dt>[Unforgeable] readonly attribute boolean isTrusted</dt>
- <dd>
- <p class="intro-dom">Introduced in DOM Level 3</p>
-
- <p>Used to indicate whether this event was generated by the <a class="def" href="#glossary-user-agent">user agent</a> (trusted) or by script (untrusted). See <a
- href="#trusted-events">trusted events</a> for more details.</p>
-
- <p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a> of this attribute MUST be <code>false</code>.</p>
- </dd>
- </dl>
- </section><!-- interface-Event -->
-
- <section id="interface-CustomEvent">
- <h2>Interface CustomEvent</h2>
-
- <p class="intro-dom">Introduced in DOM Level 3</p>
-
- <p>The <a href="#interface-CustomEvent"><code>CustomEvent</code></a> interface is the RECOMMENDED
- interface for application-specific event types.
- Unlike the <a href="#interface-Event"><code>Event</code></a> interface, it allows applications
- to provide contextual information about the event type.
- </p>
-
- <p class="note"><strong>Authoring Note:</strong>
- Use a prefix string on the event type name for application-specific event types to avoid
- clashes with future general-purpose event types.
- </p>
-
- <p>To create an instance of the <code>CustomEvent</code> interface, use the
- <a href="#widl-DocumentEvent-createEvent"><code>DocumentEvent.createEvent("CustomEvent")</code></a>
- method call.
- </p>
-
- <dl class="idl" title="dictionary CustomEventInit : EventInit">
- <dt>any detail = null</dt><dd></dd>
- </dl>
-
- <dl class="idl" title="[Constructor(DOMString typeArg, optional CustomEventInit customEventInitDict), Exposed=Window,Worker] interface CustomEvent : Event">
- <dt>readonly attribute any detail</dt>
- <dd>
- <p>Specifies some detail information about the <a href="#interface-Event"><code>Event</code></a>.
- </p>
-
- <p>The <a class="def" href="#glossary-un-initialized-value">un-initialized value</a>
- of this attribute MUST be <code>null</code>.
- </p>
- </dd>
- </dl>
- </section><!-- interface-CustomEvent -->
-
- <section id="interface-EventTarget">
- <h2>Interface EventTarget</h2>
-
- <p class="intro-dom">Introduced in DOM Level 2</p>
-
- <p>The <code>EventTarget</code> interface allows registration and removal of event listeners, and dispatch of events to an event target.</p>
-
- <p class="note"><strong>Note:</strong> Though an event listener can be registered for any <a class="def" href="#glossary-event-target">event
- target</a> node, the user agent only dispatches UA-generated (trusted) events on node types that are defined as event target types for that specific event type
- (see the <a href="#event-types-list">List of DOM3 Event Types</a>). For example, a <a class="eventtype" href="#event-type-mouseover"><code>mouseover</code></a>
- event type registered on a text node will never be fired by the user agent, though a content author could dispatch an event of that type on the text node via script.</p>
-
- <p>When used with the DOM event flow, this interface MUST be implemented by all <a class="def" href="#glossary-event-target">event targets</a> and target ancestors,
- i.e., all DOM <code>Nodes</code> of the tree support this interface when the implementation conforms to DOM Level 3 Events and, therefore, this interface can be
- obtained by using binding-specific casting methods on an instance of the <code>Node</code> interface.</p>
-
- <p>Invoking <code>addEventListener</code> (or <code>removeEventListener</code>) repeatedly on the same <code>EventTarget</code> with the same values for the parameters
- <code>type</code>, <code>listener</code>, and <code>useCapture</code> has no effect. Doing so does not cause the event listener to be registered more than once and
- does not cause a change in the triggering order.</p>
-
- <p class="note"><strong>Note:</strong> In addition to the <a href="#widl-EventTarget-addEventListener"><code>EventTarget.addEventListener</code></a> method, some
- <a class="def" href="#glossary-host-language">host languages</a> allow a content author to register event listeners by the use of attributes, e.g.,
- <code>onclick="handleClick()"</code> (see [<cite><a class="informative" href="#references-HTML5">HTML5</a></cite>] for further examples). Due to the
- language-specific details, this type of event listener registration is not defined in this specification. In general, many event types can be used as an attribute
- in this way by adding the prefix <em><code>on-</code></em> to the event type name. Dispatching events to these listeners is expected to behave consistently with the
- event registration and propagation defined in this specification, with the same interfaces, properties, and methods.</p>
-
- <dl class="idl" title="[Exposed=Window,Worker] interface EventTarget">
- <dt>// Modified in DOM Level 3</dt>
-
- <dt>void addEventListener()</dt>
- <dd>
- <p><em>Modified in DOM Level 3</em></p>
-
- <p>Registers an event listener on the <a href="#interface-EventTarget"><code>EventTarget</code></a>. The listener is registered for the capture phase if the
- <code>useCapture</code> parameter is <code>true</code>, and for the bubble phase otherwise. When the event reaches the target element, listeners for both
- the capture and bubble phases are triggered as part of the target phase.
- </p>
-
- <dl class="parameters">
- <dt>DOMString type</dt>
- <dd>
- <p>Specifies the <a href="#widl-Event-type"><code>Event.type</code></a> associated with the event for which the user is registering.</p>
- </dd>
-
- <dt>EventListener? listener</dt>
- <dd>
- <p>If non-null, the <code>listener</code> parameter MUST be an object that implements the
- <a href="#interface-EventListener"><code>EventListener</code></a> interface or a function.
- If <code>listener</code> is a function then it MUST be used as the callback for the event.
- Otherwise, if <code>listener</code> implements
- <a href="#interface-EventListener"><code>EventListener</code></a>, then its
- <a href="#widl-EventListener-handleEvent"><code>handleEvent</code></a> method MUST be used as the callback.
- </p>
- <p>If null is passed for the <code>listener</code>, then <code>addEventListener</code> does nothing.
- </p>
- </dd>
-
- <dt>optional boolean useCapture = false</dt>
- <dd>
- <p>If true, <code>useCapture</code> indicates that the user wishes to add the event listener for the <a class="def" href="#glossary-capture-phase">capture</a>
- and <a class="def" href="#glossary-target-phase">target</a> phases only, i.e., this event listener will not be triggered during the <a class="def"
- href="#glossary-bubbling-phase"> bubbling</a> phase. If <code>false</code>, the event listener MUST only be triggered during the <a class="def"
- href="#glossary-target-phase">target</a> and <a class="def" href="#glossary-bubbling-phase">bubbling</a> phases.</p>
-
- <p>This parameter MUST be optional. If not provided, the <a href="#widl-EventTarget-addEventListener"><code>EventTarget.addEventListener</code></a> method MUST behave as if
- <code class="parameter-name">useCapture</code> was specified to be <code>false</code>.</p>
-
- <p class="note"><strong>Authoring Note:</strong> The <code class="parameter-name">useCapture</code> parameter was mandatory in
- DOM2 Events [<a href="#references-DOM2Events">DOM2 Events</a>], and omitting this parameter could cause an error in older implementations.</p>
- </dd>
- </dl>
- </dd>
-
- <dt>void removeEventListener()</dt>
- <dd>
- <p><em>Modified in DOM Level 3</em></p>
-
- <p>Removes an event listener. Calling <code>removeEventListener</code> with arguments that do not identify any currently registered <a href="#interface-EventListener"><code>
- EventListener</code></a> on the <code>EventTarget</code> has no effect. </p>
-
- <dl class="parameters">
- <dt>DOMString type</dt>
- <dd>
- <p>Specifies the <a href="#widl-Event-type"><code>Event.type</code></a> for which the user registered the event listener.</p>
- </dd>
-
- <dt>EventListener? listener</dt>
- <dd>
- <p>The <a href="#interface-EventListener"><code>EventListener</code></a> to be removed.</p>
- </dd>
-
- <dt>optional boolean useCapture = false</dt>
- <dd>
- <p>Specifies whether the <a href="#interface-EventListener"><code>EventListener</code></a> being removed was registered for the capture phase or not. Implementations
- MUST treat the same listener that was registered twice with both <code>useCapture</code> true and <code>useCapture</code> false as independent registrations, and
- remove them independently.</p>
-
- <p class="note"><strong>Authoring Note:</strong> If a listener was registered twice, once for the capture and target phases and once for the target and bubbling phases,
- this represents two unique registrations. Removal of an event listener registered for the capture and target phases does not affect the same event listener registered
- for the target and bubbling phases, and vice versa.</p>
-
- <p>This parameter MUST be optional. If not provided, the <a href="#widl-EventTarget-removeEventListener"><code>EventTarget.removeEventListener</code></a> method MUST behave as if
- <code class="parameter-name">useCapture</code> were specified to be <code>false</code>.</p>
-
- <p class="note"><strong>Authoring Note:</strong> The <code class="parameter-name">useCapture</code> parameter was mandatory in
- DOM2 Events [<a href="#references-DOM2Events">DOM2 Events</a>], and omitting this parameter could cause an error in older implementations.</p>
- </dd>
- </dl>
- </dd>
-
- <dt>boolean dispatchEvent()</dt>
- <dd>
- <p><em>Modified in DOM Level 3</em></p>
-
- <p>Dispatches an event into the implementation's event model. The <a class="def" href="#glossary-event-target">event target</a> of the event MUST be the <code>EventTarget</code>
- object on which <code>dispatchEvent</code> is called.</p>
-
- <p>If after the event object finishes propagating through the DOM event flow its <a href="#widl-Event-defaultPrevented"><code>Event.defaultPrevented</code></a>
- attribute is <code>false</code>, then this method returns <code>true</code>. Otherwise this method returns <code>false</code>.</p>
-
- <p class="warning"><strong>Warning!</strong> For security reasons, events dispatched using <a href="#widl-EventTarget-dispatchEvent">
- <code>EventTarget.dispatchEvent()</code></a> MUST have a <code class="attribute-name"><a href="#widl-Event-isTrusted">isTrusted</a></code> attribute value
- of <code>false</code>. See <a href="#trusted-events">trusted events</a> for more details.</p>
-
- <p class="note"><strong>Note:</strong> While a dispatch (triggered by <a href="#widl-EventTarget-dispatchEvent"><code>EventTarget.dispatchEvent()</code></a>) is in progress, calls to
- <a href="#widl-Event-initEvent"><code>Event.initEvent()</code></a> are ignored (the method returns immediately without side-effects) and calls to
- <a href="#widl-EventTarget-dispatchEvent"><code>EventTarget.dispatchEvent()</code></a> result in an exception.</p>
-
- <dl class="parameters">
- <dt>Event event</dt>
- <dd>
- <p>The event to be dispatched.</p>
- <p class="note"><strong>Note: </strong>This parameter receives an <code>Event</code> object, or any object that inherits from <code>Event</code>, e.g.,
- <a href="#interface-MouseEvent"><code>MouseEvent</code></a>,
- <a href="#interface-KeyboardEvent"><code>KeyboardEvent</code></a>,
- <code>MutationEvent</code>, etc.</p>
- </dd>
- </dl>
-
- <p><strong>Exceptions:</strong>
- If the <a href="#widl-Event-type"><code>Event.type</code></a> was not specified by initializing the event before <code>dispatchEvent</code> was called OR
- the <a href="#interface-Event"><code>Event</code></a> object is already being dispatched, a <code>DOMException</code> of type <em><code>InvalidStateError</code></em>
- is thrown.</p>
- </dd>
- </dl>
- </section><!-- interface-EventTarget -->
-
- <section id="interface-EventListener">
- <h2>Interface EventListener</h2>
-
- <p class="intro-dom">Introduced in DOM Level 2</p>
-
- <p>The <code>EventListener</code> interface is the primary way to handle events. <code>EventListener</code> represents the callback object that the user agent will
- invoke when dispatching an <code>Event</code> to an <a href="#interface-EventTarget"><code>EventTarget</code></a>.</p>
-
- <p class="note"><strong>Note:</strong> Authors define an object which implements the <code>EventListener</code> interface and register their event listener using
- <a href="#widl-EventTarget-addEventListener"><code>EventTarget.addEventListener</code></a>. In JavaScript, an <code>EventListener</code> can be either a function or an object
- with a <code>handleEvent</code> member function.</p>
-
- <p class="note"><strong>Note:</strong> It is a best practice for authors to remove their <code>EventListener</code> from its <a href="#interface-EventTarget"><code>EventTarget</code></a>
- after they have completed using the listener.</p>
-
- <p>Copying a <code>Node</code>, with methods such as <code>Node.cloneNode</code> or <code>Range.cloneContents</code> [<cite><a class="informative"
- href="#references-DOMRange">DOM Range</a></cite>], MUST NOT copy the event listeners attached to it.
- Event listeners can be attached to the newly created <code>Node</code> afterwards, if so desired.</p>
-
- <p>Moving a <code>Node</code>, with methods such as <code>Document.adoptNode</code>, <code>Node.appendChild</code>, or <code>Range.extractContents</code>
- [<cite><a class="informative" href="#references-DOMRange">DOM Range</a></cite>], MUST NOT cause the event listeners attached to it to be removed or un-registered.</p>
-
- <dl class="idl" title="interface EventListener">
- <dt>void handleEvent()</dt>
- <dd>
- <p>This method MUST be called whenever an event occurs of the event type for which the <code>EventListener</code> interface was registered.</p>
-
- <dl class="parameters">
- <dt>Event event</dt>
- <dd>
- <p>The <a href="#interface-Event"><code>Event</code></a> contains contextual information about the <a class="def" href="#glossary-event">event</a>.</p>
- </dd>
- </dl>
- </dd>
- </dl>
- </section><!-- interface-EventListener -->
-
- <section id="interface-DocumentEvent">
- <h2>Interface DocumentEvent</h2>
-
- <p class="intro-dom">Introduced in DOM Level 2</p>
-
- <p>The <code>DocumentEvent</code> interface provides a mechanism by which the user can create an <a href="#interface-Event"><code>Event</code></a> object of a type supported
- by the implementation. The <code>DocumentEvent</code> interface MUST be implemented on the same object that implements the <code>Document</code> interface.</p>
-
- <dl class="idl" title="Document implements DocumentEvent">
- </dl>
-
- <!-- NOTE: This is preserved as a [NoInterfaceObject] definition (rather than a partial interface Document { ..} because SVG also needs to implement this interface on their SVGSVGElement interface -->
- <dl class="idl" title="[NoInterfaceObject] interface DocumentEvent">
- <dt>[NewObject] Event createEvent()</dt>
- <dd>
- <p class="intro-dom">Modified in DOM Level 3</p>
-
- <p>Creates an event object of the type specified. Returns the newly created object.</p>
-
-<p class="issue">
-The text of this note needs to be reviewed. Remove reference to initMouseEvent (here and throughout main text).
-</p>
- <p class="note"><strong>Note: </strong>After calling <code>createEvent</code>, and prior to dispatching the event with the
- <a href="#widl-EventTarget-dispatchEvent"><code>EventTarget.dispatchEvent()</code></a> method, the
- <a href="#interface-Event"><code>Event</code></a> will need to be initialized with the appropriate event initialization
- method (e.g., <code>initEvent</code>, <code>initMouseEvent</code>, etc.) in order to associate it with an event type and related values.</p>
-
- <div class="example">
- <div class="example-title"></div>
- <p>A content author wishing to synthesize some kind of <a href="#interface-UIEvent"><code>UIEvent</code></a>
- would invoke <a href="#widl-DocumentEvent-createEvent"><code>DocumentEvent.createEvent("UIEvent")</code></a>. The <a href="#widl-UIEvent-initUIEvent"><code>
- UIEvent.initUIEvent()</code></a> method could then be called on the newly created <a class="noxref" href="#interface-UIEvent"><code>UIEvent</code></a> object to
- set the specific type of user interface event to be dispatched, <a class="eventtype" href="#event-type-scroll"><code>scroll</code></a> for example, and set its
- context information, e.g., <a href="#widl-UIEvent-detail"><code>UIEvent.detail</code></a>.</p>
- </div>
-
- <p class="warning"><strong>Warning!</strong> For security reasons, events generated using <a href="#widl-DocumentEvent-createEvent">
- <code>DocumentEvent.createEvent("Event")</code></a> MUST have a <code class="attribute-name"><a href="#widl-Event-isTrusted">isTrusted</a></code> attribute
- value of <code>false</code>. See <a href="#trusted-events">trusted events</a> for more details.</p>
-
- <p><strong>Exceptions:</strong>
- If the implementation does not support the <a href="#interface-Event"><code>Event</code></a> interface requested, a <code>DOMException</code> of type <em><code>NotSupportedError</code></em>
- is thrown.</p>
-
- <dl class="parameters">
- <dt>DOMString eventInterface</dt>
- <dd>
- <p>The <code>eventInterface</code> parameter specifies the name of the DOM Events interface to be supported by the created event
- object, e.g., <code>"Event"</code>, <code>"MouseEvent"</code>, <code>"MutationEvent"</code>, and so on.</p>
-
- <p>For backward compatibility, the following case-insensitive feature names are valid values for the parameter <code>eventInterface</code>:</p>
-
- <table class="data-table" summary="The first column contains the feature name, the second contains the resulting event interface returned by createEvent">
- <tr>
- <th>Legacy feature name</th>
- <th>Resulting event interface</th>
- </tr>
- <tr>
- <td><code>"Events"</code></td>
- <td><a href="#interface-Event"><code>Event</code></a></td>
- </tr>
- <tr>
- <td><code>"HTMLEvents"</code></td>
- <td><a href="#interface-Event"><code>Event</code></a></td>
- </tr>
- <tr>
- <td><code>"UIEvents"</code></td>
- <td><a href="#interface-UIEvent"><code>UIEvent</code></a></td>
- </tr>
- <tr>
- <td><code>"MouseEvents"</code></td>
- <td><a href="#interface-MouseEvent"><code>MouseEvent</code></a></td>
- </tr>
- <tr>
- <td><code>"MutationEvents"</code></td>
- <td><a href="#interface-MutationEvent"><code>MutationEvent</code></a></td>
- </tr>
- </table>
-
- </dd>
- </dl>
- </dd>
- </dl>
- </section><!-- interface-DocumentEvent -->
-
<section id="event-types-list">
<h3>List of Event Types</h3>