Event

  • Revision slug: DOM/event
  • Revision title: Event
  • Revision id: 23736
  • Created:
  • Creator: quazar
  • Is current revision? No
  • Comment no wording changes

Revision Content

{{ DomRef() }}

Introduction

This chapter describes the DOM Level 2 Event Model as implemented by Gecko. The Event interface itself is described, as well as the interfaces for event registration on nodes in the DOM, event handlers 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 elements in the DOM. When an event occurs, an event object is dynamically created, and passed sequentially to the event listeners that are allowed to handle the event. The DOM Event interface is then accessible within the handler function, via the event object passed as the first (and the only) argument.

Given that we don't list the three ways right here, the sentence is unclear, and is not perfectly right either IMO. -Nickolay There are three ways to attach an event listener to an element. With 2 of those techniques, the event object is passed to the handler function implicitly. The remaining technique requires you to specify the <code>event</code> object as a parameter, which is passed explicitly to the event handler function. 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.

Note there is no "evt" parameter passed in the code below. The event object gets passed automatically to foo. All that is needed is to define a parameter in the event handler to receive the event object.

function foo(evt) {
  // event handling functions like this one
  // get an implicit reference to the event object they handle
  // (in this case we chose to call it "evt").
  alert(evt);
}
table_el.onclick = foo;

This example is woefully simplistic, but it shows an important feature of events in the Gecko DOM, which is that event objects in the DOM are typically accessed in the event handler functions. Once you have a reference to the event object, you can access all of the properties and methods described in this chapter.

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

DOM event handler List

In addition to the event object described here, the Gecko DOM also provides methods for registering event listeners on nodes in the DOM, removing those event listeners, and dispatching events from the DOM. These and the various Event Handlers on HTML or XML elements are the main entry points for events in the DOM. These three methods are described in the DOM Element Reference list.

You can also pass the event object reference as a predefined parameter, named event, to the function that handles the event. This is very similar to the way this works, but for event objects, rather than element object references.

<html>
<head>
<title>event object parameter example</title>

<script type="text/javascript">

function showCoords(evt){
  alert(
    "clientX value: " + evt.clientX + "\n" +
    "clientY value: " + evt.clientY + "\n"
  );
}

</script>
</head>

<body onmousedown="showCoords(event)">
<p>To display the mouse coordinates click anywhere on the page.</p>
</body>
</html>

Using the predefined event object parameter allows you to pass other parameters to the event handling function as well, if required:

<html>
<head>
<title>event object & extra parameters example</title>

<script type="text/javascript">

var par2 = 'hello';
var par3 = 'world!';

function showCoords(evt, p2, p3){
  alert(
    "clientX value: " + evt.clientX + "\n"
    + "clientY value: " + evt.clientY + "\n"
    + "p2: " + p2 + "\n"
    + "p3: " + p3 + "\n"
  );
}

</script>
</head>

<body onmousedown="showCoords(event, par2, par3)">
<p>To display the mouse coordinates please click anywhere on the page.</p>
</body>
</html>

Properties

event.altKey 
Returns a boolean indicating whether the <alt> key was pressed during the event.
event.bubbles 
Returns a boolean indicating whether the event bubbles up through the DOM or not.
event.button 
Returns a mouse key.
event.cancelBubble 
{{ Deprecated_inline() }} Returns a boolean indicating whether the bubbling up of the event has been canceled or not.
event.cancelable 
Returns a boolean indicating whether the event is cancelable.
event.charCode 
Returns the Unicode value of a character key that was pressed as part of a keypress event. See also Gecko Keypress Event.
event.clientX 
Returns the horizontal position of the event.
event.clientY 
Returns the vertical position of the event.
event.ctrlKey 
Returns a boolean indicating whether the <ctrl> key was pressed during the event.
event.currentTarget 
Returns a reference to the currently registered target for the event.
event.detail 
Returns detail about the event, depending on the type of event.
event.eventPhase 
Used to indicate which phase of the event flow is currently being evaluated.
event.explicitOriginalTarget 
The explicit original target of the event (Mozilla-specific).
event.isChar 
Returns a boolean indicating whether the event produced a key character or not.
event.keyCode 
Returns the Unicode value of a non-character key in a keypress event or any key in any other type of keyboard event.
event.layerX 
Returns the horizontal coordinate of the event relative to the current layer.
event.layerY 
Returns the vertical coordinate of the event relative to the current layer.
event.metaKey 
Returns a boolean indicating whether the meta key was pressed during the event.
event.originalTarget 
The original target of the event, before any retargetings (Mozilla-specific).
event.pageX 
Returns the horizontal coordinate of the event relative to the page.
event.pageY 
Returns the vertical coorindate of the event relative to the page.
event.relatedTarget 
Identifies a secondary target for the event.
event.screenX 
Returns the horizontal position of the event on the screen.
event.screenY 
Returns the vertical position of the event on the screen.
event.shiftKey 
Returns a boolean indicating whether the <shift> key was pressed when the event was fired.
event.target 
Returns a reference to the target to which the event was originally dispatched.
event.timeStamp 
Returns the time that the event was created.
event.type 
Returns the name of the event (case-insensitive).
event.view 
The view attribute identifies the AbstractView from which the event was generated.
event.which 
Returns the Unicode value of a key in a keyboard event, regardless of which type of key is pressed.

Methods

event.initEvent 
Initializes the value of an Event created through the DocumentEvent interface.
event.initKeyEvent 
Initializes a keyboard event. Gecko-specific.
event.initMouseEvent 
Initializes a mouse event once it's been created
event.initUIEvent 
Initializes a UI event once it's been created.
event.initMessageEvent 
Initializes a message event once it's been created {{ Gecko_minversion_inline("1") }}
event.preventBubble 
{{ Obsolete_inline() }} Prevents the event from bubbling. This method is deprecated in favor of standard stopPropagation and is removed in Gecko 1.9.
event.preventCapture 
{{ Obsolete_inline() }} This method is deprecated in favor of standard stopPropagation and is removed in Gecko 1.9.
event.preventDefault 
Cancels the event (if it is cancelable).
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" } ) }}

Revision Source

<p>{{ DomRef() }}</p>
<h3 name="Introduction">Introduction</h3>
<p>This chapter describes the DOM Level 2 Event Model as implemented by <a href="/en/Gecko" title="en/Gecko">Gecko</a>. 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, event handlers 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>
<h4 name="DOM_Event_interface">DOM <code>Event</code> interface</h4>
<p>Event handlers may be attached to various elements in the DOM. When an event occurs, an event object is dynamically created, and passed sequentially to the event listeners that are allowed to handle the event. The DOM <code>Event</code> interface is then accessible within the handler function, via the event object passed as the first (and the only) argument.</p>
<p><span class="comment">Given that we don't list the three ways right here, the sentence is unclear, and is not perfectly right either IMO. -Nickolay There are three ways to attach an event listener to an element. With 2 of those techniques, the event object is passed to the handler function implicitly. The remaining technique requires you to specify the &lt;code&gt;event&lt;/code&gt; object as a parameter, which is passed explicitly to the event handler function.</span> 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>
<p>Note there is no "evt" parameter passed in the code below. The event object gets passed automatically to <em>foo</em>. All that is needed is to define a parameter in the event handler to receive the event object.</p>
<pre>function foo(evt) {
  // event handling functions like this one
  // get an implicit reference to the event object they handle
  // (in this case we chose to call it "evt").
  alert(evt);
}
table_el.onclick = foo;
</pre>
<p>This example is woefully simplistic, but it shows an important feature of events in the Gecko DOM, which is that event objects in the DOM are typically accessed in the event handler functions. Once you have a reference to the event object, you can access all of the properties and methods described in this chapter.</p>
<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>
<h5 name="DOM_event_subclasses">DOM event subclasses</h5>
<ul> <li><a href="/en/DOM/Event/UIEvent" title="en/DOM/Event/UIEvent">DOM:Event:UIEvent</a></li> <li><a href="/en/DOM/Event/UIEvent/KeyEvent" title="en/DOM/Event/UIEvent/KeyEvent">DOM:Event:UIEvent:KeyEvent</a></li> <li><a href="/en/DOM/Event/UIEvent/MouseEvent" title="en/DOM/Event/UIEvent/MouseEvent">DOM:Event:UIEvent:MouseEvent</a></li>
</ul>
<h4 name="DOM_event_handler_List">DOM event handler List</h4>
<p>In addition to the <code>event</code> object described here, the Gecko DOM also provides methods for registering event listeners on nodes in the DOM, removing those event listeners, and dispatching events from the DOM. These and the various <a href="/en/DOM/element#Event_Handlers" title="en/DOM/element#Event_Handlers">Event Handlers</a> on HTML or XML elements are the main entry points for events in the DOM. These three methods are described in the <a href="/en/DOM/element" title="en/DOM/element">DOM Element Reference</a> list.</p>
<p>You can also pass the event object reference as a predefined parameter, named <code>event</code>, to the function that handles the event. This is very similar to the way <code>this</code> works, but for event objects, rather than element object references.</p>
<pre>&lt;html&gt;
&lt;head&gt;
&lt;title&gt;event object parameter example&lt;/title&gt;

&lt;script type="text/javascript"&gt;

function showCoords(evt){
  alert(
    "clientX value: " + evt.clientX + "\n" +
    "clientY value: " + evt.clientY + "\n"
  );
}

&lt;/script&gt;
&lt;/head&gt;

&lt;body onmousedown="showCoords(event)"&gt;
&lt;p&gt;To display the mouse coordinates click anywhere on the page.&lt;/p&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>
<p>Using the predefined <code>event</code> object parameter allows you to pass other parameters to the event handling function as well, if required:</p>
<pre>&lt;html&gt;
&lt;head&gt;
&lt;title&gt;event object &amp; extra parameters example&lt;/title&gt;

&lt;script type="text/javascript"&gt;

var par2 = 'hello';
var par3 = 'world!';

function showCoords(evt, p2, p3){
  alert(
    "clientX value: " + evt.clientX + "\n"
    + "clientY value: " + evt.clientY + "\n"
    + "p2: " + p2 + "\n"
    + "p3: " + p3 + "\n"
  );
}

&lt;/script&gt;
&lt;/head&gt;

&lt;body onmousedown="showCoords(event, par2, par3)"&gt;
&lt;p&gt;To display the mouse coordinates please click anywhere on the page.&lt;/p&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>
<h3 name="Properties">Properties</h3>
<dl> <dt><a href="/en/DOM/event.altKey" title="en/DOM/event.altKey">event.altKey</a> </dt> <dd>Returns a boolean indicating whether the <code>&lt;alt&gt;</code> key was pressed during the event.</dd> <dt><a href="/en/DOM/event.bubbles" title="en/DOM/event.bubbles">event.bubbles</a> </dt> <dd>Returns a boolean indicating whether the event bubbles up through the DOM or not.</dd> <dt><a href="/en/DOM/event.button" title="en/DOM/event.button">event.button</a> </dt> <dd>Returns a mouse key.</dd> <dt><a href="/en/DOM/event.cancelBubble" title="en/DOM/event.cancelBubble">event.cancelBubble</a> </dt> <dd>{{ Deprecated_inline() }} Returns a boolean indicating whether the bubbling up of the event has been canceled or not.</dd> <dt><a href="/en/DOM/event.cancelable" title="en/DOM/event.cancelable">event.cancelable</a> </dt> <dd>Returns a boolean indicating whether the event is cancelable.</dd> <dt><a href="/en/DOM/event.charCode" title="en/DOM/event.charCode">event.charCode</a> </dt> <dd>Returns the Unicode value of a character key that was pressed as part of a <a href="/en/DOM/event/keypress" title="en/DOM/event/keypress">keypress</a> event. See also <a href="/en/Gecko_Keypress_Event" title="en/Gecko_Keypress_Event">Gecko Keypress Event</a>.</dd> <dt><a href="/en/DOM/event.clientX" title="en/DOM/event.clientX">event.clientX</a> </dt> <dd>Returns the horizontal position of the event.</dd> <dt><a href="/en/DOM/event.clientY" title="en/DOM/event.clientY">event.clientY</a> </dt> <dd>Returns the vertical position of the event.</dd> <dt><a href="/en/DOM/event.ctrlKey" title="en/DOM/event.ctrlKey">event.ctrlKey</a> </dt> <dd>Returns a boolean indicating whether the <code>&lt;ctrl&gt;</code> key was pressed during the event.</dd> <dt><a href="/en/DOM/event.currentTarget" title="en/DOM/event.currentTarget">event.currentTarget</a> </dt> <dd>Returns a reference to the currently registered target for the event.</dd> <dt><a href="/en/DOM/event.detail" title="en/DOM/event.detail">event.detail</a> </dt> <dd>Returns detail about the event, depending on the type of event.</dd> <dt><a href="/en/DOM/event.eventPhase" title="en/DOM/event.eventPhase">event.eventPhase</a> </dt> <dd>Used to indicate which phase of the event flow is currently being evaluated.</dd> <dt><a href="/en/DOM/event.explicitOriginalTarget" title="en/DOM/event.explicitOriginalTarget">event.explicitOriginalTarget</a> </dt> <dd>The explicit original target of the event (Mozilla-specific).</dd> <dt><a href="/en/DOM/event.isChar" title="en/DOM/event.isChar">event.isChar</a> </dt> <dd>Returns a boolean indicating whether the event produced a key character or not.</dd> <dt><a href="/en/DOM/event.keyCode" title="en/DOM/event.keyCode">event.keyCode</a> </dt> <dd>Returns the Unicode value of a non-character key in a <a href="/en/DOM/event/keypress" title="en/DOM/event/keypress">keypress</a> event or any key in any other type of keyboard event.</dd> <dt><a href="/en/DOM/event.layerX" title="en/DOM/event.layerX">event.layerX</a> </dt> <dd>Returns the horizontal coordinate of the event relative to the current layer.</dd> <dt><a href="/en/DOM/event.layerY" title="en/DOM/event.layerY">event.layerY</a> </dt> <dd>Returns the vertical coordinate of the event relative to the current layer.</dd> <dt><a href="/en/DOM/event.metaKey" title="en/DOM/event.metaKey">event.metaKey</a> </dt> <dd>Returns a boolean indicating whether the <code>meta</code> key was pressed during the event.</dd> <dt><a href="/en/DOM/event.originalTarget" title="en/DOM/event.originalTarget">event.originalTarget</a> </dt> <dd>The original target of the event, before any retargetings (Mozilla-specific).</dd> <dt><a href="/en/DOM/event.pageX" title="en/DOM/event.pageX">event.pageX</a> </dt> <dd>Returns the horizontal coordinate of the event relative to the page.</dd> <dt><a href="/en/DOM/event.pageY" title="en/DOM/event.pageY">event.pageY</a> </dt> <dd>Returns the vertical coorindate of the event relative to the page.</dd> <dt><a href="/en/DOM/event.relatedTarget" title="en/DOM/event.relatedTarget">event.relatedTarget</a> </dt> <dd>Identifies a secondary target for the event.</dd> <dt><a href="/en/DOM/event.screenX" title="en/DOM/event.screenX">event.screenX</a> </dt> <dd>Returns the horizontal position of the event on the screen.</dd> <dt><a href="/en/DOM/event.screenY" title="en/DOM/event.screenY">event.screenY</a> </dt> <dd>Returns the vertical position of the event on the screen.</dd> <dt><a href="/en/DOM/event.shiftKey" title="en/DOM/event.shiftKey">event.shiftKey</a> </dt> <dd>Returns a boolean indicating whether the <code>&lt;shift&gt;</code> key was pressed when the event was fired.</dd> <dt><a href="/en/DOM/event.target" title="en/DOM/event.target">event.target</a> </dt> <dd>Returns a reference to the target to which the event was originally dispatched.</dd> <dt><a href="/en/DOM/event.timeStamp" title="en/DOM/event.timeStamp">event.timeStamp</a> </dt> <dd>Returns the time that the event was created.</dd> <dt><a href="/en/DOM/event.type" title="en/DOM/event.type">event.type</a> </dt> <dd>Returns the name of the event (case-insensitive).</dd> <dt><a href="/en/DOM/event.view" title="en/DOM/event.view">event.view</a> </dt> <dd>The view attribute identifies the <code>AbstractView</code> from which the event was generated.</dd> <dt><a href="/en/DOM/event.which" title="en/DOM/event.which">event.which</a> </dt> <dd>Returns the Unicode value of a key in a keyboard event, regardless of which type of key is pressed.</dd>
</dl>
<h3 name="Methods">Methods</h3>
<dl> <dt><a href="/en/DOM/event.initEvent" title="en/DOM/event.initEvent">event.initEvent</a> </dt> <dd>Initializes the value of an Event created through the <code>DocumentEvent</code> interface.</dd> <dt><a href="/en/DOM/event.initKeyEvent" title="en/DOM/event.initKeyEvent">event.initKeyEvent</a> </dt> <dd>Initializes a keyboard event. Gecko-specific.</dd> <dt><a href="/en/DOM/event.initMouseEvent" title="en/DOM/event.initMouseEvent">event.initMouseEvent</a> </dt> <dd>Initializes a mouse event once it's been created</dd> <dt><a href="/en/DOM/event.initUIEvent" title="en/DOM/event.initUIEvent">event.initUIEvent</a> </dt> <dd>Initializes a UI event once it's been created.</dd> <dt><a href="/en/DOM/event.initMessageEvent" title="en/DOM/event.initMessageEvent">event.initMessageEvent</a> </dt> <dd>Initializes a message event once it's been created {{ Gecko_minversion_inline("1") }}</dd> <dt><a href="/en/DOM/event.preventBubble" title="en/DOM/event.preventBubble">event.preventBubble</a> </dt> <dd>{{ Obsolete_inline() }} Prevents the event from bubbling. This method is deprecated in favor of standard <a href="/en/DOM/event.stopPropagation" title="en/DOM/event.stopPropagation">stopPropagation</a> and is <a href="/en/Gecko_1.9_Changes_affecting_websites" title="en/Gecko_1.9_Changes_affecting_websites">removed in Gecko 1.9</a>.</dd> <dt><a href="/en/DOM/event.preventCapture" title="en/DOM/event.preventCapture">event.preventCapture</a> </dt> <dd>{{ Obsolete_inline() }} This method is deprecated in favor of standard <a href="/en/DOM/event.stopPropagation" title="en/DOM/event.stopPropagation">stopPropagation</a> and is <a href="/en/Gecko_1.9_Changes_affecting_websites" title="en/Gecko_1.9_Changes_affecting_websites">removed in Gecko 1.9</a>.</dd> <dt><a href="/en/DOM/event.preventDefault" title="en/DOM/event.preventDefault">event.preventDefault</a> </dt> <dd>Cancels the event (if it is cancelable).</dd> <dt><a href="/en/DOM/event.stopPropagation" title="en/DOM/event.stopPropagation">event.stopPropagation</a> </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 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>
Revert to this revision