Class Touchscreen

A multi-touch surface.

Inheritance
Object
InputControl
InputDevice
Pointer
Touchscreen
Inherited Members
Namespace: UnityEngine.InputSystem
Syntax
public class Touchscreen : Pointer, IInputStateCallbackReceiver, IEventMerger, ICustomDeviceReset
Remarks

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; protected set; }
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.

touchControlArray

Declaration
protected TouchControl[] touchControlArray { get; set; }
Property Value
Type Description
TouchControl[]

touches

Array of all TouchControls on the device.

Declaration
public ReadOnlyArray<TouchControl> touches { get; protected set; }
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. Hence why 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
Implements

Extension Methods