Class Touchscreen
A multi-touch surface.
Implements
Inherited Members
Namespace: UnityEngine.InputSystem
Assembly: Unity.InputSystem.dll
Syntax
public class Touchscreen : Pointer, IInputStateCallbackReceiver
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. |
isPressureSupported
Whether the Input System can deliver a measured touch pressure value on the current platform, regardless of whether a touchscreen is connected.
Declaration
public static bool isPressureSupported { get; }
Property Value
| Type | Description |
|---|---|
| bool |
Remarks
Use this to decide whether to treat pressure as an analog signal. When it is false, don't read meaning into pressure: either the Input System doesn't deliver a measured value on this platform, in which case pressure reports a platform-dependent constant while a finger is down, or it couldn't determine whether it does. The two cases aren't distinguished. It doesn't change while the application runs.
The answer covers the platform, not an individual touchscreen. Platforms with no touchscreen at all also report false.
On some platforms the OS supplies a pressure value whether or not the attached digitizer measures one, and there is no per-device query to tell a real reading from a constant.
To find out whether a touchscreen is connected and delivering input, use current and enabled instead.
Examples
var brushWidth = Touchscreen.isPressureSupported
&& Touchscreen.current != null && Touchscreen.current.enabled
? Touchscreen.current.primaryTouch.pressure.ReadValue() * maxBrushWidth
: defaultBrushWidth;
See Also
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.
Examples
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()
Makes this device the current device of its type.
Declaration
public override void MakeCurrent()
Overrides
Remarks
Many types of devices have .current getters that return the current device of that type
(for example, current). The current device of a type is the device of that
type that most recently became current. For a built-in sensor, the type is the class that derives directly
from Sensor. For example, an Android gyroscope becomes current.
The Input System calls this method in the following cases:
- When a device is added. If all the device's controls are noisy, the device becomes current only if no other device of its type is current. For example, a second gyroscope doesn't replace the first one as current, because all of a gyroscope sensor's controls are noisy.
- When input changes a control that isn't noisy. Input on noisy controls doesn't call this method.
- When a device's usage changes, with the same rule as when the device is added.
- When a layout change recreates a device. The new device is current if the old one was.
- When a device is removed. The remaining device of its type that was updated last becomes current.
If no device of that type is left,
.currentisnull. If you remove a sensor that isn't current,.currentstays the same.
A device with noisy controls (noisy) can receive events that carry no user interaction. For example, the PlayStation®4 (PS4) gamepad has a gyro and keeps sending events when nobody uses it. Without the rule for noisy controls, the PS4 gamepad would make itself current while the user plays with another gamepad.
When you call this method yourself, the device becomes current even if its controls are noisy.
If you override this method, call base.MakeCurrent(). Otherwise, the built-in .current
getters don't return the device, and the rules above don't apply to it.
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
Examples
using UnityEngine.InputSystem;
public class MyDevice : InputDevice
{
public static MyDevice current { get; private set; }
protected override void OnRemoved()
{
// use this context to unassign the current device for instance
base.OnRemoved();
if (current == this)
current = null;
}
}
OnStateEvent(InputEventPtr)
Called whenever a new state event is received.
Declaration
protected void OnStateEvent(InputEventPtr eventPtr)
Parameters
| Type | Name | Description |
|---|---|---|
| InputEventPtr | eventPtr |