Skip to content

Commit e72d158

Browse files
ducketsduckets
authored
DOCS: improve migration docs (#1933)
* Updates to migration guide for Pen events * Updates to migration guide for Keyboard IME text composition * Removed migration info for Input.mousePresent
1 parent 084bf22 commit e72d158

7 files changed

Lines changed: 264 additions & 197 deletions

File tree

‎Packages/com.unity.inputsystem/Documentation~/Gamepad.md‎

Lines changed: 44 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,16 @@ uid: input-system-gamepad
33
---
44
# Gamepad Support
55

6-
- [Gamepad Support](#gamepad-support)
7-
- [Controls](#controls)
8-
- [Deadzones](#deadzones)
9-
- [Polling](#polling)
10-
- [Rumble](#rumble)
11-
- [Pausing, resuming, and stopping haptics](#pausing-resuming-and-stopping-haptics)
12-
- [PlayStation controllers](#playstation-controllers)
13-
- [Xbox controllers](#xbox-controllers)
14-
- [Switch controllers](#switch-controllers)
15-
- [Cursor Control](#cursor-control)
6+
- [Controls](#controls)
7+
- [Deadzones](#deadzones)
8+
- [Polling](#polling)
9+
- [Rumble](#rumble)
10+
- [Pausing, resuming, and stopping haptics](#pausing-resuming-and-stopping-haptics)
11+
- [PlayStation controllers](#playstation-controllers)
12+
- [Xbox controllers](#xbox-controllers)
13+
- [Switch controllers](#switch-controllers)
14+
- [Cursor Control](#cursor-control)
15+
- [Discover all connected devices](#discover-all-connected-devices)
1616

1717
A [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) is narrowly defined as a Device with two thumbsticks, a D-pad, and four face buttons. Additionally, gamepads usually have two shoulder and two trigger buttons. Most gamepads also have two buttons in the middle.
1818

@@ -198,3 +198,37 @@ The Input System support Switch Pro controllers on desktop computers via the [`S
198198
## Cursor Control
199199

200200
To give gamepads and joysticks control over a hardware or software cursor, you can use the [`VirtualMouseInput`](../api/UnityEngine.InputSystem.UI.VirtualMouseInput.html) component. See [`VirtualMouseInput` component](UISupport.md#virtual-mouse-cursor-control) in the UI section of the manual.
201+
202+
## Discover all connected devices
203+
204+
There are various ways to discover the currently connected devices, as shown in the code samples below.
205+
206+
To query a list of all connected devices (does not allocate; read-only access):
207+
```
208+
InputSystem.devices
209+
```
210+
211+
To get notified when a device is added or removed:
212+
```
213+
InputSystem.onDeviceChange +=
214+
(device, change) =>
215+
{
216+
if (change == InputDeviceChange.Added || change == InputDeviceChange.Removed)
217+
{
218+
Debug.Log($"Device '{device}' was {change}");
219+
}
220+
}
221+
```
222+
223+
To find all gamepads and joysticks:
224+
```
225+
var devices = InputSystem.devices;
226+
for (var i = 0; i < devices.Count; ++i)
227+
{
228+
var device = devices[i];
229+
if (device is Joystick || device is Gamepad)
230+
{
231+
Debug.Log("Found " + device);
232+
}
233+
}
234+
```

‎Packages/com.unity.inputsystem/Documentation~/Images/InputManagerVsInputActions.png‎

60.1 KB
Loading

‎Packages/com.unity.inputsystem/Documentation~/Migration.md‎

Lines changed: 90 additions & 171 deletions
Large diffs are not rendered by default.

‎Packages/com.unity.inputsystem/Documentation~/Sensors.md‎

Lines changed: 35 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,19 +3,19 @@ uid: input-system-sensors
33
---
44
# Sensor support
55

6-
* [Sampling Frequency](#sampling-frequency)
7-
* [Accelerometer](#accelerometer)
8-
* [Gyroscope](#gyroscope)
9-
* [GravitySensor](#gravitysensor)
10-
* [AttitudeSensor](#attitudesensor)
11-
* [LinearAccelerationSensor](#linearaccelerationsensor)
12-
* [MagneticFieldSensor](#magneticfieldsensor)
13-
* [LightSensor](#lightsensor)
14-
* [PressureSensor](#pressuresensor)
15-
* [ProximitySensor](#proximitysensor)
16-
* [HumiditySensor](#humiditysensor)
17-
* [AmbientTemperatureSensor](#ambienttemperaturesensor)
18-
* [StepCounter](#stepcounter)
6+
- [Sampling frequency](#sampling-frequency)
7+
- [`Accelerometer`](#accelerometer)
8+
- [`Gyroscope`](#gyroscope)
9+
- [`GravitySensor`](#gravitysensor)
10+
- [`AttitudeSensor`](#attitudesensor)
11+
- [`LinearAccelerationSensor`](#linearaccelerationsensor)
12+
- [`MagneticFieldSensor`](#magneticfieldsensor)
13+
- [`LightSensor`](#lightsensor)
14+
- [`PressureSensor`](#pressuresensor)
15+
- [`ProximitySensor`](#proximitysensor)
16+
- [`HumiditySensor`](#humiditysensor)
17+
- [`AmbientTemperatureSensor`](#ambienttemperaturesensor)
18+
- [`StepCounter`](#stepcounter)
1919

2020
Sensors are [`InputDevices`](Devices.md) that measure environmental characteristics of the device that the content is running on. Unity currently supports sensors on iOS and Android. Android supports a wider range of sensors than iOS.
2121

@@ -84,6 +84,28 @@ Gyroscope.current.samplingFrequency = 16;
8484

8585
Use the accelerometer to measure the acceleration of a device. This is useful to control content by moving a device around. It reports the acceleration measured on a device both due to moving the device around, and due to gravity pulling the device down. You can use `GravitySensor` and `LinearAccelerationSensor` to get separate values for these. Values are affected by the [__Compensate Orientation__](Settings.md#compensate-orientation) setting.
8686

87+
The following code traces all input events on the [`Accelerometer.current`](../api/UnityEngine.InputSystem.Accelerometer.html) device.
88+
```CSharp
89+
private InputEventTrace trace;
90+
91+
void StartTrace()
92+
{
93+
InputSystem.EnableDevice(Accelerometer.current);
94+
95+
trace = new InputEventTrace(Accelerometer.current);
96+
trace.Enable();
97+
}
98+
99+
void Update()
100+
{
101+
foreach (var e in trace)
102+
{
103+
//...
104+
}
105+
trace.Clear();
106+
}
107+
```
108+
87109
## <a name="gyroscope"></a>[`Gyroscope`](../api/UnityEngine.InputSystem.Gyroscope.html)
88110

89111
Use the gyroscope to measure the angular velocity of a device. This is useful to control content by rotating a device. Values are affected by the [__Compensate Orientation__](Settings.md#compensate-orientation) setting.

‎Packages/com.unity.inputsystem/Documentation~/TableOfContents.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,6 @@
4343
* [Input testing](Testing.md)
4444
* [How do I...?](HowDoI.md)
4545
* [Architecture](Architecture.md)
46-
* [Migrating from the old input system](Migration.md)
46+
* [Migrating from the old Input Manager](Migration.md)
4747
* [Contributing](Contributing.md)
4848
* [Known Limitations](KnownLimitations.md)

‎Packages/com.unity.inputsystem/InputSystem/Controls/ButtonControl.cs‎

Lines changed: 84 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -100,9 +100,55 @@ public ButtonControl()
100100
/// </summary>
101101
/// <value>True if button is currently pressed.</value>
102102
/// <remarks>
103-
/// A button is considered press if it's value is equal to or greater
103+
/// A button is considered pressed if its value is equal to or greater
104104
/// than its button press threshold (<see cref="pressPointOrDefault"/>).
105105
/// </remarks>
106+
/// <example>
107+
/// <para>You can use this to read whether specific keys are currently pressed by using isPressed on keys, as shown in the following examples:</para>
108+
/// <code>
109+
/// <![CDATA[
110+
/// // Using KeyControl property directly.
111+
/// Keyboard.current.spaceKey.isPressed
112+
/// Keyboard.current.aKey.isPressed // etc.
113+
///
114+
/// // Using Key enum.
115+
/// Keyboard.current[Key.Space].isPressed
116+
///
117+
/// // Using key name.
118+
/// ((KeyControl)Keyboard.current["space"]).isPressed
119+
/// ]]>
120+
/// </code>
121+
/// <para>Note: The Input System identifies keys by physical layout, not according to the current language mapping of the keyboard. To query the name of the key according to the language mapping, use <see cref="InputControl.displayName"/>.
122+
///
123+
/// You can also use this to read mouse buttons, as shown in the following examples:</para>
124+
/// <code>
125+
/// <![CDATA[
126+
/// bool leftPressed = Mouse.current.leftButton.isPressed;
127+
/// bool rightPressed = Mouse.current.rightButton.isPressed;
128+
/// bool middlePressed = Mouse.current.middleButton.isPressed;
129+
/// ]]>
130+
/// </code>
131+
/// <para>You can also check through all numbered buttons on the mouse: (this example does not cause allocations)</para>
132+
/// <code>
133+
/// <![CDATA[
134+
/// var controls = Mouse.current.allControls;
135+
/// for (var i = 0; i < controls.Count; ++i)
136+
/// {
137+
/// var button = controls[i] as ButtonControl;
138+
/// if (button != null && button.isPressed)
139+
/// {
140+
/// // respond to mouse button press here...
141+
/// }
142+
/// }
143+
/// ]]>
144+
/// </code>
145+
/// <para>Or you can look up controls by name, like this:</para>
146+
/// <code>
147+
/// <![CDATA[
148+
/// bool leftPressed = ((ButtonControl)Mouse.current["leftButton"]).isPressed;
149+
/// ]]>
150+
/// </code>
151+
/// </example>
106152
/// <seealso cref="InputSettings.defaultButtonPressPoint"/>
107153
/// <seealso cref="pressPoint"/>
108154
/// <seealso cref="InputSystem.onAnyButtonPress"/>
@@ -177,6 +223,19 @@ private void BeginTestingForFramePresses(bool currentlyPressed, bool pressedLast
177223
/// }
178224
/// </code>
179225
/// </example>
226+
/// _Note_: The Input System identifies keys by physical layout, not according to the current language mapping of the keyboard. To query the name of the key according to the language mapping, use <see cref="InputControl.displayName"/>.
227+
///
228+
/// You can also use this property to read mouse buttons. For example:
229+
///
230+
/// <example>
231+
/// <code>
232+
/// Mouse.current.leftButton.wasPressedThisFrame
233+
/// Mouse.current.rightButton.wasPressedThisFrame
234+
/// Mouse.current.middleButton.wasPressedThisFrame
235+
/// </code>
236+
/// </example>
237+
///
238+
///
180239
/// </remarks>
181240
public bool wasPressedThisFrame
182241
{
@@ -200,6 +259,29 @@ public bool wasPressedThisFrame
200259
}
201260
}
202261

262+
/// <summary>
263+
/// Whether the press ended this frame.
264+
/// </summary>
265+
/// <value>True if the current press of the button ended this frame.</value>
266+
/// <remarks>
267+
/// _Note_: The Input System identifies keys by physical layout, not according to the current language mapping of the keyboard. To query the name of the key according to the language mapping, use <see cref="InputControl.displayName"/>.
268+
/// </remarks>
269+
/// <example>
270+
/// <para>An example showing the use of this property on a gamepad button and a keyboard key:</para>
271+
/// <code>
272+
/// using UnityEngine;
273+
/// using UnityEngine.InputSystem;
274+
///
275+
/// public class ExampleScript : MonoBehaviour
276+
/// {
277+
/// void Update()
278+
/// {
279+
/// bool buttonPressed = Gamepad.current.aButton.wasReleasedThisFrame;
280+
/// bool spaceKeyPressed = Keyboard.current.spaceKey.wasReleasedThisFrame;
281+
/// }
282+
/// }
283+
/// </code>
284+
/// </example>
203285
public bool wasReleasedThisFrame
204286
{
205287
get
@@ -214,7 +296,7 @@ public bool wasReleasedThisFrame
214296
return device.wasUpdatedThisFrame && !currentlyPressed && pressedLastFrame;
215297
}
216298

217-
#if UNITY_EDITOR
299+
#if UNITY_EDITOR
218300
if (InputUpdate.s_LatestUpdateType.IsEditorUpdate())
219301
return InputUpdate.s_UpdateStepCount == m_UpdateCountLastReleasedEditor;
220302
#endif

‎Packages/com.unity.inputsystem/InputSystem/Devices/Keyboard.cs‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -972,6 +972,16 @@ public event Action<char> onTextInput
972972
///
973973
/// See <see cref="Keyboard.SetIMEEnabled"/> for turning IME on/off
974974
/// </remarks>
975+
/// <example>
976+
/// <para>To subscribe to the onIMECompositionChange event, use the following sample code:</para>
977+
/// <code>
978+
/// var compositionString = "";
979+
/// Keyboard.current.onIMECompositionChange += composition =>
980+
/// {
981+
/// compositionString = composition.ToString();
982+
/// };
983+
/// </code>
984+
/// </example>
975985
public event Action<IMECompositionString> onIMECompositionChange
976986
{
977987
add

0 commit comments

Comments
 (0)