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 UserInputProperties
| Name | Description |
|---|---|
| Keyboard | 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. |
| Modifiers | Gets or sets the modifier keys that are pressed (the shiftKey, ctrlKey, altKey and metaKey of the events). |
| Mouse | Gets the mouse of the user agent (its pointer always exists, https://w3c.github.io/pointerevents/#dfn-active-pointer). |
Keyboard
UserInput.Keyboard.csGets 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
Modifiers
UserInput.csGets or sets the modifier keys that are pressed (the shiftKey, ctrlKey, altKey and metaKey of the events).
public InputModifiers Modifiers { get; set; }Property value
Mouse
UserInput.csGets the mouse of the user agent (its pointer always exists, https://w3c.github.io/pointerevents/#dfn-active-pointer).
public PointerInput Mouse { get; }Property value
Methods
| Name | Description |
|---|---|
| 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.csCreates 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)Drop(double, double, DragData)
UserInput.csDrops 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.
Parameters
xdouble- The horizontal position, in CSS pixels, relative to the viewport of the top-level browsing context.
ydouble- The vertical position, in CSS pixels, relative to the viewport of the top-level browsing context.
dataDragData- The files, the directories and the strings that are dropped.
Exceptions
InvalidOperationException- A button of the mouse is pressed.
HitTest(double, double)
UserInput.csReturns 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)
UserInput.Scrolling.csMaps 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)
UserInput.csMaps 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.
Parameters
documentDocument- A document of the top-level browsing context or of a nested browsing context.
xdouble- The horizontal position, in CSS pixels, relative to the viewport of the top-level browsing context.
ydouble- The vertical position, in CSS pixels, relative to the viewport of the top-level browsing context.
Returns
MapToTopLevel(Document, double, double)
UserInput.csMaps 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)
UserInput.Scrolling.csPinches 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.
Parameters
xdouble- The horizontal position of the center of the pinch, in CSS pixels, relative to the viewport of the top-level browsing context.
ydouble- The vertical position of the center of the pinch, in CSS pixels, relative to the viewport of the top-level browsing context.
scaledouble- The factor by which the zoom is multiplied: greater than 1 to zoom in, less than 1 to zoom out.
Returns
Wheel(double, double, double, double)
UserInput.Scrolling.csRotates 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.
Parameters
Returns
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.