Pointer Events

WebIDL[Exposed=Window]
interface MouseEvent : UIEvent {
	constructor(DOMString type, optional MouseEventInit eventInitDict = {});
	readonly attribute long screenX;
	readonly attribute long screenY;
	readonly attribute long clientX;
	readonly attribute long clientY;
	readonly attribute long layerX;
	readonly attribute long layerY;
	readonly attribute boolean ctrlKey;
	readonly attribute boolean shiftKey;
	readonly attribute boolean altKey;
	readonly attribute boolean metaKey;
	readonly attribute short button;
	readonly attribute unsigned short buttons;
	readonly attribute EventTarget? relatedTarget;
	boolean getModifierState(DOMString keyArg);
};

screenX

The horizontal coordinate at which the event occurred relative to the origin of the screen coordinate system.

The un-initialized value of this attribute MUST be 0 .

screenY

The vertical coordinate at which the event occurred relative to the origin of the screen coordinate system.

The un-initialized value of this attribute MUST be 0 .

clientX

The horizontal coordinate at which the event occurred relative to the viewport associated with the event.

The un-initialized value of this attribute MUST be 0 .

clientY

The vertical coordinate at which the event occurred relative to the viewport associated with the event.

The un-initialized value of this attribute MUST be 0 .

layerX

The horizontal offset from the nearest ancestor element which is a stacking context , is positioned , or paints in the positioned phase when painting a stacking context .

The un-initialized value of this attribute MUST be 0 .

layerY

The vertical offset from the nearest ancestor element which is a stacking context , is positioned , or paints in the positioned phase when painting a stacking context .

The un-initialized value of this attribute MUST be 0 .

ctrlKey

Refer to the KeyboardEvent 's ctrlKey attribute.

The un-initialized value of this attribute MUST be false .

shiftKey

Refer to the KeyboardEvent 's shiftKey attribute.

The un-initialized value of this attribute MUST be false .

altKey

Refer to the KeyboardEvent 's altKey attribute.

The un-initialized value of this attribute MUST be false .

metaKey

Refer to the KeyboardEvent 's metaKey attribute.

The un-initialized value of this attribute MUST be false .

button

During mouse events caused by the depression or release of a mouse button, button MUST be used to indicate which pointer device button changed state.

The value of the button attribute MUST be as follows:

• 0 MUST indicate the primary button of the device (in general, the left button or the only button on single-button devices, used to activate a user interface control or select text) or the un-initialized value.
• 1 MUST indicate the auxiliary button (in general, the middle button, often combined with a mouse wheel).
• 2 MUST indicate the secondary button (in general, the right button, often used to display a context menu).
• 3 MUST indicate the X1 (back) button.
• 4 MUST indicate the X2 (forward) button.

Some pointing devices provide or simulate more button states, and values higher than 2 or lower than 0 MAY be used to represent such buttons.

Note

The value of button is not updated for events not caused by the depression/release of a mouse button. In these scenarios, take care not to interpret the value 0 as the left button, but rather as the default value.

Note

Some default actions related to events such as mousedown and mouseup depend on the specific mouse button in use.

The un-initialized value of this attribute MUST be 0 .

buttons

During any mouse events, buttons MUST be used to indicate which combination of mouse buttons are currently being pressed, expressed as a bitmask.

Note

Though similarly named, the values for the buttons attribute and the button attribute are very different. The value of button is assumed to be valid during mousedown / mouseup event handlers, whereas the buttons attribute reflects the state of the mouse's buttons for any trusted MouseEvent object (while it is being dispatched), because it can represent the "no button currently active" state (0).

The value of the buttons attribute MUST be as follows:

• 0 MUST indicate no button is currently active.
• 1 MUST indicate the primary button of the device (in general, the left button or the only button on single-button devices, used to activate a user interface control or select text).
• 2 MUST indicate the secondary button (in general, the right button, often used to display a context menu), if present.
• 4 MUST indicate the auxiliary button (in general, the middle button, often combined with a mouse wheel).

Some pointing devices provide or simulate more buttons. To represent such buttons, the value MUST be doubled for each successive button (in the binary series 8 , 16 , 32 , ... ).

Note

Because the sum of any set of button values is a unique number, a content author can use a bitwise operation to determine how many buttons are currently being pressed and which buttons they are, for an arbitrary number of mouse buttons on a device. For example, the value 3 indicates that the left and right button are currently both pressed, while the value 5 indicates that the left and middle button are currently both pressed.

Note

Some default actions related to events such as mousedown and mouseup depend on the specific mouse button in use.

The un-initialized value of this attribute MUST be 0 .

relatedTarget

Used to identify a secondary EventTarget related to a UI event, depending on the type of event.

The un-initialized value of this attribute MUST be null .

getModifierState(keyArg)

Queries the state of a modifier using a key value.

Returns true if it is a modifier key and the modifier is activated, false otherwise.

DOMString keyArg

Refer to the KeyboardEvent 's getModifierState () method for a description of this parameter.

WebIDLdictionary MouseEventInit : EventModifierInit {
	long screenX = 0;
	long screenY = 0;
	long clientX = 0;
	long clientY = 0;
	short button = 0;
	unsigned short buttons = 0;
	EventTarget? relatedTarget = null;
};

screenX

Initializes the screenX attribute of the MouseEvent object to the desired horizontal relative position of the mouse pointer on the user's screen.

Initializing the event object to the given mouse position must not move the user's mouse pointer to the initialized position.

screenY

Initializes the screenY attribute of the MouseEvent object to the desired vertical relative position of the mouse pointer on the user's screen.

Initializing the event object to the given mouse position must not move the user's mouse pointer to the initialized position.

clientX

Initializes the clientX attribute of the MouseEvent object to the desired horizontal position of the mouse pointer relative to the client window of the user's browser.

Initializing the event object to the given mouse position must not move the user's mouse pointer to the initialized position.

clientY

Initializes the clientY attribute of the MouseEvent object to the desired vertical position of the mouse pointer relative to the client window of the user's browser.

Initializing the event object to the given mouse position must not move the user's mouse pointer to the initialized position.

button

Initializes the button attribute of the MouseEvent object to a number representing the desired state of the button(s) of the mouse.

Note

The value 0 is used to represent the primary mouse button, 1 is used to represent the auxiliary/middle mouse button, and 2 to represent the right mouse button. Numbers greater than 2 are also possible, but are not specified in this document.

buttons

Initializes the buttons attribute of the MouseEvent object to a number representing one or more of the button(s) of the mouse that are to be considered active.

Note

The buttons attribute is a bit-field. If a mask value of 1 is true when applied to the value of the bit field, then the primary mouse button is down. If a mask value of 2 is true when applied to the value of the bit field, then the right mouse button is down. If a mask value of 4 is true when applied to the value of the bit field, then the auxiliary/middle button is down.

In JavaScript, to initialize the buttons attribute as if the right (2) and middlebutton (4) were being pressed simultaneously, the buttons value can be assigned as either:

{
buttons:
2
|
4
}

or:

{
buttons:
6
}

relatedTarget

The relatedTarget should be initialized to the element whose bounds the mouse pointer just left (in the case of a mouseover or mouseenter event) or the element whose bounds the mouse pointer is entering (in the case of a mouseout or mouseleave or focusout event). For other events, this value need not be assigned (and will default to null).

Implementations MUST maintain the current click count when generating mouse events. This MUST be a non-negative integer indicating the number of consecutive clicks of a pointing device button within a specific time. The delay after which the count resets is specific to the environment configuration.

The algorithms in this section assume that the native platform OS will provide the following:

• An event when the mouse is moved (handled by handle native mouse move )
• An event when a mouse button is pressed (handled by handle native mouse down )
• An event when a mouse button is released (handled by handle native mouse up )
• A way to identify when a mouse button press should be interpreted as a "click" (handled by handle native mouse click )
  • For example, as a flag or as a separate event
  • If a separate "click" event is fired, then the native OS will fire it immediately after the corresponding "mouse up" event, with no intervening mouse-related events
• A way to identify when a mouse click is a "double click" (handled by handle native mouse double click )

For these events, the OS will be able to provide the following info:

• The x,y mouse coordinates relative to the native OS desktop
• The x,y mouse coordinates relative to the UA's window viewport
• Which keyboard modifiers are currently being held

Generally, when a constructor of an Event interface, or of an interface inherited from the Event interface, is invoked, the steps described in [ DOM ] should be followed. However the MouseEvent interfaces provide additional dictionary members for initializing the internal state of the Event object's key modifiers: specifically, the internal state queried for using the getModifierState () methods. This section supplements the [ DOM ] steps for intializing a new MouseEvent object with these optional modifier states.

For the purposes of constructing a MouseEvent , or object derived from these objects using the algorithm below, all MouseEvent , and derived objects have internal key modifier state which can be set and retrieved using the key modifier names described in the Modifier Keys table in [ UIEvents-Key ].

The following steps supplement the algorithm defined for constructing events in [ DOM ]:

• If the Event being constructed is a MouseEvent object or an object that derives from it, and a EventModifierInit argument was provided to the constructor, then run the following sub-steps:
  • For each EventModifierInit argument, if the dictionary member begins with the string "modifier" , then let the key modifier name be the dictionary member's name excluding the prefix "modifier" , and set the Event object's internal key modifier state that matches the key modifier name to the corresponding value.

A MouseEvent has the following internal flags that are used to track the state of various modifier keys: shift flag , control flag , alt flag , altgraph flag , and meta flag . These flags are set if the corresponding modifier key was pressed at the time of the mouse event.

1. Let pos be the x,y coordinates relative to the viewport
2. Return [ CSSOM-View ]'s elementFromPoint () with pos (the frontmost DOM element at pos )
   Note

   To account for inert or disabled elements. this should call elementsFromPoint () and reject invalid elements.

To initialize a MouseEvent with event , eventType and eventTarget , bubbles , and cancelable , run the following steps:

1. Initialize a UIEvent with event , eventType , eventTarget , bubbles and cancelable .
2. Set event . screenX to the x-coordinate of the position where the event occurred relative to the origin of the desktop
3. Set event . screenY to the y-coordinate of the position where the event occurred relative to the origin of the desktop
4. Set event . clientX to the x-coordinate of the position where the event occurred relative to the origin of the viewport
5. Set event . clientY to the y-coordinate of the position where the event occurred relative to the origin of the viewport
6. Set mouse event modifiers with event
7. Set event . button to 0
8. Set event . buttons to mouse button bitmask
9. Initialize PointerLock attributes for MouseEvent with event
   Issue 1

   We should provide a hook for PointerLock instead of hardcoding it here.

1. Let event be the MouseEvent to update
2. Set event 's shift flag if key modifier state includes "Shift", unset it otherwise
3. Set event 's control flag if key modifier state includes "Control", unset it otherwise
4. Set event 's alt flag if key modifier state includes "Alt", unset it otherwise
5. Set event 's altgraph flag if key modifier state includes "AltGraph", unset it otherwise
6. Set event 's meta flag if key modifier state includes "Meta", unset it otherwise
7. Set event . shiftKey to true if the event's shift flag is set, false otherwise
8. Set event . ctrlKey to true if the event's control flag is set, false otherwise
9. Set event . altKey to true if the event's alt flag or altgraph flag is set, false otherwise
10. Set event . metaKey to true if the event's meta flag is set, false otherwise

1. Let eventType be a DOMString containing a valid MouseEvent type
2. Let eventTarget be the EventTarget of the event
3. Let bubbles be true
4. Let cancelable be true
5. Let event be the result of creating an event using MouseEvent
6. Initialize a MouseEvent with event , eventType , eventTarget , bubbles and cancelable .
7. Return event

1. Let eventType be a DOMString containing a valid MouseEvent type
2. Let eventTarget be the EventTarget of the event
3. Let bubbles be "false"
4. Let cancelable be "false"
5. Let event be the result of creating an event using MouseEvent
6. Initialize a MouseEvent with event , eventType , eventTarget , bubbles and cancelable .
7. Return event

This will return a button ID suitable for storing in the MouseEvent 's button attribute.

1. Let mbutton be an ID that identifies a mouse button
2. If mbutton is the primary mouse button, then return 0
3. If mbutton is the auxiliary (middle) mouse button, then return 1
4. If mbutton is the secondary mouse button, then return 2
5. If mbutton is the X1 (back) button, then return 3
6. If mbutton is the X2 (forward) button, then return 4

1. Let event be the MouseEvent to initialize
2. Let native be the native mouse event
   Editor's note

   TODO.

3. If event . type is one of [ mousedown, mouseup ], then
   1. Let mbutton be an ID from native that identifies which mouse button was pressed
   2. Set event . button to calculate MouseEvent button attribute with mbutton

1. Let native be the native mousedown
2. Let mbutton be an ID from native that identifies which mouse button was pressed
3. Update the mouse button bitmask as follows:
   1. If mbutton is the primary mouse button, then set the 0x01 bit
   2. If mbutton is the secondary mouse button, then set the 0x02 bit
   3. If mbutton is the auxiliary (middle) mouse button, then set the 0x04 bit
      Note

      Other buttons can be added starting with 0x08 .

4. Let target be hit test with viewport-relative coordinates from native
5. Let event be the result of creating a cancelable MouseEvent with "mousedown", target
6. Set MouseEvent attributes from native with native
7. Maybe send pointerdown event with event
8. Let result be dispatch event at target
9. If result is true and target is a focusable area that is click focusable , then
   1. Run the focusing steps at target
10. if mbutton is the secondary mouse button, then
    1. Maybe show context menu with native , target

1. Let native be the native mouseup
   Note

   Other mouse events can occur between the mousedown and mouseup.

2. Let mbutton be an ID from native that identifies which mouse button was pressed
3. Update the mouse button bitmask as follows:
   1. If mbutton is the primary mouse button, then clear the 0x01 bit
   2. If mbutton is the secondary mouse button, then clear the 0x02 bit
   3. If mbutton is the auxiliary (middle) mouse button, then clear the 0x04 bit
4. Let target be hit test with viewport-relative coordinates from native
5. Let event be the result of creating a cancelable MouseEvent with "mouseup", target
6. Set MouseEvent attributes from native with native
7. Maybe send pointerup event with event
8. dispatch event at target

1. Let native be the native mouse click
   Note

   The platform should call this immediately after handle native mouse up for mouseups that generate clicks.

2. Let target be hit test with viewport-relative coordinates from native
3. Send click event with native and target .

1. Let native be the native mousedown
2. Let target be the EventTarget of the event
3. Let mbutton be 1 (primary mouse button by default)
4. If native is valid, then
   1. Let mbutton be an ID from native that identifies which mouse button was pressed
5. Set eventType to "click" if mbutton is the primary mouse button, otherwise "auxclick"
6. Let event be the result of creating a PointerEvent with eventType and target
7. If native is valid, then
   1. Set MouseEvent attributes from native with event , native
   2. If event . screenX is not an integer value, then round it.
   3. If event . screenY is not an integer value, then round it.
8. dispatch event at target
   Note

   See pointerevents/100 for info about browsers using PointerEvents and rounded coordinates.

   Editor's note

   Any "default action" is handled during dispatch by triggering the activation behavior algorithm for the target. So there is no need for handle that here. However, need to verify that the existing spec handles disabled/css-pointer-events/inert/...

   Note

   To handle HTMLelement.click() , call this algorithm with native = null and target = HTMLelement .

   Note

   To handle keyboard-initiated clicks, call this algorithm with native = null and target = currently focused element.

1. Let native be the native mouse double click
   Note

   This should be called immediately after handle native mouse click for mouse clicks that generate double clicks.

2. Let mbutton be an ID from native that identifies which mouse button was pressed
3. If mbutton is not the primary mouse button, then return
4. Let target be hit test with viewport-relative coordinates from native
5. Let event be the result of creating a PointerEvent with "dblclick" and target
6. Set MouseEvent attributes from native with event , native
7. If event . screenX is not an integer value, then round it.
8. If event . screenY is not an integer value, then round it.
9. dispatch event at target

1. Let native be the native mouse move
   Issue 2

   This algorithm makes assumptions about the dispatch of PointerEvents because they are not currently specified explicitly. Once pointerevents/285 is resolved this may need to be updated.

2. Let target be hit test with viewport-relative coordinates from native
3. Let targetDomPath be inclusive ancestors of target
4. Generate events for leaving the current element:
   1. If last mouse element is defined and not equal to target , then
      1. Let mouseout be the result of creating a cancelable MouseEvent with "mouseout" and last mouse element
         Editor's note

         TODO: Set mouseout attributes from native . +CSSOM attributes.

   2. Maybe send pointerout event with mouseout
   3. Dispatch mouseout at target
      Note

      Verify behavior when canceled (appears to have no effect).

   4. Let leaveElements be a copy of last mouse DOM path with all elements common to targetDomPath removed.
   5. For each element in leaveElements , do
      Editor's note

      Handle case where element has been deleted. Also case where it has been moved: Should the DOM mutation have triggered a mouseleave event? Should we sent it now? Should it be dropped? Need to verify what current browsers do.

      1. Let mouseleave be the result of creating a non-cancelable MouseEvent with "mouseleave" and element
      2. Set mouseleave . Event . composed = false
         Note

         Check compat: Value of event.composed. Spec says false. Chrome/Linux = true. Firefox/Linux = false.

      3. Maybe send pointerleave event with mouseleave
      4. Let result be dispatch mouseleave at element
5. Generate events for entering the new element:
   1. If target is not last mouse element , then
      1. Let mouseover be the result of creating a cancelable MouseEvent with "mouseover" and target
         Editor's note

         TODO: Set mouseout attributes from native . +CSSOM attributes.

      2. Maybe send pointerover event with mouseover
      3. Dispatch mouseout at target
         Note

         Need to verify behavior when canceled (appears to have no effect).

      4. Let enterElements be a copy of targetDomPath with all elements common to last mouse DOM path removed.
      5. For each element in enterElements , do
         Note

         Handle case where element has been deleted or moved.

         1. Let mouseenter be the result of creating a non-cancelable MouseEvent with "mouseenter" and element
         2. Set mouseenter . Event . composed = false
            Note

            Check compat: Value of event.composed. Spec says false. Chrome/Linux = true. Firefox/Linux = false.

         3. Maybe send pointerenter event with mouseenter
            Note

            Check compat for shadow DOM elements. Chrome/Linux fires this event at the element and the shadow root.

         4. Let result be dispatch mouseenter at element
      6. Set last mouse element to target
      7. Set last mouse DOM path to targetDomPath
6. Let mousemove be the result of creating a cancelable MouseEvent with "mousemove" and element
7. Set PointerLock attributes for mousemove
8. Maybe send pointermove event with mousemove
9. Dispatch mousemove at element

1. Let native be the native mousedown or pointer event
2. Let target be the EventTarget of the event
   1. Let menuevent be the result of creating a PointerEvent with "contextmenu", target
   2. If native is valid, then
      1. Set MouseEvent attributes from native with native
   3. Let result be dispatch menuevent at target
   4. If result is true, then show the UA context menu

The auxclick event type MUST be dispatched on the topmost event target indicated by the pointer, when the user presses down and releases the non-primary pointer button, or otherwise activates the pointer in a manner that simulates such an action. The actuation method of the mouse button depends upon the pointer device and the environment configuration, e.g., it MAY depend on the screen location or the delay between the press and release of the pointing device button.

The auxclick event should only be fired for the non-primary pointer buttons (i.e., when button value is not 0 , buttons value is greater than 1 ). The primary button (like the left button on a standard mouse) MUST NOT fire auxclick events. See click for a corresponding event that is associated with the primary button.

The auxclick event MAY be preceded by the mousedown and mouseup events on the same element, disregarding changes between other node types (e.g., text nodes). Depending upon the environment configuration, the auxclick event MAY be dispatched if one or more of the event types mouseover , mousemove , and mouseout occur between the press and release of the pointing device button.

The default action of the auxclick event type varies based on the target of the event and the value of the button or buttons attributes. Typical default actions of the auxclick event type are as follows:

• If the target has associated activation behavior, the default action MUST be to execute that activation behavior.

myLink.addEventListener("auxclick", function(e) {
  if (e.button === 1) {
    // This would prevent the default behavior which is for example
    // opening a new tab when middle clicking on a link.
    e.preventDefault();
    // Do something else to handle middle button click like taking
    // care of opening link or non-link buttons in new tabs in a way
    // that fits the app. Other actions like closing a tab in a tab-strip
    // which should be done on the click action can be done here too.
  }
});

myDiv.addEventListener("contextmenu", function(e) {
  // This call makes sure no context menu is shown
  // to interfere with page receiving the events.
  e.preventDefault();
});
myDiv.addEventListener("auxclick", function(e) {
  if (e.button === 2) {
    // Do something else to handle right button click like opening a
    // customized context menu inside the app.
  }
});

The click event type MUST be dispatched on the topmost event target indicated by the pointer, when the user presses down and releases the primary pointer button, or otherwise activates the pointer in a manner that simulates such an action. The actuation method of the mouse button depends upon the pointer device and the environment configuration, e.g., it MAY depend on the screen location or the delay between the press and release of the pointing device button.

The click event should only be fired for the primary pointer button (i.e., when button value is 0 , buttons value is 1 ). Secondary buttons (like the middle or right button on a standard mouse) MUST NOT fire click events. See auxclick for a corresponding event that is associated with the non-primary buttons.

The click event MAY be preceded by the mousedown and mouseup events on the same element, disregarding changes between other node types (e.g., text nodes). Depending upon the environment configuration, the click event MAY be dispatched if one or more of the event types mouseover , mousemove , and mouseout occur between the press and release of the pointing device button. The click event MAY also be followed by the dblclick event.

If a user mouses down on a text node child of a <p> element which has been styled with a large line-height, shifts the mouse slightly such that it is no longer over an area containing text but is still within the containing block of that <p> element (i.e., the pointer is between lines of the same text block, but not over the text node per se), then subsequently mouses up, this will likely still trigger a click event (if it falls within the normal temporal hysteresis for a click ), since the user has stayed within the scope of the same element. Note that user-agent-generated mouse events are not dispatched on text nodes.

In addition to being associated with pointer devices, the click event type MUST be dispatched as part of an element activation.

The default action of the click event type varies based on the target of the event and the value of the button or buttons attributes. Typical default actions of the click event type are as follows:

• If the target has associated activation behavior, the default action MUST be to execute that activation behavior.
• If the target is focusable, the default action MUST be to give that element document focus.

A user agent MUST dispatch this event before invoking a context menu.

When the contextmenu event is triggered by right mouse button, the contextmenu event MUST be dispatched after the mousedown event.

A user agent MUST dispatch this event when the primary button of a pointing device is clicked twice over an element. The definition of a double click depends on the environment configuration, except that the event target MUST be the same between mousedown , mouseup , and dblclick . This event type MUST be dispatched after the event type click if a click and double click occur simultaneously, and after the event type mouseup otherwise.

As with the click event, the dblclick event should only be fired for the primary pointer button. Secondary buttons MUST NOT fire dblclick events.

In a multi-pointer (e.g. multi-touch) scenario, the isPrimary property is used to identify a master pointer amongst the set of active pointers for each pointer type.

• At any given time, there can only ever be at most one primary pointer for each pointer type.
• The first pointer to become active for a particular pointer type (e.g. the first finger to touch the screen in a multi-touch interaction) becomes the primary pointer for that pointer type.
• Only a primary pointer will produce compatibility mouse events . In the case where there are multiple primary pointers , these pointers will all produce compatibility mouse events .

To fire a pointer event named e means to fire an event named e using PointerEvent whose attributes are set as defined in PointerEvent Interface and Attributes and Default Actions .

If the event is not a gotpointercapture , lostpointercapture , click , auxclick or contextmenu event, run the process pending pointer capture steps for this PointerEvent .

Determine the target at which the event is fired as follows:

• If the pointer capture target override has been set for the pointer, set the target to pointer capture target override object.
• Otherwise, set the target to the object returned by hit test .

Let targetDocument be target's node document [ DOM ].

If the event is pointerdown , pointermove , or pointerup , set active document for the event's pointerId to targetDocument .

If the event is pointerdown , the associated device is a direct manipulation device, and the target is an Element , then set pointer capture for this pointerId to the target element as described in implicit pointer capture .

Before firing this event, the user agent SHOULD treat the target as if the pointing device has moved over it from the previousTarget for the purpose of ensuring event ordering [ UIEVENTS ]. If the needsOverEvent flag is set, a pointerover event is needed even if the target element is the same.

Fire the event to the determined target.

Save the determined target as the previousTarget for the given pointer, and reset the needsOverEvent flag to false . If the previousTarget at any point will no longer be connected [ DOM ], update the previousTarget to the nearest still connected [ DOM ] parent following the event path corresponding to dispatching events to the previousTarget , and set the needsOverEvent flag to true .

A pointing device that moved relative to the screen surface or underwent some change in any of its properties fires various events as defined in Pointer Event types . For a stationary pointing device (that neither moved relative to the screen surface nor underwent any change in any properties), the user agent MUST fire certain boundary events after a layout change that affected the hit test target for the pointer, see pointerover , pointerenter , pointerout and pointerleave for details. The user agent MAY delay the firing of these boundary events because of performance reasons (e.g. to avoid too many hit-tests or layout changes caused by boundary event listeners).

Pointer Events include two complementary sets of attributes to express the orientation of a transducer relative to the X-Y plane: tiltX / tiltY (introduced in the original Pointer Events specification), and azimuthAngle / altitudeAngle (adopted from the Touch Events - Level 2 specification).

Depending on the specific hardware and platform, user agents will likely only receive one set of values for the transducer orientation relative to the screen plane — either tiltX / tiltY or altitudeAngle / azimuthAngle . User agents MUST use the following algorithm for converting these values.

When the user agent calculates tiltX / tiltY from azimuthAngle / altitudeAngle it SHOULD round the final integer values using Math.round [ ECMASCRIPT ] rules.

/* Converting between tiltX/tiltY and altitudeAngle/azimuthAngle */
function spherical2tilt(altitudeAngle, azimuthAngle) {
  const radToDeg = 180/Math.PI;
  let tiltXrad = 0;
  let tiltYrad = 0;
  if (altitudeAngle == 0) {
    // the pen is in the X-Y plane
    if (azimuthAngle == 0 || azimuthAngle == 2*Math.PI) {
      // pen is on positive X axis
      tiltXrad = Math.PI/2;
    }
    if (azimuthAngle == Math.PI/2) {
      // pen is on positive Y axis
      tiltYrad = Math.PI/2;
    }
    if (azimuthAngle == Math.PI) {
      // pen is on negative X axis
      tiltXrad = -Math.PI/2;
    }
    if (azimuthAngle == 3*Math.PI/2) {
      // pen is on negative Y axis
      tiltYrad = -Math.PI/2;
    }
    if (azimuthAngle>0 && azimuthAngle<Math.PI/2) {
      tiltXrad = Math.PI/2;
      tiltYrad = Math.PI/2;
    }
    if (azimuthAngle>Math.PI/2 && azimuthAngle<Math.PI) {
      tiltXrad = -Math.PI/2;
      tiltYrad = Math.PI/2;
    }
    if (azimuthAngle>Math.PI && azimuthAngle<3*Math.PI/2) {
      tiltXrad = -Math.PI/2;
      tiltYrad = -Math.PI/2;
    }
    if (azimuthAngle>3*Math.PI/2 && azimuthAngle<2*Math.PI) {
      tiltXrad = Math.PI/2;
      tiltYrad = -Math.PI/2;
    }
  }
  if (altitudeAngle != 0) {
    const tanAlt = Math.tan(altitudeAngle);
    tiltXrad = Math.atan(Math.cos(azimuthAngle) / tanAlt);
    tiltYrad = Math.atan(Math.sin(azimuthAngle) / tanAlt);
  }
  return {"tiltX":tiltXrad*radToDeg, "tiltY":tiltYrad*radToDeg};
}
function tilt2spherical(tiltX, tiltY) {
  const tiltXrad = tiltX * Math.PI/180;
  const tiltYrad = tiltY * Math.PI/180;
  // calculate azimuth angle
  let azimuthAngle = 0;
  if (tiltX == 0) {
    if (tiltY > 0) {
      azimuthAngle = Math.PI/2;
    }
    else if (tiltY < 0) {
      azimuthAngle = 3*Math.PI/2;
    }
  } else if (tiltY == 0) {
    if (tiltX < 0) {
      azimuthAngle = Math.PI;
    }
  } else if (Math.abs(tiltX) == 90 || Math.abs(tiltY) == 90) {
    // not enough information to calculate azimuth
    azimuthAngle = 0;
  } else {
    // Non-boundary case: neither tiltX nor tiltY is equal to 0 or +-90
    const tanX = Math.tan(tiltXrad);
    const tanY = Math.tan(tiltYrad);
    azimuthAngle = Math.atan2(tanY, tanX);
    if (azimuthAngle < 0) {
      azimuthAngle += 2*Math.PI;
    }
  }
  // calculate altitude angle
  let altitudeAngle = 0;
  if (Math.abs(tiltX) == 90 || Math.abs(tiltY) == 90) {
      altitudeAngle = 0
  } else if (tiltX == 0) {
    altitudeAngle = Math.PI/2 - Math.abs(tiltYrad);
  } else if (tiltY == 0) {
    altitudeAngle = Math.PI/2 - Math.abs(tiltXrad);
  } else {
    // Non-boundary case: neither tiltX nor tiltY is equal to 0 or +-90
    altitudeAngle =  Math.atan(1.0/Math.sqrt(Math.pow(Math.tan(tiltXrad),2) + Math.pow(Math.tan(tiltYrad),2)));
  }
  return {"altitudeAngle":altitudeAngle, "azimuthAngle":azimuthAngle};
}

To initialize a PointerEvent with event , eventType and eventTarget , bubbles , and cancelable , run the following steps:

1. Initialize a MouseEvent with event , eventType and eventTarget , bubbles and cancelable
2. Initialize all other attributes to default PointerEvent values.

To create a PointerEvent with eventType and eventTarget , bubbles , and cancelable , run the following steps:

1. Let event be the result of creating an event using PointerEvent
2. Initialize a PointerEvent with event , eventType and eventTarget , bubbles and cancelable
3. Return event

1. Let eventType be a DOMString containing the event type
2. Let mouseevent be the corresponding MouseEvent
3. Let event be the result of creating an event using PointerEvent
4. Let target be the mouseevent . target
5. Initialize a PointerEvent with event , eventType and target
6. Copy MouseEvent attributes from mouseevent into event
7. Return event

1. Let mouseout be the corresponding mouseout MouseEvent
2. Let pointerout be the result of creating PointerEvent from MouseEvent with "pointerout" and mouseout
3. Set pointerevent attributes
   Editor's note

   TODO.

4. Let target be the mouseout . target
5. dispatch pointerout at target

1. Let mouseout be the corresponding mouseout MouseEvent
2. Let pointerout be the result of creating PointerEvent from MouseEvent with "pointerout" and mouseout
3. Set pointerevent attributes
   Editor's note

   TODO.

4. Let target be the mouseout . target
5. dispatch pointerout at target

1. Let mouseout be the corresponding mouseout MouseEvent
2. Let pointerout be the result of creating PointerEvent from MouseEvent with "pointerout" and mouseout
3. Set pointerevent attributes
   Editor's note

   TODO.

4. Let target be the mouseout . target
5. dispatch pointerout at target

1. Let mouseout be the corresponding mouseout MouseEvent
2. Let pointerout be the result of creating PointerEvent from MouseEvent with "pointerout" and mouseout
3. Set pointerevent attributes
   Editor's note

   TODO.

4. Let target be the mouseout . target
5. dispatch pointerout at target

1. Let mouseout be the corresponding mouseout MouseEvent
   Editor's note

   Can this send pointermove and pointerrawupdate? Or do we need 2 methods?

   Editor's note

   What is needed to properly define how pointermove events are coalesced?

2. Let pointerout be the result of creating PointerEvent from MouseEvent with "pointerout" and mouseout
3. Set pointerevent attributes
   Editor's note

   TODO.

4. Let target be the mouseout . target
5. dispatch pointerout at target

1. Let mouseout be the corresponding mouseout MouseEvent
   Note

   Unlike mousedown events, pointerdown events are not nested when multiple buttons are pressed. The MouseEvent is passed so that the fields can be copied into the PointerEvent.

2. Let pointerout be the result of creating PointerEvent from MouseEvent with "pointerout" and mouseout
3. Set pointerevent attributes
   Editor's note

   TODO.

4. Let target be the mouseout . target
5. dispatch pointerout at target

1. Let mouseout be the corresponding mouseout MouseEvent
2. Let target be the mouseout . target
3. dispatch pointerout at target

1. Let mouseout be the corresponding mouseout MouseEvent
   Note

   Unlike mouseup events, pointerup events are not nested when multiple buttons are pressed. The MouseEvent is passed so that the fields can be copied into the PointerEvent.

2. Let pointerout be the result of creating PointerEvent from MouseEvent with "pointerout" and mouseout
3. Set pointerevent attributes
   Editor's note

   TODO.

4. Let target be the mouseout . target
5. dispatch pointerout at target

The user agent MUST fire a pointer event named pointerover when any of the following occurs:

• The step to determine the target of a pointer detects that the pointer has moved into an element.
• A layout change causes the hit test boundaries of an element to move underneath an uncaptured pointer of a stationary pointing device.
• Before the user agent fires a pointerdown event for a device that does not support hover (see pointerdown ).

The user agent MUST fire a pointer event named pointerenter when any of the following occurs:

• The step to determine the target of a pointer detects that the pointer has moved into an element or one of its descendants.
• A layout change causes the hit test boundaries of an element or one of its descendants to move underneath an uncaptured pointer of a stationary pointing device.
• Before the user agent fires a pointerdown event for a device that does not support hover (see pointerdown ).

The user agent MUST fire a pointer event named pointerdown when a pointer enters the active buttons state . For mouse, this is when the device transitions from no buttons depressed to at least one button depressed. For touch, this is when physical contact is made with the digitizer . For pen, this is when the pen either makes physical contact with the digitizer without any button depressed, or transitions from no buttons depressed to at least one button depressed while hovering.

For input devices that do not support hover , the user agent MUST also fire a pointer event named pointerover followed by a pointer event named pointerenter prior to dispatching the pointerdown event.

The user agent MUST fire a pointer event named pointermove when a pointer changes any properties that don't fire pointerdown or pointerup events. This includes any changes to coordinates, pressure, tangential pressure, tilt, twist, contact geometry ( width and height ) or chorded buttons .

User agents MAY delay dispatch of the pointermove event (for instance, for performance reasons). The coalesced events information will be exposed via the getCoalescedEvents method for the single dispatched pointermove event. The final coordinates of such events should be used for finding the target of the event.

The user agent MUST fire a pointer event named pointerrawupdate , and only do so within a secure context , when a pointer changes any properties that don't fire pointerdown or pointerup events. See pointermove event for a list of such properties.

In contrast with pointermove , user agents SHOULD dispatch pointerrawupdate events as soon as possible and as frequently as the JavaScript can handle the events.

The target of pointerrawupdate events might be different from the pointermove events due to the fact that pointermove events might get delayed or coalesced, and the final position of the event which is used for finding the target could be different from its coalesced events.

Note that if there is already another pointerrawupdate with the same pointerId that hasn't been dispatched in the event loop , the user agent MAY coalesce the new pointerrawupdate with that event instead of creating a new task . This may cause pointerrawupdate to have coalesced events, and they will all be delivered as coalesced events of one pointerrawupdate event as soon as the event is processed in the event loop . See getCoalescedEvents for more information.

In terms of ordering of pointerrawupdate and pointermove , if the user agent received an update from the platform that causes both pointerrawupdate and pointermove events, then the user agent MUST dispatch the pointerrawupdate event before the corresponding pointermove .

Other than the target , the concatenation of coalesced events lists of all dispatched pointerrawupdate events since the last pointermove event is the same as the coalesced events of the next pointermove event in terms of the other event attributes. The attributes of pointerrawupdate are mostly the same as pointermove , with the exception of cancelable which MUST be false for pointerrawupdate .

User agents SHOULD not fire compatibility mouse events for pointerrawupdate .

The user agent MUST fire a pointer event named pointerup when a pointer leaves the active buttons state . For mouse, this is when the device transitions from at least one button depressed to no buttons depressed. For touch, this is when physical contact is removed from the digitizer . For pen, this is when the pen is removed from the physical contact with the digitizer while no button is depressed, or transitions from at least one button depressed to no buttons depressed while hovering.

For input devices that do not support hover , the user agent MUST also fire a pointer event named pointerout followed by a pointer event named pointerleave after dispatching the pointerup event.

All pointerup events have a pressure value of 0 .

The user agent MUST also implicitly release the pointer capture if the pointer is currently captured.

The user agent MUST fire a pointer event named pointercancel when it detects a scenario to suppress a pointer event stream .

The values of the following properties of the pointercancel event MUST match the values of the last dispatched pointer event with the same pointerId : width , height , pressure , tangentialPressure , tiltX , tiltY , twist , altitudeAngle , azimuthAngle , pointerType , isPrimary , and the coordinates inherited from [ UIEVENTS ]. The coalescedEvents and predictedEvents lists in the pointercancel event MUST be empty, and the event's cancelable attribute MUST be false.

The user agent MUST fire a pointer event named pointerout when any of the following occurs:

• The step to determine the target of a pointer detects that the pointer has moved out of an element.
• A layout change causes the hit test boundaries of an element to move away from underneath an uncaptured pointer of a stationary pointing device.
• After the user agent fires a pointerup event for a device that does not support hover (see pointerup ).
• The user agent has detected a scenario to suppress a pointer event stream .

The user agent MUST fire a pointer event named pointerleave when any of the following occurs:

• The step to determine the target of a pointer detects that the pointer has moved out of an element and all of its descendants.
• A layout change causes the hit test boundaries of an element and all of its descendants to move away from underneath an uncaptured pointer of a stationary pointing device.
• After the user agent fires the pointerup event for a device that does not support hover (see pointerup ).
• The user agent has detected a scenario to suppress a pointer event stream .

The user agent MUST fire a pointer event named gotpointercapture when an element receives pointer capture. This event is fired at the element that is receiving pointer capture. Subsequent events for that pointer will be fired at this element. See the setting pointer capture and process pending pointer capture sections.

The user agent MUST fire a pointer event named lostpointercapture after pointer capture is released for a pointer. This event MUST be fired prior to any subsequent events for the pointer after capture was released. This event is fired at the element from which pointer capture was removed. All subsequent events for the pointer except click , auxclick , and contextmenu events follow normal hit testing mechanisms (out of scope for this specification) for determining the event target. See the releasing pointer capture , implicit release of pointer capture , and process pending pointer capture sections.

This section is an addition to click , auxclick and contextmenu events defined in [ UIEVENTS ]. These events are typically tied to user interface activation, and are fired even from non-pointer input devices, such as keyboards.

These events MUST be of type PointerEvent , and are subject to the additional requirements mentioned in the rest of this section.

WebIDL[Exposed=Window]
interface WheelEvent : MouseEvent {
	constructor(DOMString type, optional WheelEventInit eventInitDict = {});
	// DeltaModeCode
	const unsigned long DOM_DELTA_PIXEL = 0x00;
	const unsigned long DOM_DELTA_LINE	= 0x01;
	const unsigned long DOM_DELTA_PAGE	= 0x02;
	readonly attribute double deltaX;
	readonly attribute double deltaY;
	readonly attribute double deltaZ;
	readonly attribute unsigned long deltaMode;
	readonly attribute boolean momentum;
};

DOM_DELTA_PIXEL

The units of measurement for the delta MUST be pixels. This is the most typical case in most operating system and implementation configurations.

DOM_DELTA_LINE

The units of measurement for the delta MUST be individual lines of text. This is the case for many form controls.

DOM_DELTA_PAGE

The units of measurement for the delta MUST be pages, either defined as a single screen or as a demarcated page.

deltaX

In user agents where the default action of the wheel event is to scroll, the value MUST be the measurement along the x-axis (in pixels, lines, or pages) to be scrolled in the case where the event is not cancelled. Otherwise, this is an implementation-specific measurement (in pixels, lines, or pages) of the movement of a wheel device around the x-axis. The un-initialized value of this attribute MUST be 0.0 .

deltaY

In user agents where the default action of the wheel event is to scroll, the value MUST be the measurement along the y-axis (in pixels, lines, or pages) to be scrolled in the case where the event is not cancelled. Otherwise, this is an implementation-specific measurement (in pixels, lines, or pages) of the movement of a wheel device around the y-axis. The un-initialized value of this attribute MUST be 0.0 .

deltaZ

In user agents where the default action of the wheel event is to scroll, the value MUST be the measurement along the z-axis (in pixels, lines, or pages) to be scrolled in the case where the event is not cancelled. Otherwise, this is an implementation-specific measurement (in pixels, lines, or pages) of the movement of a wheel device around the z-axis. The un-initialized value of this attribute MUST be 0.0 .

deltaMode

The deltaMode attribute contains an indication of the units of measurement for the delta values. The default value is DOM_DELTA_PIXEL (pixels). This attribute MUST be set to one of the DOM_DELTA constants to indicate the units of measurement for the delta values. The precise measurement is specific to device, operating system, and application configurations. The un-initialized value of this attribute MUST be 0 .

momentum

This attribute must be true if this event is synthesized by the platform to simulate scroll inertia after the user has ended the physical scroll interaction (e.g. lifted the finger from a trackpad after a fling), and false otherwise. The un-initialized value of this attribute MUST be false .

WebIDLdictionary WheelEventInit : MouseEventInit {
	double deltaX = 0.0;
	double deltaY = 0.0;
	double deltaZ = 0.0;
	

	unsigned long deltaMode = 0;
	boolean momentum = false;
};

deltaX

See deltaZ attribute.

deltaY

See deltaZ attribute.

deltaZ

Initializes the deltaZ attribute of the WheelEvent object. Relative positive values for this attribute (as well as the deltaX and deltaY attributes) are given by a right-hand coordinate system where the X, Y, and Z axes are directed towards the right-most edge, bottom-most edge, and farthest depth (away from the user) of the document, respectively. Negative relative values are in the respective opposite directions.

deltaMode

Initializes the deltaMode attribute on the WheelEvent object to the enumerated values 0, 1, or 2, which represent the amount of pixels scrolled ( DOM_DELTA_PIXEL ), lines scrolled ( DOM_DELTA_LINE ), or pages scrolled ( DOM_DELTA_PAGE ) if the rotation of the wheel would have resulted in scrolling.

momentum

Initializes the momentum attribute.

Calling preventDefault on a wheel event can prevent or otherwise interrupt scrolling. For maximum scroll performance, a user agent may not wait for each wheel event associated with the scroll to be processed to see if it will be canceled. In such cases the user agent should generate wheel events whose cancelable property is false , indicating that preventDefault cannot be used to prevent or interrupt scrolling. Otherwise cancelable will be true .

In particular, a user agent should generate only uncancelable wheel events when it observes that there are no non-passive listeners for the event.