Revision 485057 of MouseEvent

  • Revision slug: Web/API/MouseEvent
  • Revision title: MouseEvent
  • Revision id: 485057
  • Created:
  • Creator: Jeremie
  • Is current revision? No
  • Comment

Revision Content

Summary

The DOM MouseEvent interface represents events that occur due to the user interacting with a pointing device (such as a mouse).

Common events using this interface include {{event("click")}}, {{event("dblclick")}}, {{event("mouseup")}}, {{event("mousedown")}}. The list of all events using this interface is provided in the Events reference.

MouseEvent derives from {{domxref("UIEvent")}}, which in turn derives from {{domxref("Event")}}.

Properties

{{domxref("MouseEvent.altKey")}} {{readonlyinline}}
true if the alt key was down when the mouse event was fired.
{{domxref("MouseEvent.button")}} {{readonlyinline}}
The button number that was pressed when the mouse event was fired. 

Left button=0, middle button=1 (if present), right button=2. For mice configured for left handed use in which the button actions are reversed the values are instead read from right to left.

{{domxref("MouseEvent.buttons")}} {{readonlyinline}} {{dom_level("3")}} {{gecko_minversion_inline("15.0")}}

The buttons being pressed when the mouse event was fired

Left button=1, Right button=2, Middle (wheel) button=4, 4th button (typically, "Browser Back" button)=8, 5th button (typically, "Browser Forward" button)=16. If two or more buttons are pressed, returns the logical sum of the values. E.g., if Left button and Right button are pressed, returns 3 (=1 | 2).

{{domxref("MouseEvent.clientX")}} {{readonlyinline}}
The X coordinate of the mouse pointer in local (DOM content) coordinates.
{{domxref("MouseEvent.clientY")}} {{readonlyinline}}
The Y coordinate of the mouse pointer in local (DOM content) coordinates.
{{domxref("MouseEvent.ctrlKey")}} {{readonlyinline}}
true if the control key was down when the mouse event was fired.
{{domxref("MouseEvent.metaKey")}} {{readonlyinline}}
true if the meta key was down when the mouse event was fired.
{{domxref("MouseEvent.movementX")}} {{readonlyinline}}
The X coordinate of the mouse pointer relative to the position of the last {{event("mousemove")}} event. In other words, actualEvent.movementX = actualEvent.screenX - previousEvent.screenX.
{{domxref("MouseEvent.movementY")}} {{readonlyinline}}
The Y coordinate of the mouse pointer relative to the position of the last {{event("mousemove")}} event. In other words, actualEvent.movementY = actualEvent.screenY - previousEvent.screenY.
{{domxref("MouseEvent.relatedTarget")}} {{readonlyinline}}

The secondary target for the event, if there is one.

For {{event("mouseenter")}}/{{event("mouseleave")}}, {{event("mouseover")}}/{{event("mouseout")}} events an event's relatedTarget equals the {{domxref("Event", "", "target")}} of the complementary event. For example, the relatedTarget for mouseleave is the target for the corresponding mouseenter event.

For events with no secondary target, relatedTarget returns null.

{{domxref("MouseEvent.screenX")}} {{readonlyinline}}
The X coordinate of the mouse pointer in global (screen) coordinates.
{{domxref("MouseEvent.screenY")}} {{readonlyinline}}
The Y coordinate of the mouse pointer in global (screen) coordinates.
{{domxref("MouseEvent.shiftKey")}} {{readonlyinline}}
true if the shift key was down when the mouse event was fired.
{{domxref("MouseEvent.mozPressure")}} {{non-standard_inline()}} {{gecko_minversion_inline("2.0")}} {{readonlyinline}}
The amount of pressure applied to a touch or tablet device when generating the event; this value ranges between 0.0 (minimum pressure) and 1.0 (maximum pressure).
{{domxref("MouseEvent.mozInputSource")}} {{non-standard_inline()}} {{gecko_minversion_inline("2.0")}} {{readonlyinline}}

The type of device that generated the event (one of the MOZ_SOURCE_* constants listed below).

This lets you, for example, determine whether a mouse event was generated by an actual mouse or by a touch event (which might affect the degree of accuracy with which you interpret the coordinates associated with the event).

Methods

{{domxref("MouseEvent.getModifierState()")}} {{dom_level("3")}} {{gecko_minversion_inline("15.0")}}
Returns the current state of the specified modifier key. See the {{domxref("KeyboardEvent", "KeyboardEvent", "getModifierState()")}} documentation for details.

Specifications

Specification Status Comment
{{SpecName('DOM2 Events','#Events-MouseEvent','MouseEvent')}} {{Spec2('DOM2 Events')}}  
{{SpecName('DOM3 Events','#events-mouseevents','MouseEvent')}} {{Spec2('DOM3 Events')}}  

Browser compatibility

{{ CompatibilityTable() }}

Feature Firefox (Gecko) Chrome Internet Explorer Opera Safari
Basic support {{CompatVersionUnknown()}} {{CompatVersionUnknown()}} {{CompatVersionUnknown()}} {{CompatVersionUnknown()}} {{CompatVersionUnknown()}}
{{domxref("MouseEvent.movementX","movementX")}}
{{domxref("MouseEvent.movementY","movementY")}}
{{CompatVersionUnknown()}} {{property_prefix("moz")}} {{CompatVersionUnknown()}} {{property_prefix("webkit")}} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }}
Feature Firefox Mobile (Gecko) Android IE Mobile Opera Mobile Safari Mobile
Basic support {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }}

Gecko notes

Gecko supports the {{domxref("MouseEvent.buttons","buttons")}} attribute on Windows, Linux (GTK) and Mac with the following restriction:

  • On Windows, if user installed a mouse driver and its utility software which can customize button actions (e.g., IntelliPoint and SetPoint), the Middle (wheel) button, 4th button and 5th button may not be set actually even when they're pressed.
  • On Linux (GTK), 4th button and 5th button are not supported. And also, mouseup event always have the releasing button information in this attribute value.
  • On Mac OS X 10.5, buttons attribute always returns 0 because there is no platform API for implementing this feature.

Specific constants

The possible values for MouseEvent.mozInputSource are listed in the following table. They are available as properties on the MouseEvent interface (e.g. MouseEvent.MOZ_SOURCE_UNKNOWN).

Constant name Value Desription
MOZ_SOURCE_UNKNOWN 0 The input device is unknown.
MOZ_SOURCE_MOUSE 1 The event was generated by a mouse (or mouse-like device).
MOZ_SOURCE_PEN 2 The event was generated by a pen on a tablet.
MOZ_SOURCE_ERASER 3 The event was generated by an eraser on a tablet.
MOZ_SOURCE_CURSOR 4 The event was generated by a cursor.
MOZ_SOURCE_TOUCH 5 The event was generated on a touch interface.
MOZ_SOURCE_KEYBOARD 6 The event was generated by a keyboard.

 

Revision Source

<h2 id="Summary">Summary</h2>
<p>The DOM&nbsp;<code>MouseEvent</code> interface represents events that occur due to the user interacting with a pointing device (such as a mouse).</p>
<p>Common events using this interface include {{event("click")}}, {{event("dblclick")}}, {{event("mouseup")}}, {{event("mousedown")}}. The list of all events using this interface is provided in the <a href="/en-US/docs/Web/Reference/Events" title="/en-US/docs/Web/Reference/Events">Events reference</a>.</p>
<p><code>MouseEvent</code> derives from {{domxref("UIEvent")}}, which in turn derives from {{domxref("Event")}}.</p>
<h2 id="Properties">Properties</h2>
<dl>
 <dt>
  {{domxref("MouseEvent.altKey")}} {{readonlyinline}}</dt>
 <dd>
  <code>true</code> if the alt key was down when the mouse event was fired.</dd>
 <dt>
  {{domxref("MouseEvent.button")}} {{readonlyinline}}</dt>
 <dd>
  The button number that was pressed when the mouse event was fired.&nbsp;
  <p>Left button=0, middle button=1 (if present), right button=2. For mice configured for left handed use in which the button actions are reversed the values are instead read from right to left.</p>
 </dd>
 <dt>
  {{domxref("MouseEvent.buttons")}} {{readonlyinline}} {{dom_level("3")}} {{gecko_minversion_inline("15.0")}}</dt>
 <dd>
  <p>The buttons being pressed when the mouse event was fired</p>
  <p>Left button=1, Right button=2, Middle (wheel) button=4, 4th button (typically, "Browser Back" button)=8, 5th button (typically, "Browser Forward" button)=16. If two or more buttons are pressed, returns the logical sum of the values. E.g., if Left button and Right button are pressed, returns 3 (=1 | 2).</p>
 </dd>
 <dt>
  {{domxref("MouseEvent.clientX")}} {{readonlyinline}}</dt>
 <dd>
  The X coordinate of the mouse pointer in local (DOM content)&nbsp;coordinates.</dd>
 <dt>
  {{domxref("MouseEvent.clientY")}} {{readonlyinline}}</dt>
 <dd>
  The Y coordinate of the mouse pointer in local (DOM content)&nbsp;coordinates.</dd>
 <dt>
  {{domxref("MouseEvent.ctrlKey")}} {{readonlyinline}}</dt>
 <dd>
  <code>true</code> if the control key was down when the mouse event was fired.</dd>
 <dt>
  {{domxref("MouseEvent.metaKey")}} {{readonlyinline}}</dt>
 <dd>
  <code>true</code> if the meta key was down when the mouse event was fired.</dd>
 <dt>
  {{domxref("MouseEvent.movementX")}} {{readonlyinline}}</dt>
 <dd>
  The X coordinate of the mouse pointer relative to the position of the last {{event("mousemove")}} event. In other words, <code>actualEvent.movementX = </code><code>actualEvent</code><code>.screenX - previousEvent.screenX</code>.</dd>
 <dt>
  {{domxref("MouseEvent.movementY")}} {{readonlyinline}}</dt>
 <dd>
  The Y coordinate of the mouse pointer relative to the position of the last {{event("mousemove")}} event. In other words, <code>actualEvent.movementY = </code><code>actualEvent</code><code>.screenY - previousEvent.screenY</code>.</dd>
 <dt>
  {{domxref("MouseEvent.relatedTarget")}} {{readonlyinline}}</dt>
 <dd>
  <p>The secondary target for the event, if there is one.</p>
  <p>For {{event("mouseenter")}}/{{event("mouseleave")}}, {{event("mouseover")}}/{{event("mouseout")}} events an event's <code>relatedTarget</code> equals the {{domxref("Event", "", "target")}} of the complementary event. For example, the <code>relatedTarget</code> for <code>mouseleave</code> is the <code>target</code> for the corresponding <code>mouseenter</code> event.</p>
  <p>For events with no secondary target, <code>relatedTarget</code> returns <code>null</code>.</p>
 </dd>
 <dt>
  {{domxref("MouseEvent.screenX")}} {{readonlyinline}}</dt>
 <dd>
  The X coordinate of the mouse pointer in global (screen)&nbsp;coordinates.</dd>
 <dt>
  {{domxref("MouseEvent.screenY")}} {{readonlyinline}}</dt>
 <dd>
  The Y coordinate of the mouse pointer in global (screen)&nbsp;coordinates.</dd>
 <dt>
  {{domxref("MouseEvent.shiftKey")}} {{readonlyinline}}</dt>
 <dd>
  <code>true</code> if the shift key was down when the mouse event was fired.</dd>
 <dt>
  {{domxref("MouseEvent.mozPressure")}} {{non-standard_inline()}}&nbsp;{{gecko_minversion_inline("2.0")}} {{readonlyinline}}</dt>
 <dd>
  The amount of pressure applied to a touch or tablet device when generating the event; this value ranges between 0.0 (minimum pressure)&nbsp;and 1.0 (maximum pressure).</dd>
 <dt>
  {{domxref("MouseEvent.mozInputSource")}} {{non-standard_inline()}}&nbsp;{{gecko_minversion_inline("2.0")}} {{readonlyinline}}</dt>
 <dd>
  <p>The type of device that generated the event (one of the <code>MOZ_SOURCE_*</code> constants listed below).</p>
  <p>This lets you, for example, determine whether a mouse event was generated by an actual mouse or by a touch event (which might affect the degree of accuracy with which you interpret the coordinates associated with the event).</p>
 </dd>
</dl>
<h2 id="Methods">Methods</h2>
<dl>
 <dt>
  {{domxref("MouseEvent.getModifierState()")}} {{dom_level("3")}} {{gecko_minversion_inline("15.0")}}</dt>
 <dd>
  Returns the current state of the specified modifier key. See the {{domxref("KeyboardEvent", "KeyboardEvent", "getModifierState()")}} documentation for details.</dd>
</dl>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('DOM2 Events','#Events-MouseEvent','MouseEvent')}}</td>
   <td>{{Spec2('DOM2 Events')}}</td>
   <td>&nbsp;</td>
  </tr>
  <tr>
   <td>{{SpecName('DOM3 Events','#events-mouseevents','MouseEvent')}}</td>
   <td>{{Spec2('DOM3 Events')}}</td>
   <td>&nbsp;</td>
  </tr>
 </tbody>
</table>
<h2 id="Browser_compatibility" name="Browser_compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
 <table class="compat-table">
  <tbody>
   <tr>
    <th>Feature</th>
    <th>Firefox (Gecko)</th>
    <th>Chrome</th>
    <th>Internet Explorer</th>
    <th>Opera</th>
    <th>Safari</th>
   </tr>
   <tr>
    <td>Basic support</td>
    <td>{{CompatVersionUnknown()}}</td>
    <td>{{CompatVersionUnknown()}}</td>
    <td>{{CompatVersionUnknown()}}</td>
    <td>{{CompatVersionUnknown()}}</td>
    <td>{{CompatVersionUnknown()}}</td>
   </tr>
   <tr>
    <td>{{domxref("MouseEvent.movementX","movementX")}}<br />
     {{domxref("MouseEvent.movementY","movementY")}}</td>
    <td>{{CompatVersionUnknown()}} {{property_prefix("moz")}}</td>
    <td>{{CompatVersionUnknown()}} {{property_prefix("webkit")}}</td>
    <td>{{ CompatUnknown() }}</td>
    <td>{{ CompatUnknown() }}</td>
    <td>{{ CompatUnknown() }}</td>
   </tr>
  </tbody>
 </table>
</div>
<div id="compat-mobile">
 <table class="compat-table">
  <tbody>
   <tr>
    <th>Feature</th>
    <th>Firefox Mobile (Gecko)</th>
    <th>Android</th>
    <th>IE Mobile</th>
    <th>Opera Mobile</th>
    <th>Safari Mobile</th>
   </tr>
   <tr>
    <td>Basic support</td>
    <td>{{ CompatUnknown() }}</td>
    <td>{{ CompatUnknown() }}</td>
    <td>{{ CompatUnknown() }}</td>
    <td>{{ CompatUnknown() }}</td>
    <td>{{ CompatUnknown() }}</td>
   </tr>
  </tbody>
 </table>
</div>
<h2 id="Gecko_notes">Gecko notes</h2>
<div>
 <p>Gecko supports the {{domxref("MouseEvent.buttons","buttons")}} attribute on Windows, Linux (GTK) and Mac with the following restriction:</p>
 <ul>
  <li>On Windows, if user installed a mouse driver and its utility software which can customize button actions (e.g., IntelliPoint and SetPoint), the Middle (wheel) button, 4th button and 5th button may not be set actually even when they're pressed.</li>
  <li>On Linux (GTK), 4th button and 5th button are not supported. And also, mouseup event always have the releasing button information in this attribute value.</li>
  <li>On Mac OS X 10.5, buttons attribute always returns 0 because there is no platform API for implementing this feature.</li>
 </ul>
 <h3 id="Specific_constants">Specific constants</h3>
 <p>The possible values for <a href="#mozInputSource"><code>MouseEvent.mozInputSource</code></a> are listed in the following table. They are available as properties on the <code>MouseEvent</code> interface (e.g. <code>MouseEvent.MOZ_SOURCE_UNKNOWN</code>).</p>
 <table class="standard-table">
  <tbody>
   <tr>
    <th>Constant name</th>
    <th>Value</th>
    <th>Desription</th>
   </tr>
   <tr>
    <td><code>MOZ_SOURCE_UNKNOWN</code></td>
    <td>0</td>
    <td>The input device is unknown.</td>
   </tr>
   <tr>
    <td><code>MOZ_SOURCE_MOUSE</code></td>
    <td>1</td>
    <td>The event was generated by a mouse (or mouse-like device).</td>
   </tr>
   <tr>
    <td><code>MOZ_SOURCE_PEN</code></td>
    <td>2</td>
    <td>The event was generated by a pen on a tablet.</td>
   </tr>
   <tr>
    <td><code>MOZ_SOURCE_ERASER</code></td>
    <td>3</td>
    <td>The event was generated by an eraser on a tablet.</td>
   </tr>
   <tr>
    <td><code>MOZ_SOURCE_CURSOR</code></td>
    <td>4</td>
    <td>The event was generated by a cursor.</td>
   </tr>
   <tr>
    <td><code>MOZ_SOURCE_TOUCH</code></td>
    <td>5</td>
    <td>The event was generated on a touch interface.</td>
   </tr>
   <tr>
    <td><code>MOZ_SOURCE_KEYBOARD</code></td>
    <td>6</td>
    <td>The event was generated by a keyboard.</td>
   </tr>
  </tbody>
 </table>
</div>
<p>&nbsp;</p>
Revert to this revision