mouse & pointer event pages updates

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.
@@ -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")}}

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.
 
@@ -187,3 +188,4 @@ function addListItem(text) {
 - {{domxref("Element/mouseout_event", "mouseout")}}
 - {{domxref("Element/mouseleave_event", "mouseleave")}}
 - {{domxref("Element/contextmenu_event", "contextmenu")}}
+- {{domxref("Element/pointerenter_event", "pointerenter")}}

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, because of bubbling (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.
 
@@ -185,3 +185,4 @@ function addListItem(text) {
 - {{domxref("Element/mouseout_event", "mouseout")}}
 - {{domxref("Element/mouseenter_event", "mouseenter")}}
 - {{domxref("Element/contextmenu_event", "contextmenu")}}
+- {{domxref("Element/pointerleave_event", "pointerleave")}}

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.
@@ -181,3 +183,4 @@ function drawLine(context, x1, y1, x2, y2) {
 - {{domxref("Element/mouseenter_event", "mouseenter")}}
 - {{domxref("Element/mouseleave_event", "mouseleave")}}
 - {{domxref("Element/contextmenu_event", "contextmenu")}}
+- {{domxref("Element/pointermove_event", "pointermove")}}

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.
@@ -161,3 +163,4 @@ test.addEventListener(
 - {{domxref("Element/mouseenter_event", "mouseenter")}}
 - {{domxref("Element/mouseleave_event", "mouseleave")}}
 - {{domxref("Element/contextmenu_event", "contextmenu")}}
+- {{domxref("Element/pointerout_event", "pointerout")}}

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.
@@ -154,3 +156,4 @@ test.addEventListener(
 - {{domxref("Element/mouseenter_event", "mouseenter")}}
 - {{domxref("Element/mouseleave_event", "mouseleave")}}
 - {{domxref("Element/contextmenu_event", "contextmenu")}}
+- {{domxref("Element/pointerover_event", "pointerover")}}

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

@@ -12,6 +12,9 @@ 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/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.
@@ -104,3 +107,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/pointerup_event", "pointerup")}}

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.
 
@@ -104,3 +107,4 @@ para.onpointerdown = (event) => {
   - {{domxref('Element/pointerout_event', 'pointerout')}}
   - {{domxref('Element/pointerleave_event', 'pointerleave')}}
   - {{domxref('Element/pointerrawupdate_event', 'pointerrawupdate')}}
+  - {{domxref("Element/mousedown_event", "mousedown")}}

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
 
@@ -101,3 +101,4 @@ para.onpointerenter = (event) => {
   - {{domxref('Element/pointerout_event', 'pointerout')}}
   - {{domxref('Element/pointerleave_event', 'pointerleave')}}
   - {{domxref('Element/pointerrawupdate_event', 'pointerrawupdate')}}
+  - {{domxref("Element/mouseenter_event", "mouseenter")}}

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
 
@@ -101,3 +101,4 @@ para.onpointerleave = (event) => {
   - {{domxref('Element/pointercancel_event', 'pointercancel')}}
   - {{domxref('Element/pointerout_event', 'pointerout')}}
   - {{domxref('Element/pointerrawupdate_event', 'pointerrawupdate')}}
+  - {{domxref("Element/mouseleave_event", "mouseleave")}}

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
 
@@ -105,3 +107,4 @@ para.onpointermove = (event) => {
   - {{domxref('Element/pointerout_event', 'pointerout')}}
   - {{domxref('Element/pointerleave_event', 'pointerleave')}}
   - {{domxref('Element/pointerrawupdate_event', 'pointerrawupdate')}}
+  - {{domxref("Element/mousemove_event", "mousemove")}}

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.
@@ -101,3 +103,4 @@ para.onpointerout = (event) => {
   - {{domxref('Element/pointercancel_event', 'pointercancel')}}
   - {{domxref('Element/pointerleave_event', 'pointerleave')}}
   - {{domxref('Element/pointerrawupdate_event', 'pointerrawupdate')}}
+  - {{domxref("Element/mouseout_event", "mouseout")}}

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.
@@ -101,3 +103,4 @@ para.onpointerover = (event) => {
   - {{domxref('Element/pointerout_event', 'pointerout')}}
   - {{domxref('Element/pointerleave_event', 'pointerleave')}}
   - {{domxref('Element/pointerrawupdate_event', 'pointerrawupdate')}}
+  - {{domxref("Element/mouseover_event", "mouseover")}}

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.
@@ -101,3 +104,4 @@ para.onpointerup = (event) => {
   - {{domxref('Element/pointerout_event', 'pointerout')}}
   - {{domxref('Element/pointerleave_event', 'pointerleave')}}
   - {{domxref('Element/pointerrawupdate_event', 'pointerrawupdate')}}
+  - {{domxref("Element/mouseup_event", "mouseup")}}

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.