Event

  • Revision slug: DOM/event
  • Revision title: Event
  • Revision id: 23777
  • Created:
  • Creator: dbruant
  • Is current revision? No
  • Comment 46 words added

Revision Content

Introduction

This chapter describes the DOM Event Model. The Event interface itself is described, as well as the interfaces for event registration on nodes in the DOM, and event listeners, and several longer examples that show how the various event interfaces relate to one another.

There is an excellent diagram that clearly explains the three phases of event flow through the DOM in the DOM Level 3 Events draft.

DOM Event interface

Event handlers may be attached to various objects including DOM elements, document, the window object, etc. When an event occurs, an event object is created and passed sequentially to the event listeners.

The DOM Event interface is accessible from within the handler function, via the event object passed as the first argument. The following simple example shows how an event object is passed to the event handler function, and can be used from within one such function.

function foo(evt) {
  // the evt parameter is automatically assigned the event object
  alert(evt);
}
table_el.onclick = foo;

Also see Example 5: Event Propagation in the Examples chapter for a more detailed example of how events move through the DOM.

DOM event subclasses

Registering event listeners

There are 3 ways to register events to a DOM element.

HTML attribute

<button onclick="alert('Hello world!')">

This way should be avoided. This makes the markup bigger and less readable. Concerns of content/structure and behavior are not well-separated, making a bug harder to find.

DOM element properties

// Assuming myButton is a button element
myButton.onclick = function(){alert('Hello world');};

The problem with this method is that only one handler can be set per element and per event.

element.addEventListener

// Assuming myButton is a button element
myButton.addEventListener('click', function(){alert('Hello world');}, false);

This is the standard method which has none of the problem mentioned before. You should use this method. More details can be found on the specific page. Internet Explorer 6-8 do not support it. Instead, they have the element.attachEvent method which works pretty much the same way.

Properties

{{ domxref("event.bubbles") }}
A boolean indicating whether the event bubbles up through the DOM or not.
{{ domxref("event.cancelBubble") }} {{ Deprecated_inline() }}
A boolean indicating whether the bubbling of the event has been canceled or not.
{{ domxref("event.cancelable") }}
A boolean indicating whether the event is cancelable.
{{ domxref("event.currentTarget") }}
A reference to the currently registered target for the event.
{{ domxref("event.defaultPrevented") }}
Indicates whether or not {{ domxref("event.preventDefault()") }} has been called on the event.
{{ domxref("event.detail") }}
Detail about the event, depending on the type of event.
{{ domxref("event.eventPhase") }}
Indicates which phase of the event flow is being processed.
{{ domxref("event.explicitOriginalTarget") }}
The explicit original target of the event (Mozilla-specific).
{{ domxref("event.mozInputSource") }} {{ gecko_minversion_inline("1.9.3") }} {{ non-standard_inline() }}
The type of device that generated the event. This is a Gecko-specific value.
{{ domxref("event.originalTarget") }}
The original target of the event, before any retargetings (Mozilla-specific).
{{ domxref("event.target") }}
A reference to the target to which the event was originally dispatched.
{{ domxref("event.timeStamp") }}
The time that the event was created.
{{ domxref("event.type") }}
The name of the event (case-insensitive).
{{ domxref("event.isTrusted") }}
Indicates whether or not the event was initiated by the browser (after a user click for instance) or by a script (using an event creation method, like event.initEvent)

Methods

{{ domxref("event.initEvent") }}
Initializes the value of an Event created through the DocumentEvent interface.
{{ domxref("event.preventBubble") }} {{ Obsolete_inline("1.9") }}
Prevents the event from bubbling. Obsolete, use {{ domxref("event.stopPropagation") }} instead.
{{ domxref("event.preventCapture") }} {{ Obsolete_inline("1.9") }}
Obsolete, use {{ domxref("event.stopPropagation") }} instead.
{{ domxref("event.preventDefault") }}
Cancels the event (if it is cancelable).
{{ domxref("event.stopImmediatePropagation") }}
For this particular event, no other listener will be called. Neither those attached on the same element, nor those attached on elements which will be traversed later (in capture phase, for instance)
{{ domxref("event.stopPropagation") }}
Stops the propagation of events further along in the DOM.

See also

{{ languages( { "es": "es/DOM/event", "fr": "fr/DOM/event", "ja": "ja/DOM/event", "pl": "pl/DOM/event" } ) }}

Replacing Emoji...

Revision Source

<h2 name="Introduction">Introduction</h2>
<p>This chapter describes the DOM Event Model. The <a class="external" href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-Event">Event</a> interface itself is described, as well as the interfaces for event registration on nodes in the DOM, and <a href="/en/DOM/element.addEventListener" title="en/DOM/element.addEventListener">event listeners</a>, and several longer examples that show how the various event interfaces relate to one another.</p>
<p>There is an excellent diagram that clearly explains the three phases of event flow through the DOM in the <a class="external" href="http://www.w3.org/TR/DOM-Level-3-Events/#dom-event-architecture" title="http://www.w3.org/TR/DOM-Level-3-Events/#dom-event-architecture">DOM Level 3 Events draft</a>.</p>
<h3 name="DOM_Event_interface">DOM <code>Event</code> interface</h3>
<p>Event handlers may be attached to various objects including DOM elements, document, the <a href="/en/JavaScript/Reference/Global_Objects" title="Global Objects">window object</a>, etc. When an event occurs, an event object is created and passed sequentially to the event listeners.</p>
<p>The DOM <code>Event</code> interface is accessible from within the handler function, via the event object passed as the first argument. The following simple example shows how an event object is passed to the event handler function, and can be used from within one such function.</p>
<pre class="brush: js">function foo(evt) {
  // the evt parameter is automatically assigned the event object
  alert(evt);
}
table_el.onclick = foo;
</pre>
<p>Also see <a href="/en/Gecko_DOM_Reference/Examples#Example_5:_Event_Propagation" title="en/Gecko_DOM_Reference/Examples#Example_5:_Event_Propagation">Example 5: Event Propagation</a> in the Examples chapter for a more detailed example of how events move through the DOM.</p>
<h4 name="DOM_event_subclasses">DOM event subclasses</h4>
<ul> <li><a href="/en/DOM/Event/UIEvent" title="en/DOM/Event/UIEvent">UIEvent</a> <ul> <li><a href="/en/DOM/KeyboardEvent" title="en/DOM/Event/UIEvent/KeyboardEvent">KeyboardEvent</a></li> <li><a href="/en/DOM/Event/UIEvent/MouseEvent" title="en/DOM/Event/UIEvent/MouseEvent">MouseEvent</a></li> <li><a href="/en/DOM/Event/UIEvent/FocusEvent" title="en/DOM/Event/UIEvent/FocusEvent">FocusEvent</a></li> <li><a href="/en/DOM/Event/UIEvent/WheelEvent" title="en/DOM/Event/UIEvent/WheelEvent">WheelEvent</a></li> <li><a href="/en/DOM/Event/UIEvent/CompositionEvent" title="en/DOM/Event/UIEvent/CompositionEvent">CompositionEvent</a></li> </ul> </li> <li><a href="/en/DOM/event/StorageEvent" title="en/DOM/Event/StorageEvent">StorageEvent</a></li> <li><a href="/En/DOM/Event/CustomEvent" title="en/DOM/Event/CustomEvent">CustomEvent</a> {{ gecko_minversion_inline("6.0") }}</li> <li><a href="/En/DOM/Event/MutationEvent" title="en/DOM/Event/MutationEvent">MutationEvent</a></li>
</ul><h2 name="DOM_event_handler_List">Registering event listeners</h2>
<p>There are 3 ways to register events to a DOM element.</p>
<h3>HTML attribute</h3>
<pre class="brush: html">&lt;button onclick="alert('Hello world!')"&gt;
</pre>
<p>This way should be avoided. This makes the markup bigger and less readable. Concerns of content/structure and behavior are not well-separated, making a bug harder to find.</p>
<h3>DOM element properties</h3>
<pre class="brush: js">// Assuming myButton is a button element
myButton.onclick = function(){alert('Hello world');};
</pre>
<p>The problem with this method is that only one handler can be set per element and per event.</p>
<h3><a href="/en/DOM/element.addEventListener" title="element.addEventListener">element.addEventListener</a></h3>
<pre class="brush: js">// Assuming myButton is a button element
myButton.addEventListener('click', function(){alert('Hello world');}, false);
</pre>
<p>This is the standard method which has none of the problem mentioned before. <strong>You should use this method.</strong> More details can be found on the <a href="/en/DOM/element.addEventListener" title="element.addEventListener">specific page</a>. Internet Explorer 6-8 do not support it. Instead, they have the element.attachEvent method which works pretty much the same way.</p><h2 name="Properties">Properties</h2>
<dl> <dt>{{ domxref("event.bubbles") }}</dt> <dd>A boolean indicating whether the event bubbles up through the DOM or not.</dd> <dt>{{ domxref("event.cancelBubble") }} {{ Deprecated_inline() }}</dt> <dd>A boolean indicating whether the bubbling of the event has been canceled or not.</dd> <dt>{{ domxref("event.cancelable") }}</dt> <dd>A boolean indicating whether the event is cancelable.</dd> <dt>{{ domxref("event.currentTarget") }}</dt> <dd>A reference to the currently registered target for the event.</dd> <dt>{{ domxref("event.defaultPrevented") }}</dt> <dd>Indicates whether or not {{ domxref("event.preventDefault()") }} has been called on the event.</dd> <dt>{{ domxref("event.detail") }}</dt> <dd>Detail about the event, depending on the type of event.</dd> <dt>{{ domxref("event.eventPhase") }}</dt> <dd>Indicates which phase of the event flow is being processed.</dd> <dt>{{ domxref("event.explicitOriginalTarget") }}</dt> <dd>The explicit original target of the event (Mozilla-specific).</dd> <dt>{{ domxref("event.mozInputSource") }} {{ gecko_minversion_inline("1.9.3") }} {{ non-standard_inline() }}</dt> <dd>The type of device that generated the event. This is a Gecko-specific value.</dd> <dt>{{ domxref("event.originalTarget") }}</dt> <dd>The original target of the event, before any retargetings (Mozilla-specific).</dd> <dt>{{ domxref("event.target") }}</dt> <dd>A reference to the target to which the event was originally dispatched.</dd> <dt>{{ domxref("event.timeStamp") }}</dt> <dd>The time that the event was created.</dd> <dt>{{ domxref("event.type") }}</dt> <dd>The name of the event (case-insensitive).</dd> <dt>{{ domxref("event.isTrusted") }}</dt> <dd>Indicates whether or not the event was initiated by the browser (after a user click for instance) or by a script (using an event creation method, like <a href="/en/DOM/event.initEvent" title="event.initEvent">event.initEvent</a>)</dd>
</dl><h2 name="Methods">Methods</h2>
<dl> <dt>{{ domxref("event.initEvent") }}</dt> <dd>Initializes the value of an Event created through the <code>DocumentEvent</code> interface.</dd> <dt>{{ domxref("event.preventBubble") }} {{ Obsolete_inline("1.9") }}</dt> <dd>Prevents the event from bubbling. Obsolete, use {{ domxref("event.stopPropagation") }} instead.</dd> <dt>{{ domxref("event.preventCapture") }} {{ Obsolete_inline("1.9") }}</dt> <dd>Obsolete, use {{ domxref("event.stopPropagation") }} instead.</dd> <dt>{{ domxref("event.preventDefault") }}</dt> <dd>Cancels the event (if it is cancelable).</dd> <dt>{{ domxref("event.stopImmediatePropagation") }}</dt> <dd>For this particular event, no other listener will be called. Neither those attached on the same element, nor those attached on elements which will be traversed later (in capture phase, for instance)</dd> <dt>{{ domxref("event.stopPropagation") }}</dt> <dd>Stops the propagation of events further along in the DOM.</dd>
</dl><h2>See also</h2>
<ul> <li><a class="internal" href="/En/Listening_to_events" title="En/Listening to events">Listening to events</a></li> <li><a class="internal" href="/En/Listening_to_events_on_all_tabs" title="En/Listening to events on all tabs">Listening to events on all tabs</a></li> <li><a href="/en/DOM/Creating_and_triggering_events" title="Creating and triggering custom events">Creating and triggering custom events</a></li> <li><a class="internal" href="/En/DOM/Mouse_gesture_events" title="En/DOM/Mouse gesture events">Mouse gesture events</a></li>
</ul>
<p>{{ languages( { "es": "es/DOM/event", "fr": "fr/DOM/event", "ja": "ja/DOM/event", "pl": "pl/DOM/event" } ) }}</p>
<div style="-webkit-border-radius: 8px; -moz-border-radius: 8px; -moz-opacity: 0; opacity: 0; display: none; padding: 10px; background-color: #ffffff; position: fixed; right: 0px; top: 0px;"><img alt="Replacing Emoji..." src="data:image/gif;base64,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" title="Replacing Emoji..."></div>
Revert to this revision