Class Touchscreen
A multi-touch surface.
Inherited Members
Namespace: UnityEngine.InputSystem
Syntax
[Preserve]
public class Touchscreen : Pointer, IInputStateCallbackReceiverRemarks
Touchscreen is somewhat different from most other device implementations in that it does not usually
consume input in the form of a full device snapshot but rather consumes input sent to it in the form
of events containing a TouchState each. This is unusual as TouchState
uses a memory format different from Format. However, when a Touchscreen
sees an event containing a TouchState, it will handle that event on a special code path.
This allows Touchscreen to decide on its own which control in touches to store
a touch at and to perform things such as tap detection (see tap and
tapCount) and primary touch handling (see primaryTouch).
// Create a touchscreen device.
var touchscreen = InputSystem.AddDevice<Touchscreen>();
// Send a touch to the device.
InputSystem.QueueStateEvent(touchscreen,
new TouchState
{
phase = TouchPhase.Began,
// Must have a valid, non-zero touch ID. Touchscreen will not operate
// correctly if we don't set IDs properly.
touchId = 1,
position = new Vector2(123, 234),
// Delta will be computed by Touchscreen automatically.
});Note that this class presents a fairly low-level touch API. When working with touch from script code, it is recommended to use the higher-level Touch API instead.
Properties
current
The touchscreen that was added or updated last or null if there is no touchscreen connected to the system.
Declaration
public static Touchscreen current { get; }Property Value
| Type | Description |
|---|---|
| Touchscreen | Current touch screen. |
primaryTouch
Synthetic control that has the data for the touch that is deemed the "primary" touch at the moment.
Declaration
public TouchControl primaryTouch { get; }Property Value
| Type | Description |
|---|---|
| TouchControl | Control tracking the screen's primary touch. |
Remarks
This touch duplicates touch data from whichever touch is deemed the primary touch at the moment. When going from no fingers down to any finger down, the first finger to touch the screen is deemed the "primary touch". It stays the primary touch until the last finger is released.
Note that unlike the touch from which it originates, the primary touch will be kept ongoing for
as long as there is still a finger on the screen. Put another way, phase
of primaryTouch will only transition to Ended once the last finger
has been lifted off the screen.
touches
Array of all TouchControls on the device.
Declaration
public ReadOnlyArray<TouchControl> touches { get; }Property Value
| Type | Description |
|---|---|
| ReadOnlyArray<TouchControl> | All TouchControls on the screen. |
Remarks
By default, a touchscreen will allocate 10 touch controls. This can be changed by modifying the "Touchscreen" layout itself or by derived layouts. In practice, this means that this array will usually have a fixed length of 10 entries but it may deviate from that.
Methods
FinishSetup()
Perform final initialization tasks after the control hierarchy has been put into place.
Declaration
protected override void FinishSetup()Overrides
Remarks
This method can be overridden to perform control- or device-specific setup work. The most common use case is for looking up child controls and storing them in local getters.
public class MyDevice : InputDevice
{
public ButtonControl button { get; private set; }
public AxisControl axis { get; private set; }
protected override void OnFinishSetup()
{
// Cache controls in getters.
button = GetChildControl("button");
axis = GetChildControl("axis");
}
}MakeCurrent()
Make this the current device of its type.
Declaration
public override void MakeCurrent()Overrides
Remarks
This method is called automatically by the input system when a device is
added or when input is received on it. Many types of devices have .current
getters that allow querying the last used device of a specific type directly (for
example, see current).
There is one special case, however, related to noise. A device that has noisy controls (i.e. controls for which noisy is true) may receive input events that contain no meaningful user interaction but are simply just noise from the device. A good example of this is the PS4 gamepad which has a built-in gyro and may thus constantly feed events into the input system even if not being actually in use. If, for example, an Xbox gamepad and PS4 gamepad are both connected to a PC and the user is playing with the Xbox gamepad, the PS4 gamepad would still constantly make itself current by simply flooding the system with events.
By enabling filterNoiseOnCurrent (disabled by default),
noise on .current getters will be filtered out and a device will only see MakeCurrent
getting called if there input was detected on non-noisy controls.
See Also
OnNextUpdate()
Declaration
protected void OnNextUpdate()OnRemoved()
Called by the system when the device is removed from devices.
Declaration
protected override void OnRemoved()Overrides
Remarks
This is called after the device has already been removed.
See Also
OnStateEvent(InputEventPtr)
Called whenever a new state event is received.
Declaration
protected void OnStateEvent(InputEventPtr eventPtr)Parameters
| Type | Name | Description |
|---|---|---|
| InputEventPtr | eventPtr |
Explicit Interface Implementations
IInputStateCallbackReceiver.GetStateOffsetForEvent(InputControl, InputEventPtr, ref UInt32)
Declaration
bool IInputStateCallbackReceiver.GetStateOffsetForEvent(InputControl control, InputEventPtr eventPtr, ref uint offset)Parameters
| Type | Name | Description |
|---|---|---|
| InputControl | control | |
| InputEventPtr | eventPtr | |
| UInt32 | offset |
Returns
| Type | Description |
|---|---|
| Boolean |
Implements
IInputStateCallbackReceiver.OnNextUpdate()
Declaration
void IInputStateCallbackReceiver.OnNextUpdate()Implements
IInputStateCallbackReceiver.OnStateEvent(InputEventPtr)
Declaration
void IInputStateCallbackReceiver.OnStateEvent(InputEventPtr eventPtr)Parameters
| Type | Name | Description |
|---|---|---|
| InputEventPtr | eventPtr |