From 410ca45d552c63d7d20bca3322f17878dabd0d02 Mon Sep 17 00:00:00 2001 From: Allan Bonadio Date: Sat, 23 Nov 2024 23:17:16 -0800 Subject: [PATCH] added more info about pointer/mouse analogy and differences. Added details that were missing. --- files/en-us/web/api/element/mousedown_event/index.md | 3 +++ files/en-us/web/api/element/mouseenter_event/index.md | 3 ++- files/en-us/web/api/element/mouseleave_event/index.md | 2 +- files/en-us/web/api/element/mousemove_event/index.md | 2 ++ files/en-us/web/api/element/mouseout_event/index.md | 2 ++ files/en-us/web/api/element/mouseover_event/index.md | 2 ++ files/en-us/web/api/element/mouseup_event/index.md | 6 ++++++ files/en-us/web/api/element/pointerdown_event/index.md | 3 +++ files/en-us/web/api/element/pointerenter_event/index.md | 2 +- files/en-us/web/api/element/pointerleave_event/index.md | 2 +- files/en-us/web/api/element/pointermove_event/index.md | 4 +++- files/en-us/web/api/element/pointerout_event/index.md | 2 ++ files/en-us/web/api/element/pointerover_event/index.md | 2 ++ files/en-us/web/api/element/pointerup_event/index.md | 3 +++ files/en-us/web/api/mouseevent/mouseevent/index.md | 2 ++ 15 files changed, 35 insertions(+), 5 deletions(-) diff --git a/files/en-us/web/api/element/mousedown_event/index.md b/files/en-us/web/api/element/mousedown_event/index.md index 67e4817b2f57d48..c08025feb3013f2 100644 --- a/files/en-us/web/api/element/mousedown_event/index.md +++ b/files/en-us/web/api/element/mousedown_event/index.md @@ -13,6 +13,9 @@ The **`mousedown`** event is fired at an {{domxref("Element")}} when a pointing > [!NOTE] > This differs from the {{domxref("Element/click_event", "click")}} event in that `click` is fired after a full click action occurs; that is, the mouse button is pressed and released while the pointer remains inside the same element. `mousedown` is fired the moment the button is initially pressed. +> [!NOTE] +> This behavior is different from {{domxref("Element/pointerdown_event", "pointerdown")}} events. MouseDown events fire whenever any button on a mouse is pressed down. `pointerdown` events fire only upon the first button press; subsequent button presses don't fire `pointerdown` events. + ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. diff --git a/files/en-us/web/api/element/mouseenter_event/index.md b/files/en-us/web/api/element/mouseenter_event/index.md index 7f125aabaf4eb53..45ca59be68fb254 100644 --- a/files/en-us/web/api/element/mouseenter_event/index.md +++ b/files/en-us/web/api/element/mouseenter_event/index.md @@ -82,10 +82,11 @@ _This interface also inherits properties of its parents, {{domxref("UIEvent")}} ## Usage notes -Though similar to {{domxref("Element/mouseover_event", "mouseover")}}, `mouseenter` differs in that it doesn't [bubble](/en-US/docs/Web/API/Event/bubbles) and it isn't sent to any descendants when the pointer is moved from one of its descendants' physical space to its own physical space. +Though similar to {{domxref("Element/mouseover_event", "mouseover")}}, `mouseenter` differs in that it doesn't [bubble](/en-US/docs/Web/API/Event/bubbles) and it isn't sent to any descendants when the pointer is moved from one of its descendants' physical space to its own physical space. Other than that, enter and over events for the same situation are dispatched at the same time, if appropriate. ### Behavior of `mouseenter` events +This describes the mouseenter events received by each of four concentric divs with no padding or margin, so the events all happen at the same time: ![Mouseenter behavior diagram](mouseenter.png) One `mouseenter` event is sent to each element of the hierarchy when entering them. Here 4 events are sent to the four elements of the hierarchy when the pointer reaches the text. diff --git a/files/en-us/web/api/element/mouseleave_event/index.md b/files/en-us/web/api/element/mouseleave_event/index.md index a7ea6f2a31e62ee..00f3341dd8ae799 100644 --- a/files/en-us/web/api/element/mouseleave_event/index.md +++ b/files/en-us/web/api/element/mouseleave_event/index.md @@ -10,7 +10,7 @@ browser-compat: api.Element.mouseleave_event The **`mouseleave`** event is fired at an {{domxref("Element")}} when the cursor of a pointing device (usually a mouse) is moved out of it. -`mouseleave` and {{domxref("Element/mouseout_event", "mouseout")}} are similar but differ in that `mouseleave` does not bubble and `mouseout` does. This means that `mouseleave` is fired when the pointer has exited the element _and_ all of its descendants, whereas `mouseout` is fired when the pointer leaves the element _or_ leaves one of the element's descendants (even if the pointer is still within the element). +`mouseleave` and {{domxref("Element/mouseout_event", "mouseout")}} are similar but differ in that `mouseleave` does not bubble and `mouseout` does. This means that `mouseleave` is fired when the pointer has exited the element _and_ all of its descendants, whereas `mouseout` is fired when the pointer leaves the element _or_ leaves one of the element's descendants (even if the pointer is still within the element). Other than that, leave and out events for the same situation are dispatched at the same time, if appropriate. The `mouseleave` and `mouseout` events will not be triggered when the element is replaced or removed from the DOM. diff --git a/files/en-us/web/api/element/mousemove_event/index.md b/files/en-us/web/api/element/mousemove_event/index.md index f5071eaabde644c..d1ada7feab3b63c 100644 --- a/files/en-us/web/api/element/mousemove_event/index.md +++ b/files/en-us/web/api/element/mousemove_event/index.md @@ -10,6 +10,8 @@ browser-compat: api.Element.mousemove_event The `mousemove` event is fired at an element when a pointing device (usually a mouse) is moved while the cursor's hotspot is inside it. +These events happen whether or not any mouse buttons are pressed. They can come at 100 events per second or faster, but the actual rate depends on how fast the user moves the mouse, how fast the machine is, what other tasks and processes are happening, etc. + ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. diff --git a/files/en-us/web/api/element/mouseout_event/index.md b/files/en-us/web/api/element/mouseout_event/index.md index 2dc4f6dec4b6171..f62d8b2b601c40a 100644 --- a/files/en-us/web/api/element/mouseout_event/index.md +++ b/files/en-us/web/api/element/mouseout_event/index.md @@ -12,6 +12,8 @@ The **`mouseout`** event is fired at an {{domxref("Element")}} when a pointing d `mouseout` is also delivered to an element if the cursor enters a child element, because the child element obscures the visible area of the element. +If the target element has elements inside, `mouseout` and `mouseover` events will fire as the mouse moves over the boundaries of these elemenets. For instance, `mouseout` will fire on the parent as the mouse moves into one of the child elements, because the mouse is not directly over the parent anymore. Because it gets complicated, usually everybody listens for `mouseenter` and `mouseleave` events instead, because those events don't have that problem. `mouseout` and `mouseover` were standardized first, before developers realized this problem. Years later, the enter and leave events were added to the dom. Out and over events still work, but are rarely used. + ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. diff --git a/files/en-us/web/api/element/mouseover_event/index.md b/files/en-us/web/api/element/mouseover_event/index.md index 8108b0063b7b441..adfb95705adec75 100644 --- a/files/en-us/web/api/element/mouseover_event/index.md +++ b/files/en-us/web/api/element/mouseover_event/index.md @@ -10,6 +10,8 @@ browser-compat: api.Element.mouseover_event The **`mouseover`** event is fired at an {{domxref("Element")}} when a pointing device (such as a mouse or trackpad) is used to move the cursor onto the element or one of its child elements. +If the target element has elements inside, `mouseover` and `mouseout` events will fire as the mouse moves over the boundaries of these elemenets. For instance, `mouseout` will fire on the parent as the mouse moves into one of the child elements, because the mouse is not directly over the parent anymore. Because it gets complicated, usually everybody listens for `mouseenter` and `mouseleave` events instead, because those events don't have that problem. `mouseout` and `mouseover` were standardized first, before developers realized this problem. Years later, the enter and leave events were added to the dom. Out and over events still work, but are rarely used. + ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. diff --git a/files/en-us/web/api/element/mouseup_event/index.md b/files/en-us/web/api/element/mouseup_event/index.md index 4f0fc4c21522afe..1b2c19b91f57826 100644 --- a/files/en-us/web/api/element/mouseup_event/index.md +++ b/files/en-us/web/api/element/mouseup_event/index.md @@ -12,6 +12,12 @@ The **`mouseup`** event is fired at an {{domxref("Element")}} when a button on a `mouseup` events are the counterpoint to {{domxref("Element.mousedown_event", "mousedown")}} events. +> [!NOTE] +> This behavior is different from {{domxref("Element/pointerdown_event", "pointerdown")}} events. MouseDown events fire whenever any button on a mouse is pressed down. `pointerdown` events fire only upon the first button press; subsequent button presses don't fire `pointerdown` events. + +> [!NOTE] +> This behavior is different from {{domxref("Element/pointerup_event", "pointerup")}} events. `mouseup` events fire whenever any button on a mouse is released. `pointerup` events fire only upon the last button release; previous button releases, while other buttons are held down, don't fire `pointerup` events. + ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. diff --git a/files/en-us/web/api/element/pointerdown_event/index.md b/files/en-us/web/api/element/pointerdown_event/index.md index c3617c12b3a6732..92760126ff81489 100644 --- a/files/en-us/web/api/element/pointerdown_event/index.md +++ b/files/en-us/web/api/element/pointerdown_event/index.md @@ -10,6 +10,9 @@ browser-compat: api.Element.pointerdown_event The `pointerdown` event is fired when a pointer becomes active. For mouse, it is fired when the device transitions from no buttons pressed to at least one button pressed. For touch, it is fired when physical contact is made with the digitizer. For pen, it is fired when the stylus makes physical contact with the digitizer. +> [!NOTE] +> This behavior is different from {{domxref("element/mousedown_event", "mousedown")}} events. `mousedown` events fire whenever any button on a mouse is pressed down. `pointerdown` events fire only upon the first button press; subsequent button presses don't fire `pointerdown` events. + > [!NOTE] > For touchscreen browsers that allow [direct manipulation](https://w3c.github.io/pointerevents/#dfn-direct-manipulation), a `pointerdown` event triggers [implicit pointer capture](https://w3c.github.io/pointerevents/#dfn-implicit-pointer-capture), which causes the target to capture all subsequent pointer events as if they were occurring over the capturing target. Accordingly, `pointerover`, `pointerenter`, `pointerleave`, and `pointerout` **will not fire** as long as this capture is set. The capture can be released manually by calling {{domxref('element.releasePointerCapture')}} on the target element, or it will be implicitly released after a `pointerup` or `pointercancel` event. diff --git a/files/en-us/web/api/element/pointerenter_event/index.md b/files/en-us/web/api/element/pointerenter_event/index.md index 4781067b9d46db6..963362bf3176ef7 100644 --- a/files/en-us/web/api/element/pointerenter_event/index.md +++ b/files/en-us/web/api/element/pointerenter_event/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.pointerenter_event {{APIRef}} -The `pointerenter` event fires when a pointing device is moved into the hit test boundaries of an element or one of its descendants, including as a result of a {{domxref("Element/pointerdown_event", "pointerdown")}} event from a device that does not support hover (see {{domxref("Element/pointerdown_event", "pointerdown")}}). +The `pointerenter` event fires when a pointing device is moved into the hit test boundaries of an element or one of its descendants, including as a result of a {{domxref("Element/pointerdown_event", "pointerdown")}} event from a device that does not support hover (see {{domxref("Element/pointerdown_event", "pointerdown")}}). Otherwise, `pointerenter` works the same as {{domxref("Element/mouseenter_event", "mouseenter")}}, and are dispatched at the same time. They are dispatched at the same time, also, as {{domxref("Element/mouseover_event", "mouseover")}} and {{domxref("Element/pointerover_event", "pointerover")}} events, if appropriate. ## Syntax diff --git a/files/en-us/web/api/element/pointerleave_event/index.md b/files/en-us/web/api/element/pointerleave_event/index.md index 7503c83b948ade8..47cc5293e481348 100644 --- a/files/en-us/web/api/element/pointerleave_event/index.md +++ b/files/en-us/web/api/element/pointerleave_event/index.md @@ -8,7 +8,7 @@ browser-compat: api.Element.pointerleave_event {{APIRef}} -The `pointerleave` event is fired when a pointing device is moved out of the hit test boundaries of an element. For pen devices, this event is fired when the stylus leaves the hover range detectable by the digitizer. +The `pointerleave` event is fired when a pointing device is moved out of the hit test boundaries of an element. For pen devices, this event is fired when the stylus leaves the hover range detectable by the digitizer. Otherwise, `pointerleave` works the same as {{domxref("Element/mouseleave_event", "mouseleave")}}, and are dispatched at the same time. They are dispatched at the same time, also, as {{domxref("Element/mouseout_event", "mouseout")}} and {{domxref("Element/pointerout_event", "pointerout")}} events, if appropriate. ## Syntax diff --git a/files/en-us/web/api/element/pointermove_event/index.md b/files/en-us/web/api/element/pointermove_event/index.md index 35c979570a5312d..421631ca22427e2 100644 --- a/files/en-us/web/api/element/pointermove_event/index.md +++ b/files/en-us/web/api/element/pointermove_event/index.md @@ -8,7 +8,9 @@ browser-compat: api.Element.pointermove_event {{APIRef}} -The `pointermove` event is fired when a pointer changes coordinates, and the pointer has not been [canceled](/en-US/docs/Web/API/Element/pointercancel_event) by a browser [touch-action](/en-US/docs/Web/CSS/touch-action). +The `pointermove` event is fired when a pointer changes coordinates, and the pointer has not been [canceled](/en-US/docs/Web/API/Element/pointercancel_event) by a browser [touch-action](/en-US/docs/Web/CSS/touch-action). It's very similar to the {{domxref("Element/mousemove_event", "mousemove")}} event, but with more features. + +These events happen whether or not any pointer buttons are pressed. They can come at 100 events per second or faster, but the actual rate depends on how fast the user moves the mouse, how fast the machine is, what other tasks and processes are happening, etc. ## Syntax diff --git a/files/en-us/web/api/element/pointerout_event/index.md b/files/en-us/web/api/element/pointerout_event/index.md index c8016f2f18cc941..4a245b9d8d605fe 100644 --- a/files/en-us/web/api/element/pointerout_event/index.md +++ b/files/en-us/web/api/element/pointerout_event/index.md @@ -10,6 +10,8 @@ browser-compat: api.Element.pointerout_event The `pointerout` event is fired for several reasons including: pointing device is moved out of the _hit test_ boundaries of an element; firing the {{domxref("Element/pointerup_event", "pointerup")}} event for a device that does not support hover (see {{domxref("Element/pointerup_event", "pointerup")}}); after firing the {{domxref("Element/pointercancel_event", "pointercancel")}} event (see {{domxref("Element/pointercancel_event", "pointercancel")}}); when a pen stylus leaves the hover range detectable by the digitizer. +`pointerover` and `pointerout` events have the same problems as {{domxref("Element/mouseover_event", "mouseover")}} and {{domxref("Element/mouseout_event", "mouseout")}}. {{domxref("Element/pointerenter_event", "pointerenter")}} and {{domxref("Element/pointerleave_event", "pointerleave")}} are probably what you should listen for instead. + ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. diff --git a/files/en-us/web/api/element/pointerover_event/index.md b/files/en-us/web/api/element/pointerover_event/index.md index 6a226853d29d556..ca6c333a150456a 100644 --- a/files/en-us/web/api/element/pointerover_event/index.md +++ b/files/en-us/web/api/element/pointerover_event/index.md @@ -10,6 +10,8 @@ browser-compat: api.Element.pointerover_event The `pointerover` event is fired when a pointing device is moved into an element's hit test boundaries. +`pointerover` and `pointerout` events have the same problems as {{domxref("Element/mouseover_event", "mouseover")}} and {{domxref("Element/mouseout_event", "mouseout")}}. {{domxref("Element/pointerenter_event", "pointerenter")}} and {{domxref("Element/pointerleave_event", "pointerleave")}} are probably what you should listen for instead. + ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. diff --git a/files/en-us/web/api/element/pointerup_event/index.md b/files/en-us/web/api/element/pointerup_event/index.md index 7fc62a2b31e9d77..003adf53373d7ce 100644 --- a/files/en-us/web/api/element/pointerup_event/index.md +++ b/files/en-us/web/api/element/pointerup_event/index.md @@ -10,6 +10,9 @@ browser-compat: api.Element.pointerup_event The `pointerup` event is fired when a pointer is no longer active. Remember that it is possible to get a [`pointercancel`](/en-US/docs/Web/API/Element/pointercancel_event) event instead. +> [!NOTE] +> This behavior is different from {{domxref("Element/mouseup_event", "mouseup")}} events. `mouseup` events fire whenever any button on a mouse is released. `pointerup` events fire only upon the last button release; previous button releases, while other buttons are held down, don't fire `pointerup` events. + ## Syntax Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. diff --git a/files/en-us/web/api/mouseevent/mouseevent/index.md b/files/en-us/web/api/mouseevent/mouseevent/index.md index 3c9b8001cdd30d9..76293a0b5e6e1fd 100644 --- a/files/en-us/web/api/mouseevent/mouseevent/index.md +++ b/files/en-us/web/api/mouseevent/mouseevent/index.md @@ -89,3 +89,5 @@ new MouseEvent(type, options) ## See also - {{domxref("MouseEvent")}}, the interface of the objects it constructs. +- {{domxref("PointerEvent")}}, similar, but with more features, like multi-touch. +- {{domxref("Pointer_Events")}}, discussion of pointer & mouse events and their correspondence.