mouse & pointer event pages updates #36993

allan-bonadio · 2024-11-27T01:28:31Z

Description

In the docs for the various MouseEvents and PointerEvents, rarely do either mention the other. I added cross links, and also some discussions in various event pages how the moouse/pointer event differs from the corresponding pointer/mouse event.

I added notes to the over/out events, explaining how they're rarely used, and one should use the enter/leave events. (The details were explained already, but nowhere did I find it specifically say to not use over/out.)

I also did some other updates that I thought were needed.

Motivation

I only recently learned about pointer events, despite being a web developer for 10+ years. Maybe a few more links between pointer and mouse events would have helped me find out about them.

I saw a question recently about over/out events on StackOverflow, and sure enough, the questioner was using over/out when they should have used enter/leave. Probably others are in the same situation; sometimes you have to come out and say it.

Additional details

The pointer events
article introduction describes the situation pretty well.
(Do not confuse with the PointerEvent article, which describes the superclass.)

Related issues and pull requests

Fixes #27878

github-actions · 2024-11-27T01:30:32Z

Preview URLs (15 pages)

(comment last updated: 2025-01-08 04:49:52)

…tails that were missing.

wbamberg · 2024-12-25T04:43:19Z

Sorry to be slow with this @allan-bonadio , I will get to it (but I think it might be a bit complicated).

allan-bonadio · 2024-12-26T03:54:59Z

thanks @wbamberg I was wondering if I had bad breath or something 😀

I've got a few more PRs coming, is there a good place to ask for volunteer reviewers? Or I just sit tight and wait to get picked up?

allan-bonadio · 2024-12-26T03:57:06Z

This PR is mostly addition of text, stuff I've learned over the years. Including my own experimentation.

wbamberg · 2024-12-26T04:36:11Z

I've got a few more PRs coming, is there a good place to ask for volunteer reviewers? Or I just sit tight and wait to get picked up?

They will just get auto-assigned. How quickly they get reviewed mostly depends on how easy the review is :).

allan-bonadio · 2025-01-03T01:41:34Z

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 is NOT the same as the last one!

allan-bonadio · 2025-01-03T01:42:37Z

files/en-us/web/api/element/mousedown_event/index.md

@@ -105,3 +108,4 @@ See [`mousemove` event](/en-US/docs/Web/API/Element/mousemove_event#examples) fo
 - {{domxref("Element/mouseenter_event", "mouseenter")}}
 - {{domxref("Element/mouseleave_event", "mouseleave")}}
 - {{domxref("Element/contextmenu_event", "contextmenu")}}
+- {{domxref("Element/pointerdown_event", "pointerdown")}}


These crosslinks between mouse and pointer events are the original reason I started on this project.

allan-bonadio · 2025-01-03T01:44:33Z

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.



just an observation I had ^

allan-bonadio · 2025-01-03T01:45:57Z

files/en-us/web/api/element/mouseenter_event/index.md


 ### 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:


This example just looked like a box, but in fact it was four concentric boxes. There was no explanation.

allan-bonadio · 2025-01-03T01:49:17Z

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.


This is based on my own experience working with move events over more than a decade. If you set a print stmt at a move event handler, it might fill up your console easily, so be ready.

allan-bonadio · 2025-01-03T01:51:04Z

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.


none of this documentation ever came right out and said "don't use over and out; use enter and leave instead". But that's what everybody needs to know, so I included it here.

allan-bonadio · 2025-01-03T01:53:46Z

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]


analogous to pointerup; same text

allan-bonadio · 2025-01-03T01:56:06Z

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.


there was not enough assurance to the reader that these do about the same thing. I added that.

allan-bonadio · 2025-01-03T01:56:42Z

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.


same text as enter

allan-bonadio · 2025-01-03T01:57:41Z

files/en-us/web/api/element/pointermove_event/index.md

-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.


same comment as mousemove event

allan-bonadio · 2025-01-03T01:58:31Z

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.


same as with pointer out event and mouse over event

allan-bonadio · 2025-01-03T01:58:45Z

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.


allan-bonadio · 2025-01-03T01:59:13Z

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.


allan-bonadio · 2025-01-03T02:07:52Z

I added some comments, see above, trying to streamline this process.

There's a LOT of repetition and duplicated text in these articles; pointer events work like mouse events, and complementary events ( Like down/up, enter/leave, over/out) have complementary text in their articles. So if a comment says 'same' it means that the paragraph is the same as the same paragraph in one or more analogous articles, which are also part of this PR.

allan-bonadio requested a review from a team as a code owner November 27, 2024 01:28

allan-bonadio requested review from wbamberg and removed request for a team November 27, 2024 01:28

github-actions bot added Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed labels Nov 27, 2024

Allan Bonadio added 3 commits December 15, 2024 23:02

Added cross-links between individual mouse events and pointer events

2c7952a

added more info about pointer/mouse analogy and differences. Added de…

410ca45

…tails that were missing.

a few typos

4b09459

allan-bonadio force-pushed the mousePointerCrosslinks branch from b1f246a to 4b09459 Compare December 16, 2024 07:02

allan-bonadio added 2 commits December 15, 2024 23:50

Merge branch 'main' into mousePointerCrosslinks

5b50a7b

Merge branch 'mdn:main' into mousePointerCrosslinks

98d6a09

Merge branch 'main' into mousePointerCrosslinks

5e89d97

allan-bonadio commented Jan 3, 2025

View reviewed changes

Merge branch 'main' into mousePointerCrosslinks

abe8057

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

mouse & pointer event pages updates #36993

mouse & pointer event pages updates #36993

allan-bonadio commented Nov 27, 2024

github-actions bot commented Nov 27, 2024 •

edited

Loading

wbamberg commented Dec 25, 2024

allan-bonadio commented Dec 26, 2024

allan-bonadio commented Dec 26, 2024

wbamberg commented Dec 26, 2024

allan-bonadio Jan 3, 2025

allan-bonadio Jan 3, 2025

allan-bonadio Jan 3, 2025

allan-bonadio Jan 3, 2025

allan-bonadio Jan 3, 2025

allan-bonadio Jan 3, 2025

allan-bonadio Jan 3, 2025

allan-bonadio Jan 3, 2025

allan-bonadio Jan 3, 2025

allan-bonadio Jan 3, 2025

allan-bonadio Jan 3, 2025

allan-bonadio Jan 3, 2025

allan-bonadio Jan 3, 2025

allan-bonadio commented Jan 3, 2025


		### 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:

		@@ -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.

		@@ -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.

		@@ -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]

		@@ -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.

		@@ -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.

mouse & pointer event pages updates #36993

Are you sure you want to change the base?

mouse & pointer event pages updates #36993

Conversation

allan-bonadio commented Nov 27, 2024

Description

Motivation

Additional details

Related issues and pull requests

github-actions bot commented Nov 27, 2024 • edited Loading

wbamberg commented Dec 25, 2024

allan-bonadio commented Dec 26, 2024

allan-bonadio commented Dec 26, 2024

wbamberg commented Dec 26, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

allan-bonadio commented Jan 3, 2025

github-actions bot commented Nov 27, 2024 •

edited

Loading