NEW: Add controls for combined modifiers and method to look up keys by display name (#966).

Author: Rene Damm

Assets/Tests/InputSystem/CoreTests_Devices.cs

@@ -2124,6 +2124,61 @@ public void Devices_CanLookUpKeyFromKeyboardUsingKeyCode()
         Assert.That(keyboard[Key.A], Is.SameAs(keyboard.aKey));
     }
 
+    [Test]
+    [Category("Devices")]
+    public void Devices_CanLookUpKeyFromKeyboardUsingDisplayName()
+    {
+        var keyboard = InputSystem.AddDevice<Keyboard>();
+        SetKeyInfo(Key.A, "q");
+        SetKeyInfo(Key.Q, "a");
+
+        Assert.That(keyboard.FindKeyOnCurrentKeyboardLayout("a"), Is.SameAs(keyboard.qKey));
+        Assert.That(keyboard.FindKeyOnCurrentKeyboardLayout("q"), Is.SameAs(keyboard.aKey));
+    }
+
+    [Test]
+    [Category("Devices")]
+    public void Devices_KeyboardsHaveSyntheticCombinedModifierKeys()
+    {
+        var keyboard = InputSystem.AddDevice<Keyboard>();
+
+        Assert.That(keyboard.shiftKey.synthetic, Is.True);
+        Assert.That(keyboard.ctrlKey.synthetic, Is.True);
+        Assert.That(keyboard.altKey.synthetic, Is.True);
+
+        Assert.That(keyboard.shiftKey.isPressed, Is.False);
+        Assert.That(keyboard.ctrlKey.isPressed, Is.False);
+        Assert.That(keyboard.altKey.isPressed, Is.False);
+
+        Press(keyboard.leftAltKey);
+        Press(keyboard.leftShiftKey);
+        Press(keyboard.leftCtrlKey);
+
+        Assert.That(keyboard.shiftKey.isPressed, Is.True);
+        Assert.That(keyboard.ctrlKey.isPressed, Is.True);
+        Assert.That(keyboard.altKey.isPressed, Is.True);
+
+        Assert.That(keyboard.shiftKey.ReadValue(), Is.EqualTo(1).Within(0.00001));
+        Assert.That(keyboard.ctrlKey.ReadValue(), Is.EqualTo(1).Within(0.00001));
+        Assert.That(keyboard.altKey.ReadValue(), Is.EqualTo(1).Within(0.00001));
+
+        Release(keyboard.leftAltKey);
+        Release(keyboard.leftShiftKey);
+        Release(keyboard.leftCtrlKey);
+
+        Assert.That(keyboard.shiftKey.isPressed, Is.False);
+        Assert.That(keyboard.ctrlKey.isPressed, Is.False);
+        Assert.That(keyboard.altKey.isPressed, Is.False);
+
+        Press(keyboard.rightAltKey);
+        Press(keyboard.rightShiftKey);
+        Press(keyboard.rightCtrlKey);
+
+        Assert.That(keyboard.shiftKey.isPressed, Is.True);
+        Assert.That(keyboard.ctrlKey.isPressed, Is.True);
+        Assert.That(keyboard.altKey.isPressed, Is.True);
+    }
+
     [Test]
     [Category("Devices")]
     public void Devices_CanPerformHorizontalAndVerticalScrollWithMouse()

Packages/com.unity.inputsystem/CHANGELOG.md

@@ -9,6 +9,23 @@ however, it has to be formatted properly to pass verification tests.
 
 ## [1.0.0-preview.4] - 2019-12-12
 
+### Added
+
+- `Keyboard` now has a `FindKeyOnCurrentKeyboardLayout` method to look up key controls by their display names.
+- Keyboards now have synthetic controls that combine left and right variants of modifier keys.
+  * This means that you can bind to just "shift" now, for example, instead of having to bind to both "left shift" and "right shift".
+    ```CSharp
+    new InputAction(binding: "<Keyboard>/shift");
+    ```
+  * The controls are also available as properties on `Keyboard`.
+    ```CSharp
+    if (Keyboard.current.shiftKey.isPressed) /* ... */;
+
+    // Is equivalent to:
+    if (Keyboard.current.leftShiftKey.isPressed ||
+        Keyboard.current.rightShiftKey.isPressed) /* ... */;
+    ```
+
 ### Changed
 
 - `InputControlExtensions.GetStatePtrFromStateEvent` no longer throws `InvalidOperationException` when the state format for the event does not match that of the device. It simply returns `null` instead (same as when control is found in the event's state).

Packages/com.unity.inputsystem/Documentation~/Keyboard.md

@@ -11,6 +11,7 @@ You can look up keys based on the character they produce using [Control paths](C
 >__Note__
 >* Keyboards usually have hardware limitations on both the number of simultaneous keypresses they report, and the combinations of keys they support. This means that certain simultaneous keypresses may not register correctly. For example, a given keyboard may report a simultaneous press of the "QWERT" keys correctly but may not report "QWERA" correctly.
 >* At the moment, the new Input System doesn't support on-screen keyboards. For now, please Unity's existing API in `UnityEngine.TouchScreenKeyboard`.
+>* At the moment, Unity platform backends generally do not support distinguishing between multiple keyboards. While the Input System supports having arbitray many [`Keyboard`](../api/UnityEngine.InputSystem.Keyboard.html) devices at any point, platform backends will generally only report a single keyboard and route input from all attached keyboards to the one keyboard device.
 
 ## Controls
 
@@ -23,21 +24,21 @@ The [scripting API reference for the `Keyboard` class](../api/UnityEngine.InputS
 
 Two special Controls, [`anyKey`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_anyKey) and [`imeSelected`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_imeSelected), don't directly map to individual keys. [`anyKey`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_anyKey) is a [synthetic](Controls.md#synthetic-controls) button Control which reports whether any key on the keyboard is pressed, and [`imeSelected`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_imeSelected) reports whether or not [IME](#ime) text processing is enabled.
 
+In addition, [`Keyboard`](../api/UnityEngine.InputSystem.Keyboard.html)'s indexer and the [`Key`](../api/UnityEngine.InputSystem.Key.html) has three [synthetic](Controls.md#synthetic-controls) controls that represent combinations of modifier keys:
+
+|Control|Description|
+|-------|-----------|
+|[`shiftKey`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_shiftKey)|A button that is pressed if [`leftShiftKey`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_leftShiftKey) and/or [`rightShiftKey`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_rightShiftKey) is pressed.|
+|[`ctrlKey`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_ctrlKey)|A button that is pressed if [`leftCtrlKey`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_leftCtrlKey) and/or [`rightCtrlKey`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_rightCtrlKey) is pressed.|
+|[`altKey`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_altKey)|A button that is pressed if [`leftAltKey`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_leftAltKey) and/or [`rightAltKey`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_rightAltKey) is pressed.|
+
 ## Text input
 
 As a best practice, you shouldn't manually translate text input from key presses by trying to string together the characters corresponding to the keys. Instead, to listen to text input, hook into [`Keyboard.onTextInput`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_onTextInput). This delivers character-by-character input as reported by the platform, including input from on-screen keyboards.
 
 Note that the text input API doesn't allocate GC memory because it doesn't deliver fully composed strings.
 
-## Keyboard layouts
-
-You can query the name of the current keyboard layout using [`Keyboard.keyboardLayout`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_keyboardLayout). Layout names are platform-specific.
-
-There is no support for setting keyboard layouts from your application.
-
-To monitor keyboard layout changes, hook into [`InputSystem.onDeviceChange`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onDeviceChange) and check for [`InputDeviceChange.ConfigurationChanged`](../api/UnityEngine.InputSystem.InputDeviceChange.html) on a [`Keyboard`](../api/UnityEngine.InputSystem.Keyboard.html) device.
-
-## IME
+### IME
 
 Some writing systems, such as some East-Asian scripts, are too complex to represent all characters as individual keys on a keyboard. For these layouts, operating systems implement IMEs (Input Method Editors) to allow composing input strings by other methods, for instance by typing several keys to produce a single character. Unity's UI frameworks for text input support IME without any additional configuration. If you want to build your own UI for text input, the [`Keyboard`](../api/UnityEngine.InputSystem.Keyboard.html) class allows you to work with input from IMEs using the following APIs:
 
@@ -48,3 +49,18 @@ Some writing systems, such as some East-Asian scripts, are too complex to repres
 * [`SetIMECursorPosition()`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_SetIMECursorPosition_Vector2_). IMEs might open system windows that let users interactively edit the text they want to input. Typically, these open next to the text editing UI. You can use the [`SetIMECursorPosition()`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_SetIMECursorPosition_Vector2_) method to tell the OS where that is.
 
 * [`onIMECompositionChange`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_onIMECompositionChange) is an event you can subscribe to in order to receive all updates to the IME composition string. The composition string is the text input the user is currently editing using an IME. Typically, any UI dealing with text input displays this text (with some visual indication of it being actively edited, usually an underline) at the current text input cursor position.
+
+## Keyboard layouts
+
+You can query the name of the current keyboard layout using [`Keyboard.keyboardLayout`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_keyboardLayout). Layout names are platform-specific.
+
+There is no support for setting keyboard layouts from your application.
+
+To monitor keyboard layout changes, hook into [`InputSystem.onDeviceChange`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onDeviceChange) and check for [`InputDeviceChange.ConfigurationChanged`](../api/UnityEngine.InputSystem.InputDeviceChange.html) on a [`Keyboard`](../api/UnityEngine.InputSystem.Keyboard.html) device.
+
+To find the key control that corresponds to a specific display character sequence, call [`Keyboard.FindKeyOnCurrentKeyboardLayout`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_FindKeyOnCurrentKeyboardLayout_).
+
+```CSharp
+// Find key that generates a 'q' character according to the current keyboard layout.
+Keyboard.current.FindKeyOnCurrentKeyboardLayout("q");
+```

Packages/com.unity.inputsystem/Documentation~/UISupport.md

@@ -2,6 +2,8 @@
 
 You can use the Input System package to control any in-game UI created with the [Unity UI package](https://docs.unity3d.com/Manual/UISystem.html). The integration between the Input System and the UI system is handled by the [`InputSystemUIInputModule`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) component.
 
+>NOTE: At the moment, there is no support for IMGUI or for UIElements. This is being worked on.
+
 ## `InputSystemUIInputModule` Component
 
 The [`InputSystemUIInputModule`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) component acts as a drop-in replacement for the [`StandaloneInputModule`](https://docs.unity3d.com/Manual/script-StandaloneInputModule.html) component that the Unity UI package. [`InputSystemUIInputModule`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) provides the same kind of functionality as  [`StandaloneInputModule`](https://docs.unity3d.com/Manual/script-StandaloneInputModule.html), but it uses the Input System instead of the legacy Input Manager to drive UI input.

Packages/com.unity.inputsystem/InputSystem/Controls/KeyControl.cs

@@ -1,4 +1,5 @@
 using UnityEngine.InputSystem.LowLevel;
+using UnityEngine.Scripting;
 
 namespace UnityEngine.InputSystem.Controls
 {
@@ -14,7 +15,7 @@ namespace UnityEngine.InputSystem.Controls
     /// layout specific and does not need to be key-by-key. For general text input, see <see cref="Keyboard.onTextInput"/>.
     /// To find the text displayed on a key, use <see cref="KeyControl.displayName"/>.
     /// </remarks>
-    [Scripting.Preserve]
+    [Preserve]
     public class KeyControl : ButtonControl
     {
         /// <summary>

Packages/com.unity.inputsystem/InputSystem/Devices/Commands/QueryKeyNameCommand.cs

@@ -10,7 +10,7 @@ namespace UnityEngine.InputSystem.LowLevel
     [StructLayout(LayoutKind.Explicit, Size = kSize)]
     public unsafe struct QueryKeyNameCommand : IInputDeviceCommandInfo
     {
-        public static FourCC Type { get { return new FourCC('K', 'Y', 'C', 'F'); } }
+        public static FourCC Type => new FourCC('K', 'Y', 'C', 'F');
 
         internal const int kMaxNameLength = 256;
         internal const int kSize = InputDeviceCommand.kBaseCommandSize + kMaxNameLength + 4;
@@ -32,10 +32,7 @@ public string ReadKeyName()
             }
         }
 
-        public FourCC typeStatic
-        {
-            get { return Type; }
-        }
+        public FourCC typeStatic => Type;
 
         public static QueryKeyNameCommand Create(Key key)
         {