docs.unity3d.com
    Show / Hide Table of Contents

    Class VirtualMouseInput

    A component that creates a virtual Mouse device and drives its input from gamepad-style inputs. This effectively adds a software mouse cursor.

    Inheritance
    Object
    VirtualMouseInput
    Namespace: UnityEngine.InputSystem.UI
    Syntax
    public class VirtualMouseInput : MonoBehaviour
    Remarks

    This component can be used with UIs that are designed for mouse input, i.e. need to be operated with a cursor. By hooking up the InputActions of this component to gamepad input and directing cursorTransform to the UI transform of the cursor, you can use this component to drive an on-screen cursor.

    Note that this component does not actually trigger UI input itself. Instead, it creates a virtual Mouse device which can then be picked up elsewhere (such as by InputSystemUIInputModule) where mouse/pointer input is expected.

    Also note that if there is a Mouse added by the platform, it is not impacted by this component. More specifically, the system mouse cursor will not be moved or otherwise used by this component.

    Input from the component is visible in the same frame as the source input on its actions by virtue of using Change(InputDevice, InputEventPtr, InputUpdateType).

    Properties

    backButtonAction

    Optional button input that determines when forwardButton is pressed on virtualMouse.

    Declaration
    public InputActionProperty backButtonAction { get; set; }
    Property Value
    Type Description
    InputActionProperty

    Input for forwardButton.

    cursorGraphic

    The UI graphic element that represents the mouse cursor.

    Declaration
    public Graphic cursorGraphic { get; set; }
    Property Value
    Type Description
    Graphic

    Graphic element for the software mouse cursor.

    Remarks

    If cursorMode is set to HardwareCursorIfAvailable, this graphic will be disabled.

    Also, this UI component implicitly determines the Canvas that defines the screen area for the cursor. The canvas that this graphic is on will be looked up using GetComponentInParent and then the Canvas.pixelRect of the canvas is used as the bounds for the cursor motion range.

    See Also
    SoftwareCursor

    cursorMode

    Determines which cursor representation to use. If this is set to SoftwareCursor (the default), then cursorGraphic and cursorTransform define a software cursor that is made to correspond to the position of virtualMouse. If this is set to HardwareCursorIfAvailable and there is a native Mouse device present, the component will take over that mouse device and disable it (so as for it to not also generate position updates). It will then use WarpCursorPosition(Vector2) to move the system mouse cursor to correspond to the position of the virtualMouse. In this case, cursorGraphic will be disabled and cursorTransform will not be updated.

    Declaration
    public VirtualMouseInput.CursorMode cursorMode { get; set; }
    Property Value
    Type Description
    VirtualMouseInput.CursorMode

    Whether the system mouse cursor (if present) should be made to correspond with the virtual mouse position.

    Remarks

    Note that regardless of which mode is used for the cursor, mouse input is expected to be picked up from virtualMouse.

    Note that if HardwareCursorIfAvailable is used, the software cursor is still used if no native Mouse device is present.

    cursorSpeed

    How many pixels per second the cursor travels in one axis when the respective axis from stickAction is 1.

    Declaration
    public float cursorSpeed { get; set; }
    Property Value
    Type Description
    Single

    Mouse speed in pixels per second.

    cursorTransform

    Optional transform that will be updated to correspond to the current mouse position.

    Declaration
    public RectTransform cursorTransform { get; set; }
    Property Value
    Type Description
    RectTransform

    Transform to update with mouse position.

    Remarks

    This is useful for having a UI object that directly represents the mouse cursor. Simply add both the VirtualMouseInput component and an Image component and hook the RectTransform component for the UI object into here. The object as a whole will then follow the generated mouse cursor motion.

    forwardButtonAction

    Optional button input that determines when forwardButton is pressed on virtualMouse.

    Declaration
    public InputActionProperty forwardButtonAction { get; set; }
    Property Value
    Type Description
    InputActionProperty

    Input for forwardButton.

    leftButtonAction

    Optional button input that determines when leftButton is pressed on virtualMouse.

    Declaration
    public InputActionProperty leftButtonAction { get; set; }
    Property Value
    Type Description
    InputActionProperty

    Input for leftButton.

    middleButtonAction

    Optional button input that determines when middleButton is pressed on virtualMouse.

    Declaration
    public InputActionProperty middleButtonAction { get; set; }
    Property Value
    Type Description
    InputActionProperty

    Input for middleButton.

    rightButtonAction

    Optional button input that determines when rightButton is pressed on virtualMouse.

    Declaration
    public InputActionProperty rightButtonAction { get; set; }
    Property Value
    Type Description
    InputActionProperty

    Input for rightButton.

    scrollSpeed

    Multiplier for values received from scrollWheelAction.

    Declaration
    public float scrollSpeed { get; set; }
    Property Value
    Type Description
    Single

    Multiplier for scroll values.

    scrollWheelAction

    Optional Vector2 value input that determines the value of scroll on virtualMouse.

    Declaration
    public InputActionProperty scrollWheelAction { get; set; }
    Property Value
    Type Description
    InputActionProperty

    Input for scroll.

    Remarks

    In case you want to only bind vertical scrolling, simply have a Vector2Composite with only Up and Down bound and Left and Right deleted or bound to nothing.

    stickAction

    The Vector2 stick input that drives the mouse cursor, i.e. position on virtualMouse and the anchoredPosition on cursorTransform (if set).

    Declaration
    public InputActionProperty stickAction { get; set; }
    Property Value
    Type Description
    InputActionProperty

    Stick input that drives cursor position.

    Remarks

    This should normally be bound to controls such as leftStick and/or rightStick.

    virtualMouse

    The virtual mouse device that the component feeds with input.

    Declaration
    public Mouse virtualMouse { get; }
    Property Value
    Type Description
    Mouse

    Instance of virtual mouse or null.

    Remarks

    This is only initialized after the component has been enabled for the first time. Note that when subsequently disabling the component, the property will continue to return the mouse device but the device will not be added to the system while the component is not enabled.

    Methods

    OnDisable()

    Declaration
    protected void OnDisable()

    OnEnable()

    Declaration
    protected void OnEnable()

    See Also

    Gamepad
    Mouse
    Back to top
    Terms of use
    Copyright © 2023 Unity Technologies — Terms of use
    • Legal
    • Privacy Policy
    • Cookies
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)
    "Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.
    Generated by DocFX on 18 October 2023