Struct Touch

A high-level representation of a touch which automatically keeps track of a touch over time.

Namespace: UnityEngine.InputSystem.EnhancedTouch

Syntax

public struct Touch : IEquatable<Touch>

Remarks

This API obsoletes the need for manually keeping tracking of touch IDs (touchId) and touch phases (phase) in order to tell one touch apart from another.

Also, this class protects against losing touches. If a touch is shorter-lived than a single input update, Touchscreen may overwrite it with a new touch coming in in the same update whereas this class will retain all changes that happened on the touchscreen in any particular update.

The API makes a distinction between "fingers" and "touches". A touch refers to one contact state change event, i.e. a finger beginning to touch the screen (Began), moving on the screen (Moved), or being lifted off the screen (Ended or Canceled). A finger, on the other hand, always refers to the Nth contact on the screen.

A Touch instance is a struct which only contains a reference to the actual data which is stored in unmanaged memory.

Properties

activeFingers

Declaration

public static ReadOnlyArray<Finger> activeFingers { get; }

Property Value

Type	Description
ReadOnlyArray<Finger>

activeTouches

All touches that are either on-going as of the current frame or have ended in the current frame.

Declaration

public static ReadOnlyArray<Touch> activeTouches { get; }

Property Value

Type	Description
ReadOnlyArray<Touch>

Remarks

Note that the fact that ended touches are being kept around until the end of a frame means that this array may have more touches than the total number of concurrent touches supported by the system.

delta

Screen-space motion delta of the touch.

Declaration

public Vector2 delta { get; }

Property Value

Type	Description
Vector2	Screen-space motion delta of the touch.

Remarks

Note that deltas have behaviors attached to them different from most other controls. See delta for details.

See Also

delta

finger

The finger used for the touch contact. Null only for default-initialized instances of the struct.

Declaration

public Finger finger { get; }

Property Value

Type	Description
Finger	Finger used for the touch contact.

See Also

activeFingers

fingers

Declaration

public static ReadOnlyArray<Finger> fingers { get; }

Property Value

Type	Description
ReadOnlyArray<Finger>

Remarks

The length of this array will always correspond to the maximum number of concurrent touches supported by the system.

history

History for this specific touch.

Declaration

public TouchHistory history { get; }

Property Value

Type	Description
TouchHistory

Remarks

Unlike touchHistory, this gives the history of this touch only.

isInProgress

Whether the touch is currently in progress, i.e. has a phase of Began, Moved, or Stationary.

Declaration

public bool isInProgress { get; }

Property Value

Type	Description
Boolean	Whether the touch is currently ongoing.

isTap

Whether the touch has performed a tap.

Declaration

public bool isTap { get; }

Property Value

Type	Description
Boolean	Indicates whether the touch has tapped the screen.

Remarks

A tap is defined as a touch that begins and ends within defaultTapTime and stays within tapRadius of its startScreenPosition. If this is the case for a touch, this button is set to 1 at the time the touch goes to phase Ended.

Resets to 0 only when another touch is started on the control or when the control is reset.

See Also

tapCount

defaultTapTime

tap

maxHistoryLengthPerFinger

The amount of history kept for each single touch.

Declaration

public static int maxHistoryLengthPerFinger { get; }

Property Value

Type	Description
Int32

Remarks

By default, this is zero meaning that no history information is kept for touches. Setting this to Int32.maxValue will cause all history from the beginning to the end of a touch being kept.

phase

Current phase of the touch.

Declaration

public TouchPhase phase { get; }

Property Value

Type	Description
TouchPhase	Current phase of the touch.

Remarks

Every touch goes through a predefined cycle that starts with Began, then potentially Moved and/or Stationary, and finally concludes with either Ended or Canceled.

This property indicates where in the cycle the touch is.

See Also

isInProgress

phase

pressure

Normalized pressure of the touch against the touch surface.

Declaration

public float pressure { get; }

Property Value

Type	Description
Single	Pressure level of the touch.

Remarks

Not all touchscreens are pressure-sensitive. If unsupported, this property will always return 0.

In general, touch pressure is supported on mobile platforms only.

Note that it is possible for the value to go above 1 even though it is considered normalized. The reason is that calibration on the system can put the maximum pressure point below the physically supported maximum value.

See Also

pressure

radius

Screen-space radius of the touch.

Declaration

public Vector2 radius { get; }

Property Value

Type	Description
Vector2	Horizontal and vertical extents of the touch contact.

Remarks

If supported by the underlying device, this reports the size of the touch contact based on its screenPosition center point. If not supported, this will be default(Vector2).

See Also

radius

screen

The touchscreen on which the touch occurred.

Declaration

public Touchscreen screen { get; }

Property Value

Type	Description
Touchscreen	Touchscreen associated with the touch.

screenPosition

Screen-space position of the touch.

Declaration

public Vector2 screenPosition { get; }

Property Value

Type	Description
Vector2	Screen-space position of the touch.

See Also

position

screens

Declaration

public static IEnumerable<Touchscreen> screens { get; }

Property Value

Type	Description
IEnumerable<Touchscreen>

startScreenPosition

Screen-space position where the touch started.

Declaration

public Vector2 startScreenPosition { get; }

Property Value

Type	Description
Vector2	Start position of the touch.

See Also

startPosition

startTime

Time in seconds on the same timeline as Time.realTimeSinceStartup when the touch began.

Declaration

public double startTime { get; }

Property Value

Type	Description
Double	Start time of the touch.

Remarks

This is the value of time when the touch started with phase Began.

See Also

startTime

tapCount

Number of times that the touch has been tapped in succession.

Declaration

public int tapCount { get; }

Property Value

Type	Description
Int32	Indicates how many taps have been performed one after the other.

Remarks

Successive taps have to come within multiTapDelayTime for them to increase the tap count. I.e. if a new tap finishes within that time after startTime of the previous touch, the tap count is increased by one. If more than multiTapDelayTime passes after a tap with no successive tap, the tap count is reset to zero.

See Also

tapCount

time

Time in seconds on the same timeline as Time.realTimeSinceStartup when the touch record was reported.

Declaration

public double time { get; }

Property Value

Type	Description
Double	Time the touch record was reported.

Remarks

This is the value time of the event that signaled the current state change for the touch.

touchId

Unique ID of the touch as (usually) assigned by the platform.

Declaration

public int touchId { get; }

Property Value

Type	Description
Int32	Unique, non-zero ID of the touch.

Remarks

Each touch contact that is made with the screen receives its own unique ID which is normally assigned by the underlying platform.

Note a platform may reuse touch IDs after their respective touches have finished. This means that the guarantee of uniqueness is only made with respect to activeTouches.

In particular, all touches in history will have the same ID whereas touches in the a finger's touchHistory may end up having the same touch ID even though constituting different physical touch contacts.

See Also

touchId

valid

Whether this touch record holds valid data.

Declaration

public bool valid { get; }

Property Value

Type	Description
Boolean	If true, the data contained in the touch is valid.

Remarks

Touch data is stored in unmanaged memory as a circular input buffer. This means that when the buffer runs out of capacity, older touch entries will get reused. When this happens, existing Touch instances referring to the record become invalid.

This property can be used to determine whether the record held on to by the Touch instance is still valid.

This property will be false for default-initialized Touch instances.

Note that accessing most of the other properties on this struct when the touch is invalid will trigger InvalidOperationException.

Methods

Equals(Object)

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
Object	obj

Returns

Type	Description
Boolean

Overrides

ValueType.Equals(Object)

Equals(Touch)

Declaration

public bool Equals(Touch other)

Parameters

Type	Name	Description
Touch	other

Returns

Type	Description
Boolean

Implements

IEquatable<T>.Equals(T)

GetHashCode()

Declaration

public override int GetHashCode()

Returns

Type	Description
Int32

Overrides

ValueType.GetHashCode()

ToString()

Declaration

public override string ToString()

Returns

Type	Description
String

Overrides

ValueType.ToString()

Events

onFingerDown

Declaration

public static event Action<Finger> onFingerDown

Event Type

Type	Description
Action<Finger>

onFingerMove

Declaration

public static event Action<Finger> onFingerMove

Event Type

Type	Description
Action<Finger>

onFingerUp

Declaration

public static event Action<Finger> onFingerUp

Event Type

Type	Description
Action<Finger>