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
Unity-Technologies · Aug 5, 2024 · e72d158 · e72d158
1 parent 084bf22
commit e72d158
Show file tree

Hide file tree

Showing 7 changed files with 264 additions and 197 deletions.
diff --git a/Packages/com.unity.inputsystem/Documentation~/Gamepad.md b/Packages/com.unity.inputsystem/Documentation~/Gamepad.md
@@ -3,16 +3,16 @@ uid: input-system-gamepad
 ---
 # Gamepad Support
 
-- [Gamepad Support](#gamepad-support)
-  - [Controls](#controls)
-    - [Deadzones](#deadzones)
-  - [Polling](#polling)
-  - [Rumble](#rumble)
-    - [Pausing, resuming, and stopping haptics](#pausing-resuming-and-stopping-haptics)
-  - [PlayStation controllers](#playstation-controllers)
-  - [Xbox controllers](#xbox-controllers)
-  - [Switch controllers](#switch-controllers)
-  - [Cursor Control](#cursor-control)
+- [Controls](#controls)
+  - [Deadzones](#deadzones)
+- [Polling](#polling)
+- [Rumble](#rumble)
+  - [Pausing, resuming, and stopping haptics](#pausing-resuming-and-stopping-haptics)
+- [PlayStation controllers](#playstation-controllers)
+- [Xbox controllers](#xbox-controllers)
+- [Switch controllers](#switch-controllers)
+- [Cursor Control](#cursor-control)
+- [Discover all connected devices](#discover-all-connected-devices)
 
 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.
 
@@ -198,3 +198,37 @@ The Input System support Switch Pro controllers on desktop computers via the [`S
 ## Cursor Control
 
 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.
+
+## Discover all connected devices
+
+There are various ways to discover the currently connected devices, as shown in the code samples below.
+
+To query a list of all connected devices (does not allocate; read-only access):
+```
+InputSystem.devices
+```
+
+To get notified when a device is added or removed:
+```
+InputSystem.onDeviceChange +=
+    (device, change) =>
+    {
+        if (change == InputDeviceChange.Added || change == InputDeviceChange.Removed)
+        {
+            Debug.Log($"Device '{device}' was {change}");
+        }
+    }
+```
+
+To find all gamepads and joysticks:
+```
+var devices = InputSystem.devices;
+for (var i = 0; i < devices.Count; ++i)
+{
+    var device = devices[i];
+    if (device is Joystick || device is Gamepad)
+    {
+        Debug.Log("Found " + device);
+    }
+}
+```
diff --git a/...ages/com.unity.inputsystem/Documentation~/Images/InputManagerVsInputActions.png b/...ages/com.unity.inputsystem/Documentation~/Images/InputManagerVsInputActions.png
diff --git a/Packages/com.unity.inputsystem/Documentation~/Migration.md b/Packages/com.unity.inputsystem/Documentation~/Migration.md
diff --git a/Packages/com.unity.inputsystem/Documentation~/Sensors.md b/Packages/com.unity.inputsystem/Documentation~/Sensors.md
@@ -3,19 +3,19 @@ uid: input-system-sensors
 ---
 # Sensor support
 
-* [Sampling Frequency](#sampling-frequency)
-* [Accelerometer](#accelerometer)
-* [Gyroscope](#gyroscope)
-* [GravitySensor](#gravitysensor)
-* [AttitudeSensor](#attitudesensor)
-* [LinearAccelerationSensor](#linearaccelerationsensor)
-* [MagneticFieldSensor](#magneticfieldsensor)
-* [LightSensor](#lightsensor)
-* [PressureSensor](#pressuresensor)
-* [ProximitySensor](#proximitysensor)
-* [HumiditySensor](#humiditysensor)
-* [AmbientTemperatureSensor](#ambienttemperaturesensor)
-* [StepCounter](#stepcounter)
+- [Sampling frequency](#sampling-frequency)
+- [`Accelerometer`](#accelerometer)
+- [`Gyroscope`](#gyroscope)
+- [`GravitySensor`](#gravitysensor)
+- [`AttitudeSensor`](#attitudesensor)
+- [`LinearAccelerationSensor`](#linearaccelerationsensor)
+- [`MagneticFieldSensor`](#magneticfieldsensor)
+- [`LightSensor`](#lightsensor)
+- [`PressureSensor`](#pressuresensor)
+- [`ProximitySensor`](#proximitysensor)
+- [`HumiditySensor`](#humiditysensor)
+- [`AmbientTemperatureSensor`](#ambienttemperaturesensor)
+- [`StepCounter`](#stepcounter)
 
 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.
 
@@ -84,6 +84,28 @@ Gyroscope.current.samplingFrequency = 16;
 
 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.
 
+ The following code traces all input events on the [`Accelerometer.current`](../api/UnityEngine.InputSystem.Accelerometer.html) device.
+```CSharp
+    private InputEventTrace trace;
+
+    void StartTrace()
+    {
+        InputSystem.EnableDevice(Accelerometer.current);
+
+        trace = new InputEventTrace(Accelerometer.current);
+        trace.Enable();
+    }
+
+    void Update()
+    {
+        foreach (var e in trace)
+        {
+            //...
+        }
+        trace.Clear();
+    }
+```
+
 ## <a name="gyroscope"></a>[`Gyroscope`](../api/UnityEngine.InputSystem.Gyroscope.html)
 
 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.

diff --git a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md
@@ -43,6 +43,6 @@
   * [Input testing](Testing.md)
 * [How do I...?](HowDoI.md)
 * [Architecture](Architecture.md)
-* [Migrating from the old input system](Migration.md)
+* [Migrating from the old Input Manager](Migration.md)
 * [Contributing](Contributing.md)
 * [Known Limitations](KnownLimitations.md)
diff --git a/Packages/com.unity.inputsystem/InputSystem/Controls/ButtonControl.cs b/Packages/com.unity.inputsystem/InputSystem/Controls/ButtonControl.cs
@@ -100,9 +100,55 @@ public ButtonControl()
         /// </summary>
         /// <value>True if button is currently pressed.</value>
         /// <remarks>
-        /// A button is considered press if it's value is equal to or greater
+        /// A button is considered pressed if its value is equal to or greater
         /// than its button press threshold (<see cref="pressPointOrDefault"/>).
         /// </remarks>
+        /// <example>
+        /// <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>
+        /// <code>
+        /// <![CDATA[
+        /// // Using KeyControl property directly.
+        /// Keyboard.current.spaceKey.isPressed
+        /// Keyboard.current.aKey.isPressed // etc.
+        ///
+        /// // Using Key enum.
+        /// Keyboard.current[Key.Space].isPressed
+        ///
+        /// // Using key name.
+        /// ((KeyControl)Keyboard.current["space"]).isPressed
+        /// ]]>
+        /// </code>
+        /// <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"/>.
+        ///
+        /// You can also use this to read mouse buttons, as shown in the following examples:</para>
+        /// <code>
+        /// <![CDATA[
+        /// bool leftPressed = Mouse.current.leftButton.isPressed;
+        /// bool rightPressed = Mouse.current.rightButton.isPressed;
+        /// bool middlePressed = Mouse.current.middleButton.isPressed;
+        /// ]]>
+        /// </code>
+        /// <para>You can also check through all numbered buttons on the mouse: (this example does not cause allocations)</para>
+        /// <code>
+        /// <![CDATA[
+        /// var controls = Mouse.current.allControls;
+        /// for (var i = 0; i < controls.Count; ++i)
+        /// {
+        ///     var button = controls[i] as ButtonControl;
+        ///     if (button != null && button.isPressed)
+        ///     {
+        ///         // respond to mouse button press here...
+        ///     }
+        /// }
+        /// ]]>
+        /// </code>
+        /// <para>Or you can look up controls by name, like this:</para>
+        /// <code>
+        /// <![CDATA[
+        /// bool leftPressed = ((ButtonControl)Mouse.current["leftButton"]).isPressed;
+        /// ]]>
+        /// </code>
+        /// </example>
         /// <seealso cref="InputSettings.defaultButtonPressPoint"/>
         /// <seealso cref="pressPoint"/>
         /// <seealso cref="InputSystem.onAnyButtonPress"/>
@@ -177,6 +223,19 @@ private void BeginTestingForFramePresses(bool currentlyPressed, bool pressedLast
         /// }
         /// </code>
         /// </example>
+        /// _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"/>.
+        ///
+        /// You can also use this property to read mouse buttons. For example:
+        ///
+        /// <example>
+        /// <code>
+        /// Mouse.current.leftButton.wasPressedThisFrame
+        /// Mouse.current.rightButton.wasPressedThisFrame
+        /// Mouse.current.middleButton.wasPressedThisFrame
+        /// </code>
+        /// </example>
+        ///
+        ///
         /// </remarks>
         public bool wasPressedThisFrame
         {
@@ -200,6 +259,29 @@ public bool wasPressedThisFrame
             }
         }
 
+        /// <summary>
+        /// Whether the press ended this frame.
+        /// </summary>
+        /// <value>True if the current press of the button ended this frame.</value>
+        /// <remarks>
+        /// _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"/>.
+        /// </remarks>
+        /// <example>
+        /// <para>An example showing the use of this property on a gamepad button and a keyboard key:</para>
+        /// <code>
+        /// using UnityEngine;
+        /// using UnityEngine.InputSystem;
+        ///
+        /// public class ExampleScript : MonoBehaviour
+        /// {
+        ///     void Update()
+        ///     {
+        ///         bool buttonPressed = Gamepad.current.aButton.wasReleasedThisFrame;
+        ///         bool spaceKeyPressed = Keyboard.current.spaceKey.wasReleasedThisFrame;
+        ///     }
+        /// }
+        /// </code>
+        /// </example>
         public bool wasReleasedThisFrame
         {
             get
@@ -214,7 +296,7 @@ public bool wasReleasedThisFrame
                     return device.wasUpdatedThisFrame && !currentlyPressed && pressedLastFrame;
                 }
 
-#if UNITY_EDITOR
+                #if UNITY_EDITOR
                 if (InputUpdate.s_LatestUpdateType.IsEditorUpdate())
                     return InputUpdate.s_UpdateStepCount == m_UpdateCountLastReleasedEditor;
                 #endif

diff --git a/Packages/com.unity.inputsystem/InputSystem/Devices/Keyboard.cs b/Packages/com.unity.inputsystem/InputSystem/Devices/Keyboard.cs
@@ -972,6 +972,16 @@ public event Action<char> onTextInput
         ///
         /// See <see cref="Keyboard.SetIMEEnabled"/> for turning IME on/off
         /// </remarks>
+        /// <example>
+        /// <para>To subscribe to the onIMECompositionChange event, use the following sample code:</para>
+        /// <code>
+        /// var compositionString = "";
+        /// Keyboard.current.onIMECompositionChange += composition =>
+        /// {
+        ///    compositionString = composition.ToString();
+        /// };
+        /// </code>
+        /// </example>
         public event Action<IMECompositionString> onIMECompositionChange
         {
             add