UserInput Class

The input devices of the user of a top-level browsing context (see BrowsingContext.Input): a host application injects the input of the user (the moves, the presses and the releases of the pointers, the rotations of the wheel), and the library dispatches the trusted events of the Pointer Events (https://w3c.github.io/pointerevents/) and UI Events (https://w3c.github.io/uievents/) specifications to the documents of the browsing context and of its nested browsing contexts, and runs the default actions of the user agent (the focus, the activation, the drag and drop, the scrolling). The positions are in CSS pixels, relative to the viewport of the top-level browsing context.

public sealed class UserInput

Properties

NameDescription
KeyboardGets the keyboard of the user agent: the keys pressed and released by the user, dispatched as trusted keyboard events (https://w3c.github.io/uievents/#events-keyboardevents) to the focused element of the top-level browsing context.
ModifiersGets or sets the modifier keys that are pressed (the shiftKey, ctrlKey, altKey and metaKey of the events).
MouseGets the mouse of the user agent (its pointer always exists, https://w3c.github.io/pointerevents/#dfn-active-pointer).

Gets the keyboard of the user agent: the keys pressed and released by the user, dispatched as trusted keyboard events (https://w3c.github.io/uievents/#events-keyboardevents) to the focused element of the top-level browsing context.

public KeyboardInput Keyboard { get; }

Property value

KeyboardInput

Modifiers

UserInput.cs

Gets or sets the modifier keys that are pressed (the shiftKey, ctrlKey, altKey and metaKey of the events).

public InputModifiers Modifiers { get; set; }

Property value

InputModifiers

Gets the mouse of the user agent (its pointer always exists, https://w3c.github.io/pointerevents/#dfn-active-pointer).

public PointerInput Mouse { get; }

Property value

PointerInput

Methods

NameDescription
CreatePointer(string)Creates a pointer of the given type: touch (a finger: a new pointer of the touch screen for each contact), pen (a stylus that hovers) or mouse (returns UserInput.Mouse: there is a single mouse).
Drop(double, double, DragData)Drops data from outside the page at a position, as when the user drops files from the file manager: the mouse enters the viewport at the position with its button pressed (dragenter, dragover), then the button is released (drop when the page accepts the data, else dragleave). See PointerInput.BeginDrag to move over the page before the drop.
HitTest(double, double)Returns the element at a point of the viewport of the top-level browsing context, as the hit testing finds it (https://drafts.csswg.org/cssom-view/#hit-testing): not retargeted out of the shadow trees, and in the document of the nested browsing context when the point is in the content box of its container. The point of an empty area hits the document element. It returns null when the documents are not laid out (e.g. the document is not fully active).
MapFromVisualViewport(double, double)Maps a point of the visual viewport of the top-level document (a position of a screenshot, in CSS pixels: the pixels of the image divided by the device pixel ratio) to the viewport of the top-level browsing context, the coordinates of the input of the user (see PointerInput.Move). They differ when the user zoomed in (see UserInput.Pinch) and on a mobile device whose page is scaled (see ViewportOptions.IsMobile): the point is visualViewport.offsetLeft + x / visualViewport.scale.
MapToDocument(Document, double, double)Maps a point of the viewport of the top-level browsing context to the viewport of a document of a nested browsing context (the document of an iframe), through the transforms and the scroll offsets of the containers.
MapToTopLevel(Document, double, double)Maps a point of the viewport of a document (e.g. the coordinates of Element.GetBoundingClientRect in the document of an iframe) to the viewport of the top-level browsing context, through the transforms and the scroll offsets of the containers: the coordinates of the input of the user (see PointerInput.Move).
Pinch(double, double, double)Pinches the touchpad at a position of the viewport of the top-level browsing context (a pinch zoom, as with two fingers on the touchpad of a laptop): as in Chromium, a wheel event with ctrlKey set and a deltaY of -100 × ln(scale) is fired (see UserInput.Wheel) and, unless it is canceled, the visual viewport of the top-level document is zoomed by scale around the position: the point at the position stays where it is displayed. The zoom is between 1 and 5, or the maximum-scale of the viewport meta element (a page with user-scalable=no is not zoomed); on a mobile device (ViewportOptions.IsMobile), it multiplies the scale of the page. Returns whether the visual viewport was zoomed or scrolled.
Wheel(double, double, double, double)Rotates the wheel of the mouse at a position of the viewport of the top-level browsing context: a wheel event is fired at the element at the position (at the pointer-lock target while the mouse is locked; at the target of the wheel event transaction in progress, see below) and, unless it is canceled, the nearest scroll container that can scroll in the direction of the deltas (in CSS pixels) is scrolled, without snapping until the gesture of the wheel ends (at once, or 100 ms after the last wheel event when ViewportOptions.SmoothUserScrolling is set). Returns whether a scrolling box was scrolled.

CreatePointer(string)

UserInput.cs

Creates a pointer of the given type: touch (a finger: a new pointer of the touch screen for each contact), pen (a stylus that hovers) or mouse (returns UserInput.Mouse: there is a single mouse).

public PointerInput CreatePointer(string pointerType)

Parameters

pointerType string

Returns

PointerInput

Drop(double, double, DragData)

UserInput.cs

Drops data from outside the page at a position, as when the user drops files from the file manager: the mouse enters the viewport at the position with its button pressed (dragenter, dragover), then the button is released (drop when the page accepts the data, else dragleave). See PointerInput.BeginDrag to move over the page before the drop.

public void Drop(double x, double y, DragData data)

Parameters

x double
The horizontal position, in CSS pixels, relative to the viewport of the top-level browsing context.
y double
The vertical position, in CSS pixels, relative to the viewport of the top-level browsing context.
data DragData
The files, the directories and the strings that are dropped.

Exceptions

InvalidOperationException
A button of the mouse is pressed.

HitTest(double, double)

UserInput.cs

Returns the element at a point of the viewport of the top-level browsing context, as the hit testing finds it (https://drafts.csswg.org/cssom-view/#hit-testing): not retargeted out of the shadow trees, and in the document of the nested browsing context when the point is in the content box of its container. The point of an empty area hits the document element. It returns null when the documents are not laid out (e.g. the document is not fully active).

public Element? HitTest(double x, double y)

Parameters

x double
The horizontal position, in CSS pixels, relative to the viewport of the top-level browsing context.
y double
The vertical position, in CSS pixels, relative to the viewport of the top-level browsing context.

Returns

Element?

MapFromVisualViewport(double, double)

UserInput.Scrolling.cs

Maps a point of the visual viewport of the top-level document (a position of a screenshot, in CSS pixels: the pixels of the image divided by the device pixel ratio) to the viewport of the top-level browsing context, the coordinates of the input of the user (see PointerInput.Move). They differ when the user zoomed in (see UserInput.Pinch) and on a mobile device whose page is scaled (see ViewportOptions.IsMobile): the point is visualViewport.offsetLeft + x / visualViewport.scale.

public (double X, double Y) MapFromVisualViewport(double x, double y)

Parameters

x double
The horizontal position, in CSS pixels, relative to the visual viewport.
y double
The vertical position, in CSS pixels, relative to the visual viewport.

Returns

(double X, double Y)

MapToDocument(Document, double, double)

UserInput.cs

Maps a point of the viewport of the top-level browsing context to the viewport of a document of a nested browsing context (the document of an iframe), through the transforms and the scroll offsets of the containers.

public (double X, double Y) MapToDocument(Document document, double x, double y)

Parameters

document Document
A document of the top-level browsing context or of a nested browsing context.
x double
The horizontal position, in CSS pixels, relative to the viewport of the top-level browsing context.
y double
The vertical position, in CSS pixels, relative to the viewport of the top-level browsing context.

Returns

(double X, double Y)

MapToTopLevel(Document, double, double)

UserInput.cs

Maps a point of the viewport of a document (e.g. the coordinates of Element.GetBoundingClientRect in the document of an iframe) to the viewport of the top-level browsing context, through the transforms and the scroll offsets of the containers: the coordinates of the input of the user (see PointerInput.Move).

public static (double X, double Y) MapToTopLevel(Document document, double x, double y)

Parameters

document Document
A document of the top-level browsing context or of a nested browsing context.
x double
The horizontal position, in CSS pixels, relative to the viewport of the document.
y double
The vertical position, in CSS pixels, relative to the viewport of the document.

Returns

(double X, double Y)

Pinch(double, double, double)

UserInput.Scrolling.cs

Pinches the touchpad at a position of the viewport of the top-level browsing context (a pinch zoom, as with two fingers on the touchpad of a laptop): as in Chromium, a wheel event with ctrlKey set and a deltaY of -100 × ln(scale) is fired (see UserInput.Wheel) and, unless it is canceled, the visual viewport of the top-level document is zoomed by scale around the position: the point at the position stays where it is displayed. The zoom is between 1 and 5, or the maximum-scale of the viewport meta element (a page with user-scalable=no is not zoomed); on a mobile device (ViewportOptions.IsMobile), it multiplies the scale of the page. Returns whether the visual viewport was zoomed or scrolled.

public bool Pinch(double x, double y, double scale)

Parameters

x double
The horizontal position of the center of the pinch, in CSS pixels, relative to the viewport of the top-level browsing context.
y double
The vertical position of the center of the pinch, in CSS pixels, relative to the viewport of the top-level browsing context.
scale double
The factor by which the zoom is multiplied: greater than 1 to zoom in, less than 1 to zoom out.

Returns

bool

Wheel(double, double, double, double)

UserInput.Scrolling.cs

Rotates the wheel of the mouse at a position of the viewport of the top-level browsing context: a wheel event is fired at the element at the position (at the pointer-lock target while the mouse is locked; at the target of the wheel event transaction in progress, see below) and, unless it is canceled, the nearest scroll container that can scroll in the direction of the deltas (in CSS pixels) is scrolled, without snapping until the gesture of the wheel ends (at once, or 100 ms after the last wheel event when ViewportOptions.SmoothUserScrolling is set). Returns whether a scrolling box was scrolled.

public bool Wheel(double x, double y, double deltaX, double deltaY)

Parameters

x double
y double
deltaX double
deltaY double

Returns

bool

Remarks

The wheel events of a wheel event transaction (https://w3c.github.io/uievents/#wheel-event-transactions) are fired at the target of its first event, even when the scroll moves other contents under the pointer. A transaction ends when a wheel event is at another position (the mouse moved), 500 ms after its last wheel event (on the clock of the event loop), or when its target is removed from its document or stops generating a box.