Class PointerEvent

Namespace

CSharpToJavaScript.APIs.JS

Assembly

CSharpToJavaScript.dll

The PointerEvent interface represents the state of a DOM event produced by a pointer such as the geometry of the contact point, the device type that generated the event, the amount of pressure that was applied on the contact surface, etc.

[Value("PointerEvent")]
public class PointerEvent : MouseEvent

Inheritance

object

Event

UIEvent

MouseEvent

PointerEvent

Inherited Members

MouseEvent.GetModifierState(string)

MouseEvent.InitMouseEvent(string, bool, bool, Window, long, long, long, long, long, bool, bool, bool, bool, Number, EventTarget)

MouseEvent.PageX

MouseEvent.PageY

MouseEvent.X

MouseEvent.Y

MouseEvent.OffsetX

MouseEvent.OffsetY

MouseEvent.MovementX

MouseEvent.MovementY

MouseEvent.ScreenX

MouseEvent.ScreenY

MouseEvent.ClientX

MouseEvent.ClientY

MouseEvent.LayerX

MouseEvent.LayerY

MouseEvent.CtrlKey

MouseEvent.ShiftKey

MouseEvent.AltKey

MouseEvent.MetaKey

MouseEvent.Button

MouseEvent.Buttons

MouseEvent.RelatedTarget

UIEvent.InitUIEvent(string, bool, bool, Window, long)

UIEvent.SourceCapabilities

UIEvent.View

UIEvent.Detail

UIEvent.Which

Event.NONE

Event.CAPTURING_PHASE

Event.AT_TARGET

Event.BUBBLING_PHASE

Event.ComposedPath()

Event.StopPropagation()

Event.StopImmediatePropagation()

Event.PreventDefault()

Event.InitEvent(string, bool, bool)

Event.Type

Event.Target

Event.SrcElement

Event.CurrentTarget

Event.EventPhase

Event.CancelBubble

Event.Bubbles

Event.Cancelable

Event.ReturnValue

Event.DefaultPrevented

Event.Composed

Event.IsTrusted

Event.TimeStamp

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

A pointer is a hardware agnostic representation of input devices (such as a mouse, pen or contact point on a touch-enable surface). The pointer can target a specific coordinate (or set of coordinates) on the contact surface such as a screen.

A pointer's hit test is the process a browser uses to determine the target element for a pointer event. Typically, this is determined by considering the pointer's location and also the visual layout of elements in a document on screen media.

-Touch events
-GestureEvent
-touch-action

See also on MDN

Constructors

PointerEvent()

public PointerEvent()

PointerEvent(string, PointerEventInit)

The PointerEvent() constructor creates a new synthetic
and untrusted PointerEvent object instance.

public PointerEvent(string type, PointerEventInit eventInitDict = null)

Parameters

type string

eventInitDict PointerEventInit

Remarks

See also on MDN

Properties

AltitudeAngle

The altitudeAngle read-only property of the PointerEvent interface represents the angle between a transducer (a pointer or stylus) axis and the X-Y plane of a device screen.
The altitude angle describes whether the transducer is perpendicular to the screen, parallel, or at some angle in between.

[Value("altitudeAngle")]
public Number AltitudeAngle { get; }

Property Value

Number

An angle in radians between 0 and π/2 where 0 is parallel to the device surface (X-Y plane), and π/2 is perpendicular to the surface.
Defaults to π/2 (perpendicular to the surface) which differs from the altitudeAngle in touch events which defaults to 0 (parallel to the surface).
For hardware and platforms that do not report tilt or angle, the value is π/2.

Remarks

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 and TiltY or altitudeAngle and AzimuthAngle.

The azimuth angle of a pointer compared to the altitude angle

For an additional illustration of this property, see Figure 4 in the specification.

-AzimuthAngle
-TiltX
-TiltY

See also on MDN

AzimuthAngle

The azimuthAngle read-only property of the PointerEvent interface represents the angle between the Y-Z plane and the plane containing both the transducer (pointer or stylus) axis and the Y axis.

[Value("azimuthAngle")]
public Number AzimuthAngle { get; }

Property Value

Number

An angle in radians between 0 and 2π where 0 represents a transducer whose cap is pointing in the direction of increasing X values (point to "3 o'clock" if looking straight down) on the X-Y plane, and the values progressively increase when going clockwise (π/2 at "6 o'clock", π at "9 o'clock", 3π/2 at "12 o'clock").When the transducer is perpendicular to the surface (AltitudeAngle of π/2), the value is 0.
For hardware and platforms that do not report tilt or angle, the value is 0.

Remarks

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 and TiltY or AltitudeAngle and azimuthAngle.

The azimuth angle of a pointer compared to the altitude angle

For an additional illustration of this property, see Figure 5 in the specification.

-AltitudeAngle
-TiltX
-TiltY

See also on MDN

Height

The height read-only property of the
PointerEvent interface represents the height of the pointer's contact
geometry, along the y-axis (in CSS pixels). Depending on the source of the pointer
device (for example a finger), for a given pointer, each event may produce a different
value.

[Value("height")]
public Number Height { get; }

Property Value

Number

The height of the event's contact area (in CSS pixels).

Remarks

If the input hardware cannot report the contact geometry to the browser, the height
defaults to 1.

See also on MDN

IsPrimary

The isPrimary read-only property of the
PointerEvent interface indicates whether or not the pointer device that
created the event is the primary pointer. It returns true if the
pointer that caused the event to be fired is the primary one and returns
false otherwise.

[Value("isPrimary")]
public bool IsPrimary { get; }

Property Value

bool

A boolean, true if the pointer for this event is the primary pointer and returns false otherwise.

Remarks

In a multi-pointer scenario (such as a touch screen that supports more than one touch
point), this property is used to identify a master pointer among the set of
active pointers for each pointer type. Only a primary pointer will produce
compatibility mouse events. Authors who desire only single-pointer interaction
can achieve that by ignoring non-primary pointers.

A pointer is considered primary if the pointer represents a mouse device. A pointer
representing pen input is considered the primary pen input if its
Elementpointerdown event was dispatched when no other active pointers representing
pen input existed. A pointer representing touch input is considered the primary touch
input if its Elementpointerdown event was dispatched when no other active pointers
representing touch input existed.

When two or more pointer device types are being used concurrently, multiple pointers
(one for each PointerType) are considered
primary. For example, a touch contact and a mouse cursor moved simultaneously will
produce pointers that are both considered primary. If there are multiple primary
pointers, these pointers will all produce compatibility mouse events (see
Pointer events for more information about pointer, mouse and touch
interaction).

See also on MDN

PersistentDeviceId

The persistentDeviceId read-only property of the PointerEvent interface is a unique identifier for the pointing device generating the PointerEvent.
This provides a secure, reliable way to identify multiple pointing devices (such as pens) interacting with the screen simultaneously.

[Value("persistentDeviceId")]
public long PersistentDeviceId { get; }

Property Value

long

An integer, or 0 if the device generating the PointerEvent could not be identified.

NOTE

Due to digitizer and pointing device hardware constraints, a persistentDeviceId may not be available for all pointer events, particularly with older hardware.
For example, the pointing device might not report its hardware ID to the digitizer in time for pointerdown to receive a persistentDeviceId: it may initially be 0 and change to a valid value for later events in the stroke.

Remarks

A persistentDeviceId persists for the lifetime of a browsing session.
To avoid the risk of fingerprinting/tracking, pointing devices are assigned a new persistentDeviceId at the start of each session.

Pointer events whose generating device could not be identified are assigned a persistentDeviceId value of 0.

See also on MDN

PointerId

The pointerId read-only property of the PointerEvent interface
is an identifier assigned to the pointer that triggered the event. The identifier
is unique, being different from the identifiers of all other active pointer events.

[Value("pointerId")]
public long PointerId { get; }

Property Value

long

A number.

Remarks

A value -1 indicates that the PointerEvent was not generated by a pointing device.
(For example, a Elementclick event fired on a button
activated via keyboard.) Otherwise, the value may be randomly generated and should
not be relied on to convey any specific information about the device. The value is
only guaranteed to be stable for the lifetime of the page or session.

NOTE

The pointerId property is implemented inconsistently across browsers and does not always persist for each ink stroke or interaction with the screen. For a reliable way of identifying multiple pointing devices on a screen simultaneously, see PersistentDeviceId.

See also on MDN

PointerType

The pointerType read-only property of the
PointerEvent interface indicates the device type (mouse, pen, or touch)
that caused a given pointer event.

[Value("pointerType")]
public string PointerType { get; }

Property Value

string

The event's pointer type. The supported values are the following strings:If the device type cannot be detected by the browser, the value can be an empty string
(""). If the browser supports pointer device types other than those listed
above, the value should be vendor-prefixed to avoid conflicting names for
different types of devices.

Remarks

See also on MDN

Pressure

The pressure read-only property of the
PointerEvent interface indicates the normalized pressure of the pointer
input.

[Value("pressure")]
public Number Pressure { get; }

Property Value

Number

The normalized pressure of the pointer input in the range of 0 to 1, inclusive, where 0 and 1 represent the minimum and maximum pressure the hardware is capable of detecting, respectively. For hardware that does not support pressure, such as a mouse, the value is 0.5 when the pointer is active buttons state and 0 otherwise.

Remarks

-Force

See also on MDN

TangentialPressure

The tangentialPressure read-only property of the
PointerEvent interface represents the normalized tangential pressure of
the pointer input (also known as barrel pressure or cylinder stress).

[Value("tangentialPressure")]
public Number TangentialPressure { get; }

Property Value

Number

A float representing the normalized tangential pressure of the pointer
input in the range -1 to 1, inclusive, where 0 is
the neutral position of the control.Note that some hardware may only support positive values in the range 0 to
1. For hardware that does not support tangential pressure, the value will
be 0.

Remarks

-Force

See also on MDN

TiltX

The tiltX read-only property of the PointerEvent interface is the angle (in degrees) between the Y-Z plane of the pointer and the screen.
This property is typically only useful for a pen/stylus pointer type.

[Value("tiltX")]
public long TiltX { get; }

Property Value

long

The angle in degrees between the Y-Z plane of the pointer (stylus) and the screen. The range of values is -90 to 90, inclusive, where a positive value is a tilt to the right.
For devices that do not support this property, the value is 0.

Remarks

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 and TiltY or AltitudeAngle and AzimuthAngle.

The tiltX angle of a pointer compared to the tiltY angle

For an additional illustration of this property see Figure 2 in the specification.

-TiltY
-AltitudeAngle
-AzimuthAngle

See also on MDN

TiltY

The tiltY read-only property of the PointerEvent interface is the angle (in degrees) between the X-Z plane of the pointer and the screen.
This property is typically only useful for a pen/stylus pointer type.

[Value("tiltY")]
public long TiltY { get; }

Property Value

long

The angle in degrees between the X-Z plane of the pointer (stylus) and the screen.
The range of values is -90 to 90, inclusive, where a positive value is a tilt towards the user.
For devices that do not support this property, the value is 0.

Remarks

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 and tiltY or AltitudeAngle and AzimuthAngle.

The tiltX angle of a pointer compared to the tiltY angle

For an additional illustration of this property, see Figure 3 in the specification.

-TiltX
-AltitudeAngle
-AzimuthAngle

See also on MDN

Twist

The twist read-only property of the
PointerEvent interface represents the clockwise rotation of the pointer
(e.g., pen stylus) around its major axis, in degrees.

[Value("twist")]
public long Twist { get; }

Property Value

long

A long value representing the amount of twist, in degrees, applied to the
transducer (pointer). The value is in the range 0 to 359,
inclusive. For devices that do not report twist, the value is
0.

Remarks

-Force

See also on MDN

Width

The width read-only property of the
PointerEvent interface represents the width of the pointer's contact
geometry along the x-axis, measured in CSS pixels. Depending on the source of the
pointer device (such as a finger), for a given pointer, each event may produce a
different value.

[Value("width")]
public Number Width { get; }

Property Value

Number

The width of the event's contact area (in CSS pixels).

Remarks

If the input hardware cannot report the contact geometry to the browser, the width
defaults to 1.

See also on MDN

Methods

GetCoalescedEvents()

The getCoalescedEvents() method of the PointerEvent interface returns a sequence of PointerEvent instances that were coalesced (merged) into a single 'Elementpointermove' or 'Elementpointerrawupdate' event.
Instead of a stream of many 'Elementpointermove' events, user agents coalesce multiple updates into a single event.
This helps with performance as the user agent has less event handling to perform, but there is a reduction in the granularity and accuracy when tracking, especially with fast and large movements.

[Value("getCoalescedEvents")]
public List<PointerEvent> GetCoalescedEvents()

Returns

List<PointerEvent>

A sequence of 'PointerEvent' instances.

Remarks

The getCoalescedEvents() method lets applications access all un-coalesced position changes for precise handling of pointer movement data where necessary.
Un-coalesced position changes are desirable in drawing applications, for instance, where having access to all events helps to build smoother curves that better match the movement of a pointer.

For an illustration of coalesced events, see Figure 7 in the specification.

See also on MDN

GetPredictedEvents()

The getPredictedEvents() method of the PointerEvent interface returns a sequence of PointerEvent instances that are estimated future pointer positions.
How the predicted positions are calculated depends on the user agent, but they are based on past points, current velocity, and trajectory.

[Value("getPredictedEvents")]
public List<PointerEvent> GetPredictedEvents()

Returns

List<PointerEvent>

A sequence of 'PointerEvent' instances.

Remarks

Applications can use the predicted events to &quot;draw ahead&quot; to a predicted position which may reduce perceived latency depending on the application&apos;s interpretation of the predicted events and the use case.

For an illustration of predicted events, see Figure 8 in the specification.

See also on MDN