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, that is, 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
Set of currently active fingers, i.e. touch contacts that currently have an active touch (as defined by activeTouches).
Declaration
public static readonly ReadOnlyArray<Finger> activeFingers { get; }
Property Value
Type | Description |
---|---|
ReadOnlyArray<Finger> |
Exceptions
Type | Condition |
---|---|
InvalidOperationException |
|
See Also
activeTouches
All touches that are either on-going as of the current frame or have ended in the current frame.
Declaration
public static readonly ReadOnlyArray<Touch> activeTouches { get; }
Property Value
Type | Description |
---|---|
ReadOnlyArray<Touch> |
Remarks
A touch that begins in a frame will always have its phase set to Began even if there was also movement (or even an end/cancellation) for the touch in the same frame.
A touch that begins and ends in the same frame will have its Began surface in that frame and then another entry with Ended surface in the next frame. This logic implies that there can be more active touches than concurrent touches supported by the hardware/platform.
A touch that begins and moves in the same frame will have its Began surface in that frame and then another entry with Moved and the screen motion surface in the next frame except if the touch also ended in the frame (in which case phase will be Ended instead of Moved).
Note that the touches reported by this API do not necessarily have to match the contents of
UnityEngine.Input.touches.
The reason for this is that the UnityEngine.Input
API and the Input System API flush their input
queues at different points in time and may thus have a different view on available input. In particular,
the Input System event queue is flushed later in the frame than inputs for UnityEngine.Input
and may thus have newer inputs available. On Android, for example, touch input is gathered from a separate
UI thread and fed into the input system via a "background" event queue that can gather input asynchronously.
Due to this setup, touch events that will reach UnityEngine.Input
only in the next frame may have
already reached the Input System.
void Awake()
{
// Enable EnhancedTouch.
EnhancedTouchSupport.Enable();
}
void Update()
{
foreach (var touch in Touch.activeTouches)
if (touch.began)
Debug.Log($"Touch {touch} started this frame");
else if (touch.ended)
Debug.Log($"Touch {touch} ended this frame");
}
Exceptions
Type | Condition |
---|---|
InvalidOperationException |
|
See Also
began
Declaration
public readonly bool began { get; }
Property Value
Type | Description |
---|---|
Boolean |
See Also
delta
Screen-space motion delta of the touch.
Declaration
public readonly 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
ended
Declaration
public readonly bool ended { get; }
Property Value
Type | Description |
---|---|
Boolean |
See Also
finger
The finger used for the touch contact. Null only for default-initialized instances of the struct.
Declaration
public readonly Finger finger { get; }
Property Value
Type | Description |
---|---|
Finger | Finger used for the touch contact. |
See Also
fingers
An array of all possible concurrent touch contacts, i.e. all concurrent touch contacts regardless of whether they are currently active or not.
Declaration
public static readonly ReadOnlyArray<Finger> fingers { get; }
Property Value
Type | Description |
---|---|
ReadOnlyArray<Finger> |
Remarks
For querying only active fingers, use activeFingers.
The length of this array will always correspond to the maximum number of concurrent touches supported by the system. Note that the actual number of physically supported concurrent touches as determined by the current hardware and operating system may be lower than this number.
Exceptions
Type | Condition |
---|---|
InvalidOperationException |
|
See Also
history
History for this specific touch.
Declaration
public readonly TouchHistory history { get; }
Property Value
Type | Description |
---|---|
TouchHistory |
Remarks
Unlike touchHistory, this gives the history of this touch only.
inProgress
Whether the touch is currently in progress, i.e. whether phase is either Moved, Stationary, or Began.
Declaration
public readonly bool inProgress { get; }
Property Value
Type | Description |
---|---|
Boolean |
See Also
isInProgress
Whether the touch is currently in progress, i.e. has a phase of Began, Moved, or Stationary.
Declaration
public readonly bool isInProgress { get; }
Property Value
Type | Description |
---|---|
Boolean | Whether the touch is currently ongoing. |
isTap
Whether the touch has performed a tap.
Declaration
public readonly 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
maxHistoryLengthPerFinger
The amount of history kept for each single touch.
Declaration
public static readonly 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 readonly 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
pressure
Normalized pressure of the touch against the touch surface.
Declaration
public readonly 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
radius
Screen-space radius of the touch.
Declaration
public readonly 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
screen
The touchscreen on which the touch occurred.
Declaration
public readonly Touchscreen screen { get; }
Property Value
Type | Description |
---|---|
Touchscreen | Touchscreen associated with the touch. |
screenPosition
Screen-space position of the touch.
Declaration
public readonly Vector2 screenPosition { get; }
Property Value
Type | Description |
---|---|
Vector2 | Screen-space position of the touch. |
See Also
screens
Return the set of Touchscreens on which touch input is monitored.
Declaration
public static readonly IEnumerable<Touchscreen> screens { get; }
Property Value
Type | Description |
---|---|
IEnumerable<Touchscreen> |
Exceptions
Type | Condition |
---|---|
InvalidOperationException |
|
startScreenPosition
Screen-space position where the touch started.
Declaration
public readonly Vector2 startScreenPosition { get; }
Property Value
Type | Description |
---|---|
Vector2 | Start position of the touch. |
See Also
startTime
Time in seconds on the same timeline as Time.realTimeSinceStartup
when the touch began.
Declaration
public readonly double startTime { get; }
Property Value
Type | Description |
---|---|
Double | Start time of the touch. |
Remarks
See Also
tapCount
Number of times that the touch has been tapped in succession.
Declaration
public readonly 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
time
Time in seconds on the same timeline as Time.realTimeSinceStartup
when the touch record was
reported.
Declaration
public readonly 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 readonly 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
valid
Whether this touch record holds valid data.
Declaration
public readonly 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
Equals(Touch)
Declaration
public bool Equals(Touch other)
Parameters
Type | Name | Description |
---|---|---|
Touch | other |
Returns
Type | Description |
---|---|
Boolean |
Implements
GetHashCode()
Declaration
public override int GetHashCode()
Returns
Type | Description |
---|---|
Int32 |
Overrides
ToString()
Declaration
public override string ToString()
Returns
Type | Description |
---|---|
String |
Overrides
Events
onFingerDown
Event that is invoked when a finger touches a Touchscreen.
Declaration
public static event Action<Finger> onFingerDown
Event Type
Type | Description |
---|---|
Action<Finger> |
Exceptions
Type | Condition |
---|---|
InvalidOperationException |
|
See Also
onFingerMove
Event that is invoked when a finger that is in contact with a Touchscreen moves on the screen.
Declaration
public static event Action<Finger> onFingerMove
Event Type
Type | Description |
---|---|
Action<Finger> |
Exceptions
Type | Condition |
---|---|
InvalidOperationException |
|
See Also
onFingerUp
Event that is invoked when a finger stops touching a Touchscreen.
Declaration
public static event Action<Finger> onFingerUp
Event Type
Type | Description |
---|---|
Action<Finger> |
Exceptions
Type | Condition |
---|---|
InvalidOperationException |
|