Class InputSystemUIInputModule
Input module that takes its input from InputAction.
Inheritance
Inherited Members
Namespace: UnityEngine.InputSystem.UI
Syntax
[HelpURL("https://docs.unity3d.com/Packages/com.unity.inputsystem@1.7/manual/UISupport.html#setting-up-ui-input")]
public class InputSystemUIInputModule : BaseInputModuleRemarks
This UI input module has the advantage over other such modules that it doesn't have to know what devices and types of devices input is coming from. Instead, the actions hide the actual sources of input from the module.
When adding this component from code (such as through GameObject.AddComponent), the
resulting module will automatically have a set of default input actions assigned to it
(see AssignDefaultActions()).
Properties
actionsAsset
Declaration
public InputActionAsset actionsAsset { get; set; }Property Value
| Type | Description |
|---|---|
| InputActionAsset |
cancel
An InputAction delivering a float button value that determines when ICancelHandler
is triggered.
Declaration
public InputActionReference cancel { get; set; }Property Value
| Type | Description |
|---|---|
| InputActionReference |
Remarks
The events generated from this input will be received by UnityEngine.EventSystems.ICancelHandler.
This action together with move and submit form the sources for navigation-style UI input.
This action should have its type set to Button.
var asset = ScriptableObject.Create<InputActionAsset>();
var map = asset.AddActionMap("UI");
var pointAction = map.AddAction("move");
var submitAction = map.AddAction("submit");
var cancelAction = map.AddAction("cancel");
moveAction.AddBinding("<Gamepad>/*stick");
moveAction.AddBinding("<Gamepad>/dpad");
submitAction.AddBinding("<Gamepad>/buttonSouth");
cancelAction.AddBinding("<Gamepad>/buttonEast");
((InputSystemUIInputModule)EventSystem.current.currentInputModule).move =
InputActionReference.Create(moveAction);
((InputSystemUIInputModule)EventSystem.current.currentInputModule).submit =
InputActionReference.Create(submitAction);
((InputSystemUIInputModule)EventSystem.current.currentInputModule).cancelAction =
InputActionReference.Create(cancelAction);See Also
cursorLockBehavior
Where to position the pointer when the cursor is locked.
Declaration
public InputSystemUIInputModule.CursorLockBehavior cursorLockBehavior { get; set; }Property Value
| Type | Description |
|---|---|
| InputSystemUIInputModule.CursorLockBehavior |
Remarks
By default, the pointer is positioned at -1, -1 in screen space when the cursor is locked. This has implications for using ray casters like UnityEngine.EventSystems.PhysicsRaycaster because the raycasts will be sent from the pointer position. By setting the value of cursorLockBehavior to ScreenCenter, the raycasts will be sent from the center of the screen. This is useful when trying to interact with world space UI using the UnityEngine.EventSystems.IPointerEnterHandler and UnityEngine.EventSystems.IPointerExitHandler interfaces when the cursor is locked.
deselectOnBackgroundClick
Whether to clear the current selection when a click happens that does not hit any GameObject.
Declaration
public bool deselectOnBackgroundClick { get; set; }Property Value
| Type | Description |
|---|---|
| Boolean | If true (default), clicking outside of any GameObject will reset the current selection. |
Remarks
By toggling this behavior off, background clicks will keep the current selection. I.e.
EventSystem.currentSelectedGameObject will not be changed.
leftClick
An InputAction delivering a float button value that determines
whether the left button of a pointer is pressed.
Declaration
public InputActionReference leftClick { get; set; }Property Value
| Type | Description |
|---|---|
| InputActionReference |
Remarks
Clicks on this button will use UnityEngine.EventSystems.PointerEventData.InputButton.Left for UnityEngine.EventSystems.PointerEventData.button.
Together with point, rightClick, middleClick, and scrollWheel, this forms the basis for pointer-type UI input.
Note that together with point, this action is necessary for a pointer to be functional. The other clicks and scrollWheel are optional, however.
This action should have its type set to PassThrough and its
expectedControlType set to "Button".
var asset = ScriptableObject.Create<InputActionAsset>();
var map = asset.AddActionMap("UI");
var pointAction = map.AddAction("scroll");
var clickAction = map.AddAction("click");
pointAction.AddBinding("<Mouse>/position");
pointAction.AddBinding("<Touchscreen>/touch*/position");
clickAction.AddBinding("<Mouse>/leftButton");
clickAction.AddBinding("<Touchscreen>/touch*/press");
((InputSystemUIInputModule)EventSystem.current.currentInputModule).point =
InputActionReference.Create(pointAction);
((InputSystemUIInputModule)EventSystem.current.currentInputModule).leftClick =
InputActionReference.Create(clickAction);See Also
middleClick
An InputAction delivering a float button value that determines
whether the middle button of a pointer is pressed.
Declaration
public InputActionReference middleClick { get; set; }Property Value
| Type | Description |
|---|---|
| InputActionReference |
Remarks
Clicks on this button will use UnityEngine.EventSystems.PointerEventData.InputButton.Middle for UnityEngine.EventSystems.PointerEventData.button.
Together with leftClick, rightClick, scrollWheel, and point, this forms the basis for pointer-type UI input.
Note that the action is optional. A pointer is fully functional with just point and leftClick alone.
This action should have its type set to PassThrough and its
expectedControlType set to "Button".
var asset = ScriptableObject.Create<InputActionAsset>();
var map = asset.AddActionMap("UI");
var pointAction = map.AddAction("scroll");
var leftClickAction = map.AddAction("leftClick");
var middleClickAction = map.AddAction("middleClick");
pointAction.AddBinding("<Mouse>/position");
pointAction.AddBinding("<Touchscreen>/touch*/position");
leftClickAction.AddBinding("<Mouse>/leftButton");
leftClickAction.AddBinding("<Touchscreen>/touch*/press");
middleClickAction.AddBinding("<Mouse>/middleButton");
((InputSystemUIInputModule)EventSystem.current.currentInputModule).point =
InputActionReference.Create(pointAction);
((InputSystemUIInputModule)EventSystem.current.currentInputModule).leftClick =
InputActionReference.Create(leftClickAction);
((InputSystemUIInputModule)EventSystem.current.currentInputModule).middleClick =
InputActionReference.Create(middleClickAction);See Also
move
An InputAction delivering a Vector2 2D motion vector
used for sending UnityEngine.EventSystems.AxisEventData navigation events.
Declaration
public InputActionReference move { get; set; }Property Value
| Type | Description |
|---|---|
| InputActionReference |
Remarks
The events generated from this input will be received by UnityEngine.EventSystems.IMoveHandler.OnMove(UnityEngine.EventSystems.AxisEventData).
This action together with submit and cancel form the sources for navigation-style UI input.
This action should have its type set to PassThrough and its
expectedControlType set to "Vector2".
var asset = ScriptableObject.Create<InputActionAsset>();
var map = asset.AddActionMap("UI");
var pointAction = map.AddAction("move");
var submitAction = map.AddAction("submit");
var cancelAction = map.AddAction("cancel");
moveAction.AddBinding("<Gamepad>/*stick");
moveAction.AddBinding("<Gamepad>/dpad");
submitAction.AddBinding("<Gamepad>/buttonSouth");
cancelAction.AddBinding("<Gamepad>/buttonEast");
((InputSystemUIInputModule)EventSystem.current.currentInputModule).move =
InputActionReference.Create(moveAction);
((InputSystemUIInputModule)EventSystem.current.currentInputModule).submit =
InputActionReference.Create(submitAction);
((InputSystemUIInputModule)EventSystem.current.currentInputModule).cancelAction =
InputActionReference.Create(cancelAction);See Also
moveRepeatDelay
Delay in seconds between an initial move action and a repeated move action while move is actuated.
Declaration
public float moveRepeatDelay { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
Remarks
While move is being held down, the input module will first wait for moveRepeatDelay seconds after the first actuation of move and then trigger a move event every moveRepeatRate seconds.
See Also
moveRepeatRate
Delay in seconds between repeated move actions while move is actuated.
Declaration
public float moveRepeatRate { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
Remarks
While move is being held down, the input module will first wait for moveRepeatDelay seconds after the first actuation of move and then trigger a move event every moveRepeatRate seconds.
Note that a maximum of one UnityEngine.EventSystems.AxisEventData will be sent per frame. This means that even if multiple time increments of the repeat delay have passed since the last update, only one move repeat event will be generated.
See Also
point
An InputAction delivering a Vector2 2D screen position used as a cursor for pointing at UI elements.
Declaration
public InputActionReference point { get; set; }Property Value
| Type | Description |
|---|---|
| InputActionReference |
Remarks
The values read from this action determine UnityEngine.EventSystems.PointerEventData.position and UnityEngine.EventSystems.PointerEventData.delta.
Together with leftClick, rightClick, middleClick, and scrollWheel, this forms the basis for pointer-type UI input.
This action should have its type set to PassThrough and its
expectedControlType set to "Vector2".
var asset = ScriptableObject.Create<InputActionAsset>();
var map = asset.AddActionMap("UI");
var pointAction = map.AddAction("Point");
pointAction.AddBinding("<Mouse>/position");
pointAction.AddBinding("<Touchscreen>/touch*/position");
((InputSystemUIInputModule)EventSystem.current.currentInputModule).point =
InputActionReference.Create(pointAction);See Also
pointerBehavior
How to deal with the presence of pointer-type input from multiple devices.
Declaration
public UIPointerBehavior pointerBehavior { get; set; }Property Value
| Type | Description |
|---|---|
| UIPointerBehavior |
Remarks
By default, this is set to SingleMouseOrPenButMultiTouchAndTrack which will treat input from Mouse and Pen devices as coming from a single on-screen pointer but will treat input from devices such as XRController and Touchscreen as their own discrete pointers.
The primary effect of this setting is to determine whether the user can concurrently point at more than a single UI element or not. Whenever multiple pointers are allowed, more than one element may have a pointer over it at any one point and thus several elements can be interacted with concurrently.
rightClick
An InputAction delivering a float" button value that determines
whether the right button of a pointer is pressed.
Declaration
public InputActionReference rightClick { get; set; }Property Value
| Type | Description |
|---|---|
| InputActionReference |
Remarks
Clicks on this button will use UnityEngine.EventSystems.PointerEventData.InputButton.Right for UnityEngine.EventSystems.PointerEventData.button.
Together with leftClick, middleClick, scrollWheel, and point, this forms the basis for pointer-type UI input.
Note that the action is optional. A pointer is fully functional with just point and leftClick alone.
This action should have its type set to PassThrough and its
expectedControlType set to "Button".
var asset = ScriptableObject.Create<InputActionAsset>();
var map = asset.AddActionMap("UI");
var pointAction = map.AddAction("scroll");
var leftClickAction = map.AddAction("leftClick");
var rightClickAction = map.AddAction("rightClick");
pointAction.AddBinding("<Mouse>/position");
pointAction.AddBinding("<Touchscreen>/touch*/position");
leftClickAction.AddBinding("<Mouse>/leftButton");
leftClickAction.AddBinding("<Touchscreen>/touch*/press");
rightClickAction.AddBinding("<Mouse>/rightButton");
((InputSystemUIInputModule)EventSystem.current.currentInputModule).point =
InputActionReference.Create(pointAction);
((InputSystemUIInputModule)EventSystem.current.currentInputModule).leftClick =
InputActionReference.Create(leftClickAction);
((InputSystemUIInputModule)EventSystem.current.currentInputModule).rightClick =
InputActionReference.Create(rightClickAction);See Also
scrollWheel
An InputAction delivering a Vector2 scroll wheel value
used for sending UnityEngine.EventSystems.PointerEventData events.
Declaration
public InputActionReference scrollWheel { get; set; }Property Value
| Type | Description |
|---|---|
| InputActionReference |
Remarks
The values read from this action determine UnityEngine.EventSystems.PointerEventData.scrollDelta.
Together with leftClick, rightClick, middleClick, and point, this forms the basis for pointer-type UI input.
Note that the action is optional. A pointer is fully functional with just point and leftClick alone.
This action should have its type set to PassThrough and its
expectedControlType set to "Vector2".
var asset = ScriptableObject.Create<InputActionAsset>();
var map = asset.AddActionMap("UI");
var pointAction = map.AddAction("scroll");
var scrollAction = map.AddAction("scroll");
pointAction.AddBinding("<Mouse>/position");
pointAction.AddBinding("<Touchscreen>/touch*/position");
scrollAction.AddBinding("<Mouse>/scroll");
((InputSystemUIInputModule)EventSystem.current.currentInputModule).point =
InputActionReference.Create(pointAction);
((InputSystemUIInputModule)EventSystem.current.currentInputModule).scrollWheel =
InputActionReference.Create(scrollAction);See Also
submit
An InputAction delivering a float button value that determines when ISubmitHandler
is triggered.
Declaration
public InputActionReference submit { get; set; }Property Value
| Type | Description |
|---|---|
| InputActionReference |
Remarks
The events generated from this input will be received by UnityEngine.EventSystems.ISubmitHandler.
This action together with move and cancel form the sources for navigation-style UI input.
This action should have its type set to Button.
var asset = ScriptableObject.Create<InputActionAsset>();
var map = asset.AddActionMap("UI");
var pointAction = map.AddAction("move");
var submitAction = map.AddAction("submit");
var cancelAction = map.AddAction("cancel");
moveAction.AddBinding("<Gamepad>/*stick");
moveAction.AddBinding("<Gamepad>/dpad");
submitAction.AddBinding("<Gamepad>/buttonSouth");
cancelAction.AddBinding("<Gamepad>/buttonEast");
((InputSystemUIInputModule)EventSystem.current.currentInputModule).move =
InputActionReference.Create(moveAction);
((InputSystemUIInputModule)EventSystem.current.currentInputModule).submit =
InputActionReference.Create(submitAction);
((InputSystemUIInputModule)EventSystem.current.currentInputModule).cancelAction =
InputActionReference.Create(cancelAction);See Also
trackedDeviceDragThresholdMultiplier
Scales the drag threshold of EventSystem for tracked devices to make selection easier.
Declaration
public float trackedDeviceDragThresholdMultiplier { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
trackedDeviceOrientation
An InputAction delivering a Quaternion value reflecting the orientation of TrackedDevices.
In combination with trackedDevicePosition, this is used to determine the transform of tracked devices from which
to raycast into the UI scene.
Declaration
public InputActionReference trackedDeviceOrientation { get; set; }Property Value
| Type | Description |
|---|---|
| InputActionReference |
Remarks
trackedDeviceOrientation and trackedDevicePosition together replace point for UI input from TrackedDevice. Other than that, UI input for tracked devices is no different from "normal" pointer-type input. This means that leftClick, rightClick, middleClick, and scrollWheel can all be used for tracked device input like for regular pointer input.
This action should have its type set to PassThrough and its
expectedControlType set to "Quaternion".
var asset = ScriptableObject.Create<InputActionAsset>();
var map = asset.AddActionMap("UI");
var positionAction = map.AddAction("position");
var orientationAction = map.AddAction("orientation");
var clickAction = map.AddAction("click");
positionAction.AddBinding("<TrackedDevice>/devicePosition");
orientationAction.AddBinding("<TrackedDevice>/deviceRotation");
clickAction.AddBinding("<TrackedDevice>/trigger");
((InputSystemUIInputModule)EventSystem.current.currentInputModule).trackedDevicePosition =
InputActionReference.Create(positionAction);
((InputSystemUIInputModule)EventSystem.current.currentInputModule).trackedDeviceOrientation =
InputActionReference.Create(orientationAction);
((InputSystemUIInputModule)EventSystem.current.currentInputModule).leftClick =
InputActionReference.Create(clickAction);See Also
trackedDevicePosition
An InputAction delivering a Vector3 value reflecting the position of TrackedDevices.
In combination with trackedDeviceOrientation, this is used to determine the transform of tracked devices from which
to raycast into the UI scene.
Declaration
public InputActionReference trackedDevicePosition { get; set; }Property Value
| Type | Description |
|---|---|
| InputActionReference |
Remarks
trackedDeviceOrientation and trackedDevicePosition together replace point for UI input from TrackedDevice. Other than that, UI input for tracked devices is no different from "normal" pointer-type input. This means that leftClick, rightClick, middleClick, and scrollWheel can all be used for tracked device input like for regular pointer input.
This action should have its type set to PassThrough and its
expectedControlType set to "Vector3".
var asset = ScriptableObject.Create<InputActionAsset>();
var map = asset.AddActionMap("UI");
var positionAction = map.AddAction("position");
var orientationAction = map.AddAction("orientation");
var clickAction = map.AddAction("click");
positionAction.AddBinding("<TrackedDevice>/devicePosition");
orientationAction.AddBinding("<TrackedDevice>/deviceRotation");
clickAction.AddBinding("<TrackedDevice>/trigger");
((InputSystemUIInputModule)EventSystem.current.currentInputModule).trackedDevicePosition =
InputActionReference.Create(positionAction);
((InputSystemUIInputModule)EventSystem.current.currentInputModule).trackedDeviceOrientation =
InputActionReference.Create(orientationAction);
((InputSystemUIInputModule)EventSystem.current.currentInputModule).leftClick =
InputActionReference.Create(clickAction);See Also
xrTrackingOrigin
A Transform representing the real world origin for tracking devices. This is used to convert real world positions and rotations for Tracked pointers into Unity's global space. When using the XR Interaction Toolkit, this should be pointing to the XR Rig's Transform.
Declaration
public Transform xrTrackingOrigin { get; set; }Property Value
| Type | Description |
|---|---|
| Transform |
Remarks
This will transform all tracked pointers. If unset, or set to null, the Unity world origin will be used as the basis for all tracked positions and rotations.
Methods
ActivateModule()
Called by EventSystem when the input module is made current.
Declaration
public override void ActivateModule()Overrides
AssignDefaultActions()
Assigns default input actions asset and input actions, similar to how defaults are assigned when creating UI module in editor. Useful for creating InputSystemUIInputModule at runtime.
Declaration
public void AssignDefaultActions()Remarks
This instantiates DefaultInputActions and assigns it to actionsAsset. It also assigns all the various individual actions such as point and leftClick.
Note that if an InputSystemUIInputModule component is programmatically added to a GameObject,
it will automatically receive the default actions as part of its OnEnable method. Use UnassignActions()
to remove these assignments.
var go = new GameObject();
go.AddComponent<EventSystem>();
// Adding the UI module like this will implicitly enable it and thus lead to
// automatic assignment of the default input actions.
var uiModule = go.AddComponent<InputSystemUIInputModule>();
// Manually remove the default input actions.
uiModule.UnassignActions();See Also
Awake()
Declaration
protected override void Awake()Overrides
GetLastRaycastResult(Int32)
Returns the most recent raycast information for a given pointer or touch.
Declaration
public RaycastResult GetLastRaycastResult(int pointerOrTouchId)Parameters
| Type | Name | Description |
|---|---|---|
| Int32 | pointerOrTouchId | ID of the pointer or touch. Meaning this should correspond to either
Negative values will return an invalid UnityEngine.EventSystems.RaycastResult. |
Returns
| Type | Description |
|---|---|
| UnityEngine.EventSystems.RaycastResult | The most recent raycast information. |
Remarks
This method is for the most recent raycast, but depending on when it's called is not guaranteed to be for the current frame.
This method can be used to determine raycast distances and hit information for visualization.
Use UnityEngine.EventSystems.RaycastResult.isValid to determine if pointer hit anything.
See Also
IsPointerOverGameObject(Int32)
Check whether the given pointer or touch is currently hovering over a GameObject.
Declaration
public override bool IsPointerOverGameObject(int pointerOrTouchId)Parameters
| Type | Name | Description |
|---|---|---|
| Int32 | pointerOrTouchId | ID of the pointer or touch. Meaning this should correspond to either
Note that for touch, a pointer will stay valid for one frame before being removed. In other words,
when Ended or Canceled is received for a touch
and the touch was over a To check whether any pointer is over a |
Returns
| Type | Description |
|---|---|
| Boolean | True if the given pointer is currently hovering over a |
Overrides
Remarks
The result is true if the given pointer has caused an IPointerEnter event to be sent to a
GameObject.
This method can be invoked via EventSystem.current.IsPointerOverGameObject.
Be aware that this method relies on state set up during UI event processing that happens in EventSystem.Update,
that is, as part of MonoBehaviour updates. This step happens after input processing.
Thus, calling this method earlier than that in the frame will make it poll state from last frame.
Calling this method from within an InputAction callback (such as performed) will result in a warning. See the "UI vs Game Input" sample shipped with the Input System package for how to deal with this fact.
// In general, the pointer ID corresponds to the device ID:
EventSystem.current.IsPointerOverGameObject(XRController.leftHand.deviceId);
EventSystem.current.IsPointerOverGameObject(Mouse.current.deviceId);
// For touch input, pass the ID of a touch:
EventSystem.current.IsPointerOverGameObject(Touchscreen.primaryTouch.touchId.ReadValue());
// But can also pass the ID of the entire Touchscreen in which case the result
// is true if any touch is over a GameObject:
EventSystem.current.IsPointerOverGameObject(Touchscreen.current.deviceId);
// Finally, any negative value will be interpreted as "any pointer" and will
// return true if any one pointer is currently over a GameObject:
EventSystem.current.IsPointerOverGameObject(-1);
EventSystem.current.IsPointerOverGameObject(); // Equivalent.See Also
OnDestroy()
Declaration
protected override void OnDestroy()Overrides
OnDisable()
Declaration
protected override void OnDisable()Overrides
OnEnable()
Declaration
protected override void OnEnable()Overrides
Process()
Declaration
public override void Process()Overrides
UnassignActions()
Remove all action assignments, that is actionsAsset as well as all individual actions such as leftClick.
Declaration
public void UnassignActions()Remarks
If the current actions were enabled by the UI input module, they will be disabled in the process.