mouse & pointer event pages updates #36993
Conversation
github-actions
bot
added
Content:WebAPI
allan-bonadio
force-pushed
the
mousePointerCrosslinks
branch
from
b1f246a to
4b09459
Compare
|
Sorry to be slow with this @allan-bonadio , I will get to it (but I think it might be a bit complicated). |
|
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? |
|
This PR is mostly addition of text, stuff I've learned over the years. Including my own experimentation. |
They will just get auto-assigned. How quickly they get reviewed mostly depends on how easy the review is :). |
| @@ -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] | |||
There was a problem hiding this comment.
analogous to pointerup; same text
| @@ -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 a problem hiding this comment.
there was not enough assurance to the reader that these do about the same thing. I added that.
| @@ -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. | |||
There was a problem hiding this comment.
same text as enter
| 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. |
There was a problem hiding this comment.
same comment as mousemove event
| @@ -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. | |||
There was a problem hiding this comment.
same as with pointer out event and mouse over event
| @@ -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. | |||
| @@ -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. | |||
|
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. |
|
I went through, adding comments as my way of explaining why I was making individual changes. They all got "Resolve Conversation" buttons. I clicked the Resolve button on some of them, but then the comment got hidden; although you can click on "show resolved" toward the right to see the comment. Not sure if I should have resolved those. I used a similar git-management site once at a job, where line-by-line comments were just there to add explanations with no 'resolve' buttons. This is different. Sorry. |
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 eventsarticle introduction describes the situation pretty well.
(Do not confuse with the PointerEvent article, which describes the superclass.)
Related issues and pull requests
Fixes #27878