diff --git a/Packages/com.unity.inputsystem/InputSystem/Controls/InputControl.cs b/Packages/com.unity.inputsystem/InputSystem/Controls/InputControl.cs index 1f5ec6adec..5cfa3b49b8 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Controls/InputControl.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Controls/InputControl.cs @@ -77,7 +77,7 @@ namespace UnityEngine.InputSystem /// which has APIs specific to the type of value of the control (e.g. . /// /// The following example demonstrates various common operations performed on input controls: - /// + /// /// /// /// // Look up dpad/up control on current gamepad. @@ -99,10 +99,7 @@ namespace UnityEngine.InputSystem /// leftStickHistory.Enable(); /// /// - /// - /// - /// - /// + /// /// /// /// @@ -611,6 +608,8 @@ public virtual unsafe void WriteValueFromObjectIntoState(object value, void* sta /// Note that if the given path matches multiple child controls, only the first control /// encountered in the search will be returned. /// + /// This method is equivalent to calling . + /// /// /// /// // Returns the leftStick control of the current gamepad. @@ -625,9 +624,6 @@ public virtual unsafe void WriteValueFromObjectIntoState(object value, void* sta /// Gamepad.current.TryGetChildControl("*stick"); /// /// - /// - /// This method is equivalent to calling . - /// public InputControl TryGetChildControl(string path) { if (string.IsNullOrEmpty(path)) @@ -689,7 +685,7 @@ protected InputControl() /// /// 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. - /// + /// /// /// /// public class MyDevice : InputDevice @@ -706,7 +702,6 @@ protected InputControl() /// } /// /// - /// protected virtual void FinishSetup() { } @@ -723,9 +718,12 @@ protected virtual void FinishSetup() /// /// This method should be called if you are accessing cached data set up by /// . - /// + /// /// /// + /// using UnityEngine.InputSystem; + /// using UnityEngine.InputSystem.Utilities; + /// /// // Let's say your device has an associated orientation which it can be held with /// // and you want to surface both as a property and as a usage on the device. /// // Whenever your backend code detects a change in orientation, it should send @@ -779,7 +777,6 @@ protected virtual void FinishSetup() /// } /// /// - /// /// protected void RefreshConfigurationIfNeeded() { @@ -790,6 +787,61 @@ protected void RefreshConfigurationIfNeeded() } } + /// + /// Refresh the configuration of the control. This is used to update the control's state (e.g. Keyboard Layout or display Name of Keys). + /// + /// + /// The system will call this method automatically whenever a change is made to one of the control's configuration properties. + /// See . + /// + /// + /// + /// using UnityEngine.InputSystem; + /// using UnityEngine.InputSystem.Utilities; + /// + /// public class MyDevice : InputDevice + /// { + /// public enum Orientation + /// { + /// Horizontal, + /// Vertical, + /// } + /// private Orientation m_Orientation; + /// private static InternedString s_Vertical = new InternedString("Vertical"); + /// private static InternedString s_Horizontal = new InternedString("Horizontal"); + /// + /// public Orientation orientation + /// { + /// get + /// { + /// // Call RefreshOrientation if the configuration of the device has been + /// // invalidated since last time we initialized m_Orientation. + /// // Calling RefreshConfigurationIfNeeded() is sufficient in most cases, RefreshConfiguration() forces the refresh. + /// RefreshConfiguration(); + /// return m_Orientation; + /// } + /// } + /// protected override void RefreshConfiguration() + /// { + /// // Set Orientation back to horizontal. Alternatively fetch from device. + /// m_Orientation = Orientation.Horizontal; + /// // Reflect the orientation on the device. + /// switch (m_Orientation) + /// { + /// case Orientation.Vertical: + /// InputSystem.RemoveDeviceUsage(this, s_Horizontal); + /// InputSystem.AddDeviceUsage(this, s_Vertical); + /// break; + /// + /// case Orientation.Horizontal: + /// InputSystem.RemoveDeviceUsage(this, s_Vertical); + /// InputSystem.AddDeviceUsage(this, s_Horizontal); + /// break; + /// } + /// } + /// } + /// + /// protected virtual void RefreshConfiguration() { } @@ -902,8 +954,6 @@ protected virtual FourCC CalculateOptimizedControlDataType() /// /// Apply built-in parameters changes (e.g. , others), recompute for impacted controls and clear cached value. /// - /// - /// public void ApplyParameterChanges() { // First we go through all children of our own hierarchy diff --git a/Packages/com.unity.inputsystem/InputSystem/Controls/KeyControl.cs b/Packages/com.unity.inputsystem/InputSystem/Controls/KeyControl.cs index 6e8c5f8b84..de58183fa8 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Controls/KeyControl.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Controls/KeyControl.cs @@ -58,7 +58,7 @@ public int scanCode return m_ScanCode; } } - + /// protected override void RefreshConfiguration() { // Wipe our last cached set of data (if any). diff --git a/Packages/com.unity.inputsystem/InputSystem/Devices/InputDevice.cs b/Packages/com.unity.inputsystem/InputSystem/Devices/InputDevice.cs index f2b469bc73..49c78673c4 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Devices/InputDevice.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Devices/InputDevice.cs @@ -41,21 +41,31 @@ namespace UnityEngine.InputSystem /// runtime. However, it is possible to manually add devices using methods such as . /// - /// - /// - /// // Add a "synthetic" gamepad that isn't actually backed by hardware. - /// var gamepad = InputSystem.AddDevice<Gamepad>(); - /// - /// - /// /// There are subclasses representing the most common types of devices, like , /// , , and . /// /// To create your own types of devices, you can derive from InputDevice and register your device /// as a new "layout". /// + /// Devices can have usages like any other control (). However, usages of InputDevices are allowed to be changed on the fly without requiring a change to the + /// device layout (see ). + /// + /// For a more complete example of how to implement custom input devices, check out the "Custom Device" + /// sample which you can install from the Unity package manager. + /// + /// You can also find more information in the manual. + /// /// /// + /// using System.Runtime.InteropServices; + /// using UnityEditor; + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// using UnityEngine.InputSystem.Controls; + /// using UnityEngine.InputSystem.Layouts; + /// using UnityEngine.InputSystem.LowLevel; + /// using UnityEngine.InputSystem.Utilities; + /// /// // InputControlLayoutAttribute attribute is only necessary if you want /// // to override default behavior that occurs when registering your device /// // as a layout. @@ -70,6 +80,9 @@ namespace UnityEngine.InputSystem /// public ButtonControl button { get; private set; } /// public AxisControl axis { get; private set; } /// + /// // This is an example of how to add a "synthetic" gamepad that isn't actually backed by hardware. + /// Gamepad gamepad = InputSystem.AddDevice<Gamepad>(); + /// /// // Register the device. /// static MyDevice() /// { @@ -113,7 +126,7 @@ namespace UnityEngine.InputSystem /// // particular device is connected and fed into the input system. /// // The format is a simple FourCC code that "tags" state memory blocks for the /// // device to give a base level of safety checks on memory operations. - /// public FourCC format => return new FourCC('H', 'I', 'D'); + /// public FourCC format => new FourCC('H', 'I', 'D'); /// /// // InputControlAttributes on fields tell the input system to create controls /// // for the public fields found in the struct. @@ -121,26 +134,16 @@ namespace UnityEngine.InputSystem /// // Assume a 16bit field of buttons. Create one button that is tied to /// // bit #3 (zero-based). Note that buttons do not need to be stored as bits. /// // They can also be stored as floats or shorts, for example. - /// [InputControl(name = "button", layout = "Button", bit = 3)] + /// [InputControl(name = "button", layout = "Button", bit = 3)] [FieldOffset(0)] /// public ushort buttons; /// /// // Create a floating-point axis. The name, if not supplied, is taken from /// // the field. - /// [InputControl(layout = "Axis")] + /// [InputControl(layout = "Axis")] [FieldOffset(0)] /// public short axis; /// } /// /// - /// - /// Devices can have usages like any other control (). Unlike other controls, - /// however, usages of InputDevices are allowed to be changed on the fly without requiring a change to the - /// device layout (see ). - /// - /// For a more complete example of how to implement custom input devices, check out the "Custom Device" - /// sample which you can install from the Unity package manager. - /// - /// And, as always, you can also find more information in the manual. - /// /// /// /// @@ -508,10 +511,26 @@ public virtual void MakeCurrent() /// /// /// This is called after the device has already been added. + /// + /// + /// /// - /// - /// - /// + /// + /// + /// using UnityEngine.InputSystem; + /// + /// public class MyDevice : InputDevice + /// { + /// public static MyDevice current { get; private set; } + /// protected override void OnAdded() + /// { + /// // use this context to assign the current device for instance + /// base.OnAdded(); + /// current = this; + /// } + /// } + /// + /// protected virtual void OnAdded() { } @@ -521,10 +540,27 @@ protected virtual void OnAdded() /// /// /// This is called after the device has already been removed. + /// + /// + /// /// - /// - /// - /// + /// + /// + /// 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; + /// } + /// } + /// + /// protected virtual void OnRemoved() { } @@ -542,7 +578,7 @@ protected virtual void OnRemoved() /// /// /// - /// /// + /// protected virtual void OnConfigurationChanged() { } @@ -560,8 +596,8 @@ protected virtual void OnConfigurationChanged() /// the device API. This is most useful for devices implemented in the native Unity runtime /// which, through the command interface, may provide custom, device-specific functions. /// - /// This is a low-level API. It works in a similar way to - /// DeviceIoControl on Windows and ioctl + /// This is a low-level API. It works in a similar way to + /// DeviceIoControl on Windows and ioctl /// on UNIX-like systems. /// public unsafe long ExecuteCommand(ref TCommand command) diff --git a/Packages/com.unity.inputsystem/InputSystem/Devices/Keyboard.cs b/Packages/com.unity.inputsystem/InputSystem/Devices/Keyboard.cs index 20b8e0ecb3..319e3cc4c0 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Devices/Keyboard.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Devices/Keyboard.cs @@ -17,24 +17,32 @@ namespace UnityEngine.InputSystem.LowLevel /// /// /// Can be used to update the state of devices. - /// + /// /// /// - /// // Send input event with A key pressed on keyboard. - /// InputSystem.QueueStateEvent(Keyboard.current, - /// new KeyboardState(Key.A)); + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// using UnityEngine.InputSystem.LowLevel; + /// + /// public class Example : MonoBehaviour + /// { + /// void Start() + /// { + /// // Send input event with A key pressed on keyboard. + /// InputSystem.QueueStateEvent(Keyboard.current, + /// new KeyboardState(Key.A)); + /// } + /// } /// /// - /// /// // NOTE: This layout has to match the KeyboardInputState layout used in native! [StructLayout(LayoutKind.Sequential)] public unsafe struct KeyboardState : IInputStateTypeInfo { /// - /// Memory format tag for KeybboardState. + /// Memory format tag for KeyboardState. Returns "KEYS". /// - /// Returns "KEYS". /// public static FourCC Format => new FourCC('K', 'E', 'Y', 'S'); @@ -220,17 +228,25 @@ namespace UnityEngine.InputSystem /// /// To find the text character (if any) generated by a key according to the currently active keyboard /// layout, use the property of . - /// + /// /// /// - /// // Look up key by key code. - /// var aKey = Keyboard.current[Key.A]; + /// using UnityEngine; + /// using UnityEngine.InputSystem; /// - /// // Find out which text is produced by the key. - /// Debug.Log($"The '{aKey.keyCode}' key produces '{aKey.displayName}' as text input"); + /// public class Example : MonoBehaviour + /// { + /// void LookUpTextInputByKey() + /// { + /// // Look up key by key code. + /// var aKey = Keyboard.current[Key.A]; + /// + /// // Find out which text is produced by the key. + /// Debug.Log($"The '{aKey.keyCode}' key produces '{aKey.displayName}' as text input"); + /// } + /// } /// /// - /// // NOTE: Has to match up with 'KeyboardInputState::KeyCode' in native. // NOTE: In the keyboard code, we depend on the order of the keys in the various keyboard blocks. public enum Key @@ -876,6 +892,32 @@ public enum Key /// keyboard or not. It is thus not possible to find out this way whether the underlying /// keyboard has certain keys or not. /// + /// + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// + /// public class InputExample : MonoBehaviour + /// { + /// private string inputText = ""; + /// void Start() + /// { + /// Keyboard.current.onTextInput += OnTextInput; + /// } + /// void Update() + /// { + /// // Check whether the A key on the current keyboard is pressed. + /// if (Keyboard.current.aKey.wasPressedThisFrame) + /// Debug.Log("A Key pressed"); + /// } + /// private void OnTextInput(char ch) + /// { + /// inputText += ch; + /// } + /// } + /// + /// + /// [InputControlLayout(stateType = typeof(KeyboardState), isGenericTypeOfDevice = true)] public class Keyboard : InputDevice, ITextInputReceiver { @@ -883,16 +925,18 @@ public class Keyboard : InputDevice, ITextInputReceiver /// Total number of key controls on a keyboard, i.e. the number of controls /// in . /// - /// Total number of key controls. public const int KeyCount = (int)Key.OEM5; /// /// Event that is fired for every single character entered on the keyboard. + /// See . /// - /// Triggered whenever the keyboard receives text input. - /// /// /// + /// using System; + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// /// // Let's say we want to do a typing game. We could define a component /// // something along those lines to match the typed input. /// public class MatchTextByTyping : MonoBehaviour @@ -932,7 +976,7 @@ public class Keyboard : InputDevice, ITextInputReceiver /// { /// ++m_Position; /// if (m_Position == m_Text.Length) - /// onTextTypeCorrectly?.Invoke(); + /// onTextTypedCorrectly?.Invoke(); /// } /// else /// { @@ -945,7 +989,6 @@ public class Keyboard : InputDevice, ITextInputReceiver /// } /// /// - /// public event Action onTextInput { add @@ -959,11 +1002,13 @@ public event Action onTextInput } /// - /// An event that is fired to get IME composition strings. Fired once for every change containing the entire string to date. - /// When using an IME, this event can be used to display the composition string while it is being edited. When a composition - /// string is submitted, one or many events will fire with the submitted characters. + /// When a user is entering text using IME composition, this event occurs each time the IME composition string changes, and provides the new composition string as a value. + /// When using an IME, this event can be used to display the composition string while it is being edited. /// /// + /// The composition string is held by the struct. + /// When a composition string is submitted, one or many events will fire with the submitted characters. + /// /// Some languages use complex input methods which involve opening windows to insert characters. /// Typically, this is not desirable while playing a game, as games may just interpret key strokes as game input, not as text. /// @@ -975,11 +1020,20 @@ public event Action onTextInput /// /// To subscribe to the onIMECompositionChange event, use the following sample code: /// - /// var compositionString = ""; - /// Keyboard.current.onIMECompositionChange += composition => + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// + /// public class KeyboardUtils : MonoBehaviour /// { - /// compositionString = composition.ToString(); - /// }; + /// private string compositionString = ""; + /// + /// void Start(){ + /// Keyboard.current.onIMECompositionChange += composition => + /// { + /// compositionString = composition.ToString(); + /// }; + /// } + /// } /// /// public event Action onIMECompositionChange @@ -995,7 +1049,7 @@ public event Action onIMECompositionChange } /// - /// Activates/deactivates IME composition while typing. This decides whether or not to use the OS supplied IME system. + /// Activates/deactivates IME composition while typing. This decides whether to use the OS supplied IME system or not. /// /// /// @@ -1006,6 +1060,28 @@ public event Action onIMECompositionChange /// See , , /// for more IME settings and data. /// + /// + /// The IME composition enabled state. to enable the IME, to disable it. + /// + /// + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// + /// public class KeyboardUtils : MonoBehaviour + /// { + /// private string compositionString = ""; + /// + /// void Start(){ + /// Keyboard.current.SetIMEEnabled(true); + /// Keyboard.current.onIMECompositionChange += composition => + /// { + /// compositionString = composition.ToString(); + /// }; + /// } + /// } + /// + /// public void SetIMEEnabled(bool enabled) { var command = EnableIMECompositionCommand.Create(enabled); @@ -1021,6 +1097,29 @@ public void SetIMEEnabled(bool enabled) /// /// See for turning IME on/off /// + /// + /// A Vector2 of the IME cursor position to set. + /// + /// + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// + /// public class KeyboardUtils : MonoBehaviour + /// { + /// private Vector2 cursorPosition; + /// + /// void Update () + /// { + /// // Set the IME cursor position to the mouse position + /// var x = Mouse.current.position.x.ReadValue(); + /// var y = Mouse.current.position.y.ReadValue(); + /// cursorPosition = new Vector2(x, y); + /// Keyboard.current.SetIMECursorPosition(cursorPosition); + /// } + /// } + /// + /// public void SetIMECursorPosition(Vector2 position) { SetIMECursorPositionCommand command = SetIMECursorPositionCommand.Create(position); @@ -1051,471 +1150,473 @@ public string keyboardLayout /// /// A synthetic button control that is considered pressed if any key on the keyboard is pressed. /// - /// Control representing the synthetic "anyKey". + /// representing the synthetic "anyKey". public AnyKeyControl anyKey { get; protected set; } /// - /// The space bar key. + /// The space bar key at the bottom of the keyboard. /// - /// Control representing the space bar key. + /// representing the space bar key. public KeyControl spaceKey => this[Key.Space]; /// /// The enter/return key in the main key block. /// - /// Control representing the enter key. /// + /// representing the enter key. /// This key is distinct from the enter key on the numpad which is . /// public KeyControl enterKey => this[Key.Enter]; /// - /// The tab key. + /// The tab key, which is generally located on the left side above the . /// - /// Control representing the tab key. + /// representing the tab key. public KeyControl tabKey => this[Key.Tab]; /// /// The ` key. The leftmost key in the row of digits. Directly above . /// - /// Control representing the backtick/quote key. + /// representing the backtick/quote key. public KeyControl backquoteKey => this[Key.Backquote]; /// /// The ' key. The key immediately to the left of . /// - /// Control representing the quote key. + /// representing the quote key. public KeyControl quoteKey => this[Key.Quote]; /// /// The ';' key. The key immediately to the left of . /// - /// Control representing the semicolon key. + /// representing the semicolon key. public KeyControl semicolonKey => this[Key.Semicolon]; /// /// The ',' key. Third key to the left of . /// - /// Control representing the comma key. + /// representing the comma key. public KeyControl commaKey => this[Key.Comma]; /// /// The '.' key. Second key to the left of . /// - /// Control representing the period key. + /// representing the period key. public KeyControl periodKey => this[Key.Period]; /// /// The '/' key. The key immediately to the left of . /// - /// Control representing the forward slash key. + /// representing the forward slash key. public KeyControl slashKey => this[Key.Slash]; /// /// The '\' key. The key immediately to the right of and /// next to or above . /// - /// Control representing the backslash key. + /// representing the backslash key. public KeyControl backslashKey => this[Key.Backslash]; /// /// The '[' key. The key immediately to the left of . /// - /// Control representing the left bracket key. + /// representing the left bracket key. public KeyControl leftBracketKey => this[Key.LeftBracket]; /// /// The ']' key. The key in-between to the left and /// to the right. /// - /// Control representing the right bracket key. + /// representing the right bracket key. public KeyControl rightBracketKey => this[Key.RightBracket]; /// /// The '-' key. The second key to the left of . /// - /// Control representing the minus key. + /// representing the minus key. public KeyControl minusKey => this[Key.Minus]; /// /// The '=' key in the main key block. The key in-between to the left /// and to the right. /// - /// Control representing the equals key. + /// representing the equals key. public KeyControl equalsKey => this[Key.Equals]; /// /// The 'a' key. The key immediately to the right of . /// - /// Control representing the a key. + /// representing the a key. public KeyControl aKey => this[Key.A]; /// /// The 'b' key. The key in-between the to the left and the /// to the right in the bottom-most row of alphabetic characters. /// - /// Control representing the b key. + /// representing the b key. public KeyControl bKey => this[Key.B]; /// /// The 'c' key. The key in-between the to the left and the /// to the right in the bottom-most row of alphabetic characters. /// - /// Control representing the c key. + /// representing the c key. public KeyControl cKey => this[Key.C]; /// /// The 'd' key. The key in-between the to the left and the /// to the right in the middle row of alphabetic characters. /// - /// Control representing the d key. + /// representing the d key. public KeyControl dKey => this[Key.D]; /// /// The 'e' key. The key in-between the to the left and the /// to the right in the topmost row of alphabetic characters. /// - /// Control representing the e key. + /// representing the e key. public KeyControl eKey => this[Key.E]; /// /// The 'f' key. The key in-between the to the left and the /// to the right in the middle row of alphabetic characters. /// - /// Control representing the f key. + /// representing the f key. public KeyControl fKey => this[Key.F]; /// /// The 'g' key. The key in-between the to the left and the /// to the right in the middle row of alphabetic characters. /// - /// Control representing the g key. + /// representing the g key. public KeyControl gKey => this[Key.G]; /// /// The 'h' key. The key in-between the to the left and the /// to the right in the middle row of alphabetic characters. /// - /// Control representing the h key. + /// representing the h key. public KeyControl hKey => this[Key.H]; /// /// The 'i' key. The key in-between the to the left and the /// to the right in the top row of alphabetic characters. /// + /// representing the i key. public KeyControl iKey => this[Key.I]; /// /// The 'j' key. The key in-between the to the left and the /// to the right in the middle row of alphabetic characters. /// - /// Control representing the j key. + /// representing the j key. public KeyControl jKey => this[Key.J]; /// /// The 'k' key. The key in-between the to the left and the /// to the right in the middle row of alphabetic characters. /// - /// Control representing the k key. + /// representing the k key. public KeyControl kKey => this[Key.K]; /// /// The 'l' key. The key in-between the to the left and the /// to the right in the middle row of alphabetic characters. /// - /// Control representing the l key. + /// representing the l key. public KeyControl lKey => this[Key.L]; /// /// The 'm' key. The key in-between the to the left and the /// to the right in the bottom row of alphabetic characters. /// - /// Control representing the m key. + /// representing the m key. public KeyControl mKey => this[Key.M]; /// /// The 'n' key. The key in-between the to the left and the to /// the right in the bottom row of alphabetic characters. /// - /// Control representing the n key. + /// representing the n key. public KeyControl nKey => this[Key.N]; /// /// The 'o' key. The key in-between the to the left and the to /// the right in the top row of alphabetic characters. /// - /// Control representing the o key. + /// representing the o key. public KeyControl oKey => this[Key.O]; /// /// The 'p' key. The key in-between the to the left and the /// to the right in the top row of alphabetic characters. /// - /// Control representing the p key. + /// representing the p key. public KeyControl pKey => this[Key.P]; /// /// The 'q' key. The key in-between the to the left and the /// to the right in the top row of alphabetic characters. /// - /// Control representing the q key. + /// representing the q key. public KeyControl qKey => this[Key.Q]; /// /// The 'r' key. The key in-between the to the left and the /// to the right in the top row of alphabetic characters. /// - /// Control representing the r key. + /// representing the r key. public KeyControl rKey => this[Key.R]; /// /// The 's' key. The key in-between the to the left and the /// to the right in the middle row of alphabetic characters. /// - /// Control representing the s key. + /// representing the s key. public KeyControl sKey => this[Key.S]; /// /// The 't' key. The key in-between the to the left and the /// to the right in the top row of alphabetic characters. /// - /// Control representing the t key. + /// representing the t key. public KeyControl tKey => this[Key.T]; /// /// The 'u' key. The key in-between the to the left and the /// to the right in the top row of alphabetic characters. /// - /// Control representing the u key. + /// representing the u key. public KeyControl uKey => this[Key.U]; /// /// The 'v' key. The key in-between the to the left and the /// to the right in the bottom row of alphabetic characters. /// - /// Control representing the v key. + /// representing the v key. public KeyControl vKey => this[Key.V]; /// /// The 'w' key. The key in-between the to the left and the /// to the right in the top row of alphabetic characters. /// - /// Control representing the w key. + /// representing the w key. public KeyControl wKey => this[Key.W]; /// /// The 'x' key. The key in-between the to the left and the /// to the right in the bottom row of alphabetic characters. /// - /// Control representing the x key. + /// representing the x key. public KeyControl xKey => this[Key.X]; /// /// The 'y' key. The key in-between the to the left and the /// to the right in the top row of alphabetic characters. /// - /// Control representing the y key. + /// representing the y key. public KeyControl yKey => this[Key.Y]; /// /// The 'z' key. The key in-between the to the left and the /// to the right in the bottom row of alphabetic characters. /// - /// Control representing the z key. + /// representing the z key. public KeyControl zKey => this[Key.Z]; /// /// The '1' key. The key in-between the to the left and the /// to the right in the row of digit characters. /// - /// Control representing the 1 key. + /// representing the 1 key. public KeyControl digit1Key => this[Key.Digit1]; /// /// The '2' key. The key in-between the to the left and the /// to the right in the row of digit characters. /// - /// Control representing the 2 key. + /// representing the 2 key. public KeyControl digit2Key => this[Key.Digit2]; /// /// The '3' key. The key in-between the to the left and the /// to the right in the row of digit characters. /// - /// Control representing the 3 key. + /// representing the 3 key. public KeyControl digit3Key => this[Key.Digit3]; /// /// The '4' key. The key in-between the to the left and the /// to the right in the row of digit characters. /// - /// Control representing the 4 key. + /// representing the 4 key. public KeyControl digit4Key => this[Key.Digit4]; /// /// The '5' key. The key in-between the to the left and the /// to the right in the row of digit characters. /// - /// Control representing the 5 key. + /// representing the 5 key. public KeyControl digit5Key => this[Key.Digit5]; /// /// The '6' key. The key in-between the to the left and the /// to the right in the row of digit characters. /// - /// Control representing the 6 key. + /// representing the 6 key. public KeyControl digit6Key => this[Key.Digit6]; /// /// The '7' key. The key in-between the to the left and the /// to the right in the row of digit characters. /// - /// Control representing the 7 key. + /// representing the 7 key. public KeyControl digit7Key => this[Key.Digit7]; /// /// The '8' key. The key in-between the to the left and the /// to the right in the row of digit characters. /// - /// Control representing the 8 key. + /// representing the 8 key. public KeyControl digit8Key => this[Key.Digit8]; /// /// The '9' key. The key in-between the to the left and the /// to the right in the row of digit characters. /// - /// Control representing the 9 key. + /// representing the 9 key. public KeyControl digit9Key => this[Key.Digit9]; /// /// The '0' key. The key in-between the to the left and the /// to the right in the row of digit characters. /// - /// Control representing the 0 key. + /// representing the 0 key. public KeyControl digit0Key => this[Key.Digit0]; /// /// The shift key on the left side of the keyboard. /// - /// Control representing the left shift key. + /// representing the left shift key. public KeyControl leftShiftKey => this[Key.LeftShift]; /// /// The shift key on the right side of the keyboard. /// - /// Control representing the right shift key. + /// representing the right shift key. public KeyControl rightShiftKey => this[Key.RightShift]; /// /// The alt/option key on the left side of the keyboard. /// - /// Control representing the left alt/option key. + /// representing the left alt/option key. public KeyControl leftAltKey => this[Key.LeftAlt]; /// /// The alt/option key on the right side of the keyboard. /// - /// Control representing the right alt/option key. + /// representing the right alt/option key. public KeyControl rightAltKey => this[Key.RightAlt]; /// /// The control/ctrl key on the left side of the keyboard. /// - /// Control representing the left control key. + /// representing the left control key. public KeyControl leftCtrlKey => this[Key.LeftCtrl]; /// /// The control/ctrl key on the right side of the keyboard. /// - /// This key is usually not present on Mac laptops. - /// Control representing the right control key. + /// + /// This key is usually not present on Mac laptops. + /// representing the right control key. + /// public KeyControl rightCtrlKey => this[Key.RightCtrl]; /// /// The system "meta" key (Windows key on PC, Apple/command key on Mac) on the left /// side of the keyboard. /// - /// Control representing the left system meta key. + /// representing the left system meta key. public KeyControl leftMetaKey => this[Key.LeftMeta]; /// /// The system "meta" key (Windows key on PC, Apple/command key on Mac) on the right /// side of the keyboard. /// - /// Control representing the right system meta key. + /// representing the right system meta key. public KeyControl rightMetaKey => this[Key.RightMeta]; /// /// Same as . Windows system key on left side of keyboard. /// - /// Control representing the left Windows system key. + /// representing the left Windows system key. public KeyControl leftWindowsKey => this[Key.LeftWindows]; /// /// Same as . Windows system key on right side of keyboard. /// - /// Control representing the right Windows system key. + /// representing the right Windows system key. public KeyControl rightWindowsKey => this[Key.RightWindows]; /// /// Same as . Apple/command system key on left side of keyboard. /// - /// Control representing the left Apple/command system key. + /// representing the left Apple/command system key. public KeyControl leftAppleKey => this[Key.LeftApple]; /// /// Same as . Apple/command system key on right side of keyboard. /// - /// Control representing the right Apple/command system key. + /// representing the right Apple/command system key. public KeyControl rightAppleKey => this[Key.RightApple]; /// /// Same as . Apple/command system key on left side of keyboard. /// - /// Control representing the left Apple/command system key. + /// representing the left Apple/command system key. public KeyControl leftCommandKey => this[Key.LeftCommand]; /// /// Same as . Apple/command system key on right side of keyboard. /// - /// Control representing the right Apple/command system key. + /// representing the right Apple/command system key. public KeyControl rightCommandKey => this[Key.RightCommand]; /// - /// The context menu key. This key is generally only found on PC keyboards. If present, - /// the key is found in-between the to the left and the - /// to the right. It's intention is to bring up the context - /// menu according to the current selection. + /// The context menu key. This key is generally only found on PC keyboards. + /// If present, it is located in-between the and the + /// . It brings up the context menu according to the current selection. /// - /// Control representing the context menu key. + /// representing the context menu key. public KeyControl contextMenuKey => this[Key.ContextMenu]; /// /// The escape key, i.e. the key generally in the top left corner of the keyboard. /// Usually to the left of . /// - /// Control representing the escape key. + /// representing the escape key. public KeyControl escapeKey => this[Key.Escape]; /// /// The left arrow key. Usually in a block by itself and generally to the left /// of . /// - /// Control representing the left arrow key. + /// representing the left arrow key. public KeyControl leftArrowKey => this[Key.LeftArrow]; /// /// The right arrow key. Usually in a block by itself and generally to the right /// of /// - /// Control representing the right arrow key. + /// representing the right arrow key. public KeyControl rightArrowKey => this[Key.RightArrow]; /// /// The up arrow key. Usually in a block by itself and generally on top of the /// . /// - /// Control representing the up arrow key. + /// representing the up arrow key. public KeyControl upArrowKey => this[Key.UpArrow]; /// @@ -1523,15 +1624,16 @@ public string keyboardLayout /// and in-between to the /// left and to the right. /// - /// Control representing the down arrow key. + /// representing the down arrow key. public KeyControl downArrowKey => this[Key.DownArrow]; /// /// The backspace key (usually labeled "delete" on Mac). The rightmost key /// in the top digit row with to the left. /// - /// Control representing the backspace key. /// + /// representing the backspace key. + /// /// On the Mac, this key may be labeled "delete" which however is a /// key different from . /// @@ -1541,43 +1643,44 @@ public string keyboardLayout /// The page down key. Usually in a separate block with /// to the left and above it. /// - /// Control representing the page down key. + /// representing the page down key. public KeyControl pageDownKey => this[Key.PageDown]; /// /// The page up key. Usually in a separate block with /// to the left and below it. /// - /// Control representing the page up key. + /// representing the page up key. public KeyControl pageUpKey => this[Key.PageUp]; /// /// The 'home' key. Usually in a separate block with /// to the right and to the left. /// - /// Control representing the insert key. + /// representing the insert key. public KeyControl homeKey => this[Key.Home]; /// /// The 'end' key. Usually in a separate block with /// to the left and to the right. /// - /// Control representing the end key. + /// representing the end key. public KeyControl endKey => this[Key.End]; /// /// The 'insert' key. Usually in a separate block with /// to its right and sitting below it. /// - /// Control representing the insert key. + /// representing the insert key. public KeyControl insertKey => this[Key.Insert]; /// /// The 'delete' key. Usually in a separate block with /// to its right and sitting above it. /// - /// Control representing the delete key. /// + /// representing the delete key. + /// /// On the Mac, the is also labeled "delete". /// However, this is not this key. /// @@ -1587,7 +1690,7 @@ public string keyboardLayout /// The Caps Lock key. The key below and above /// . /// - /// Control representing the caps lock key. + /// representing the caps lock key. public KeyControl capsLockKey => this[Key.CapsLock]; /// @@ -1595,7 +1698,7 @@ public string keyboardLayout /// to the left and the to the right. May also /// be labeled "F14". /// - /// Control representing the scroll lock key. + /// representing the scroll lock key. public KeyControl scrollLockKey => this[Key.ScrollLock]; /// @@ -1603,7 +1706,7 @@ public string keyboardLayout /// numpad and which usually toggles the numpad between generating /// digits and triggering functions like "insert" etc. instead. /// - /// Control representing the num lock key. + /// representing the num lock key. public KeyControl numLockKey => this[Key.NumLock]; /// @@ -1611,29 +1714,30 @@ public string keyboardLayout /// to the left and to the right. May also /// be labeled "F13". /// - /// Control representing the print screen key. + /// representing the print screen key. public KeyControl printScreenKey => this[Key.PrintScreen]; /// /// The pause/break key. The key sitting to the left of . /// May also be labeled "F15". /// - /// Control representing the pause/break key. + /// representing the pause/break key. public KeyControl pauseKey => this[Key.Pause]; /// /// The enter key on the numpad. The key sitting in the bottom right corner /// of the numpad. /// - /// Control representing the numpad enter key. + /// representing the numpad enter key. public KeyControl numpadEnterKey => this[Key.NumpadEnter]; /// /// The divide ('/') key on the numpad. The key in-between /// to the left and to the right. /// - /// Control representing the numpad divide key. /// + /// representing the numpad divide key. + /// /// PC keyboards usually have a 17-key numpad layout that differs from the 18-key layout /// we use for reference. The 18-key layout is usually found on Mac keyboards. The numpad /// divide key usually is the on PC keyboards. @@ -1645,8 +1749,9 @@ public string keyboardLayout /// with to the left and /// below it. /// - /// Control representing the numpad multiply key. /// + /// representing the numpad multiply key. + /// /// PC keyboards usually have a 17-key numpad layout that differs from the 18-key layout /// we use for reference. The 18-key layout is usually found on Mac keyboards. The numpad /// multiply key usually is the on PC keyboards. @@ -1657,8 +1762,9 @@ public string keyboardLayout /// The minus ('-') key on the numpad. The key on the right side of the numpad with /// above it and below it. /// - /// Control representing the numpad minus key. /// + /// representing the numpad minus key. + /// /// PC keyboards usually have a 17-key numpad layout that differs from the 18-key layout /// we use for reference. The 18-key layout is usually found on Mac keyboards. The numpad /// minus key is usually not present on PC keyboards. Instead, the 17-key layout @@ -1670,8 +1776,9 @@ public string keyboardLayout /// The plus ('+') key on the numpad. The key on the right side of the numpad with /// above it and below it. /// - /// Control representing the numpad plus key. /// + /// representing the numpad plus key. + /// /// PC keyboards usually have a 17-key numpad layout that differs from the 18-key layout /// we use for reference. The 18-key layout is usually found on Mac keyboards. /// @@ -1687,8 +1794,9 @@ public string keyboardLayout /// The period ('.') key on the numpad. The key in-between the /// to the right and the to the left. /// - /// Control representing the numpad period key. /// + /// representing the numpad period key. + /// /// This key is the same in 17-key and 18-key numpad layouts. /// public KeyControl numpadPeriodKey => this[Key.NumpadPeriod]; @@ -1697,8 +1805,9 @@ public string keyboardLayout /// The equals ('=') key on the numpad. The key in-between to the left /// and to the right in the top row of the numpad. /// - /// Control representing the numpad equals key. /// + /// representing the numpad equals key. + /// /// PC keyboards usually have a 17-key numpad layout that differs from the 18-key layout /// we use for reference. The 18-key layout is usually found on Mac keyboards. /// @@ -1711,63 +1820,63 @@ public string keyboardLayout /// The 0 key on the numpad. The key in the bottom left corner of the numpad. Usually /// and elongated key. /// - /// Control representing the numpad 0 key. + /// representing the numpad 0 key. public KeyControl numpad0Key => this[Key.Numpad0]; /// /// The 1 key on the numpad. The key on the left side of the numpad with /// below it and above it. /// - /// Control representing the numpad 1 key. + /// representing the numpad 1 key. public KeyControl numpad1Key => this[Key.Numpad1]; /// /// The 2 key on the numpad. The key with the to its left and /// the to its right. /// - /// Control representing the numpad 2 key. + /// representing the numpad 2 key. public KeyControl numpad2Key => this[Key.Numpad2]; /// /// The 3 key on the numpad. The key with the to its left and /// the to its right. /// - /// Control representing the numpad 3 key. + /// representing the numpad 3 key. public KeyControl numpad3Key => this[Key.Numpad3]; /// /// The 4 key on the numpad. The key on the left side of the numpad with the /// below it and the above it. /// - /// Control representing the numpad 4 key. + /// representing the numpad 4 key. public KeyControl numpad4Key => this[Key.Numpad4]; /// /// The 5 key on the numpad. The key in-between the to the left and the /// to the right. /// - /// Control representing the numpad 5 key. + /// representing the numpad 5 key. public KeyControl numpad5Key => this[Key.Numpad5]; /// /// The 6 key on the numpad. The key in-between the to the let and /// the to the right. /// - /// Control representing the numpad 6 key. + /// representing the numpad 6 key. public KeyControl numpad6Key => this[Key.Numpad6]; /// /// The 7 key on the numpad. The key on the left side of the numpad with /// below it and above it. /// - /// Control representing the numpad 7 key. + /// representing the numpad 7 key. public KeyControl numpad7Key => this[Key.Numpad7]; /// /// The 8 key on the numpad. The key in-between the to the left and the /// to the right. /// - /// Control representing the numpad 8 key. + /// representing the numpad 8 key. public KeyControl numpad8Key => this[Key.Numpad8]; /// @@ -1775,98 +1884,99 @@ public string keyboardLayout /// the to the right (or, on 17-key PC keyboard numpads, the elongated /// plus key). /// - /// Control representing the numpad 9 key. + /// representing the numpad 9 key. public KeyControl numpad9Key => this[Key.Numpad9]; /// /// The F1 key. The key in-between to the left and /// to the right in the topmost row of keys. /// - /// Control representing the F1 key. + /// representing the F1 key. public KeyControl f1Key => this[Key.F1]; /// /// The F2 key. The key in-between to the left and /// to the right in the topmost row of keys. /// - /// Control representing the F2 key. + /// representing the F2 key. public KeyControl f2Key => this[Key.F2]; /// /// The F3 key. The key in-between to the left and /// to the right in the topmost row of keys. /// - /// Control representing the F3 key. + /// representing the F3 key. public KeyControl f3Key => this[Key.F3]; /// /// The F4 key. The key in-between to the left and /// to the right in the topmost row of keys. /// - /// Control representing the F4 key. + /// representing the F4 key. public KeyControl f4Key => this[Key.F4]; /// /// The F5 key. The key in-between to the left and /// to the right in the topmost row of keys. /// - /// Control representing the F5 key. + /// representing the F5 key. public KeyControl f5Key => this[Key.F5]; /// /// The F6 key. The key in-between to the left and /// to the right in the topmost row of keys. /// - /// Control representing the F6 key. + /// representing the F6 key. public KeyControl f6Key => this[Key.F6]; /// /// The F7 key. The key in-between to the left and /// to the right in the topmost row of keys. /// - /// Control representing the F7 key. + /// representing the F7 key. public KeyControl f7Key => this[Key.F7]; /// /// The F8 key. The key in-between to the left and /// to the right in the topmost row of keys. /// - /// Control representing the F8 key. + /// representing the F8 key. public KeyControl f8Key => this[Key.F8]; /// /// The F9 key. The key in-between to the left and /// to the right in the topmost row of keys. /// - /// Control representing the F9 key. + /// representing the F9 key. public KeyControl f9Key => this[Key.F9]; /// /// The F10 key. The key in-between to the left and /// to the right in the topmost row of keys. /// - /// Control representing the F10 key. + /// representing the F10 key. public KeyControl f10Key => this[Key.F10]; /// /// The F11 key. The key in-between to the left and /// to the right in the topmost row of keys. /// - /// Control representing the F11 key. + /// representing the F11 key. public KeyControl f11Key => this[Key.F11]; /// /// The F12 key. The key in-between to the left and /// to the right in the topmost row of keys. /// - /// Control representing the F12 key. + /// representing the F12 key. public KeyControl f12Key => this[Key.F12]; /// /// First additional key on the keyboard. /// - /// Control representing . /// + /// representing . + /// /// Keyboards may have additional keys that are not part of the standardized 104-key keyboard layout /// (105 in the case of an 18-key numpad). For example, many non-English keyboard layouts have an additional /// key in-between and . @@ -1880,8 +1990,9 @@ public string keyboardLayout /// /// Second additional key on the keyboard. /// - /// Control representing . /// + /// representing . + /// /// Keyboards may have additional keys that are not part of the standardized 104-key keyboard layout /// (105 in the case of an 18-key numpad). For example, many non-English keyboard layouts have an additional /// key in-between and . @@ -1895,8 +2006,9 @@ public string keyboardLayout /// /// Third additional key on the keyboard. /// - /// Control representing . /// + /// representing . + /// /// Keyboards may have additional keys that are not part of the standardized 104-key keyboard layout /// (105 in the case of an 18-key numpad). For example, many non-English keyboard layouts have an additional /// key in-between and . @@ -1910,8 +2022,9 @@ public string keyboardLayout /// /// Fourth additional key on the keyboard. /// - /// Control representing . /// + /// representing . + /// /// Keyboards may have additional keys that are not part of the standardized 104-key keyboard layout /// (105 in the case of an 18-key numpad). For example, many non-English keyboard layouts have an additional /// key in-between and . @@ -1925,8 +2038,9 @@ public string keyboardLayout /// /// Fifth additional key on the keyboard. /// - /// Control representing . /// + /// representing . + /// /// Keyboards may have additional keys that are not part of the standardized 104-key keyboard layout /// (105 in the case of an 18-key numpad). For example, many non-English keyboard layouts have an additional /// key in-between and . @@ -1940,8 +2054,9 @@ public string keyboardLayout /// /// An artificial combination of and into one control. /// - /// Control representing a combined left and right shift key. /// + /// representing a combined left and right shift key. + /// /// This is a button which is considered pressed whenever the left and/or /// right shift key is pressed. /// @@ -1950,8 +2065,9 @@ public string keyboardLayout /// /// An artificial combination of and into one control. /// - /// Control representing a combined left and right ctrl key. /// + /// representing a combined left and right ctrl key. + /// /// This is a button which is considered pressed whenever the left and/or /// right ctrl key is pressed. /// @@ -1960,8 +2076,9 @@ public string keyboardLayout /// /// An artificial combination of and into one control. /// - /// Control representing a combined left and right alt key. /// + /// representing a combined left and right alt key. + /// /// This is a button which is considered pressed whenever the left and/or /// right alt key is pressed. /// @@ -1971,9 +2088,8 @@ public string keyboardLayout /// True when IME composition is enabled. Requires to be called to enable IME, and the user to enable it at the OS level. /// /// - /// /// Some languages use complex input methods which involve opening windows to insert characters. - /// Typically, this is not desirable while playing a game, as games may just interpret key strokes as game input, not as text. + /// Typically, this is not desirable while playing a game, as games may just interpret keystrokes as game input, not as text. /// /// See for turning IME on/off /// @@ -1983,7 +2099,7 @@ public string keyboardLayout /// Look up a key control by its key code. /// /// Key code of key control to return. - /// The given is not valid. + /// The given is not valid. /// /// This is equivalent to allKeys[(int)key - 1]. /// @@ -2008,22 +2124,35 @@ public KeyControl this[Key key] /// public static Keyboard current { get; private set; } - /// - /// Make the keyboard the current keyboard (i.e. ). - /// + /// /// /// A keyboard will automatically be made current when receiving input or when /// added to the input system. + /// The currently active keyboard is tracked in . /// + /// + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// + /// public class InputExample : MonoBehaviour + /// { + /// void Start() + /// { + /// // Add a keyboard and make it the current keyboard. + /// var keyboard = InputSystem.AddDevice("Keyboard"); + /// keyboard.MakeCurrent(); + /// } + /// } + /// + /// public override void MakeCurrent() { base.MakeCurrent(); current = this; } - /// - /// Called when the keyboard is removed from the system. - /// + /// protected override void OnRemoved() { base.OnRemoved(); @@ -2035,6 +2164,27 @@ protected override void OnRemoved() /// Called after the keyboard has been constructed but before it is added to /// the system. /// + /// + /// 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. + /// + /// + /// + /// using UnityEngine.InputSystem; + /// using UnityEngine.InputSystem.Controls; + /// + /// public class MyKeyboard : Keyboard + /// { + /// public ButtonControl button { get; private set; } + /// + /// protected override void FinishSetup() + /// { + /// // Cache controls in getters. + /// button = (ButtonControl)GetChildControl("button"); + /// } + /// } + /// + /// protected override void FinishSetup() { var keyStrings = new[] @@ -2182,11 +2332,26 @@ protected override void RefreshConfiguration() /// /// Called when text input on the keyboard is received. /// - /// Character that has been entered. + /// A type value that represents the character that has been entered. /// - /// The system will call this automatically whenever a is - /// received that targets the keyboard device. + /// The system will call this method automatically whenever a is + /// received that targets the keyboard device. Subscribe to this event by using . /// + /// + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// + /// public class OnTextInputExample : MonoBehaviour + /// { + /// // Simulate text input event on the current keyboard. + /// private void FakeInput() + /// { + /// Keyboard.current.OnTextInput('a'); + /// } + /// } + /// + /// public void OnTextInput(char character) { for (var i = 0; i < m_TextInputListeners.length; ++i) @@ -2204,11 +2369,22 @@ public void OnTextInput(char character) /// In most cases, this means that the key inputs the given text when pressed. However, this does not have to be the /// case. Keys do not necessarily lead to character input. /// + /// /// - /// // Find key that prints 'q' character (if any). - /// Keyboard.current.FindKeyOnCurrentKeyboardLayout("q"); + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// + /// public class KeyboardUtils : MonoBehaviour + /// { + /// private void FindKey() + /// { + /// // Retrieve the q key on the current keyboard layout. + /// Keyboard.current.FindKeyOnCurrentKeyboardLayout("q"); + /// } + /// } + /// /// - /// /// public KeyControl FindKeyOnCurrentKeyboardLayout(string displayName) { @@ -2219,6 +2395,33 @@ public KeyControl FindKeyOnCurrentKeyboardLayout(string displayName) return null; } + /// + /// This is called to set the IME composition strings. Fired once for every change containing the entire string. + /// + /// The for the IME composition. + /// + /// To call back to the changed composition string, subscribe to the event. + /// + /// + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// using UnityEngine.InputSystem.LowLevel; + /// + /// public class KeyboardUtils : MonoBehaviour + /// { + /// private string compositionString = ""; + /// void ChangeIMEComposition() + /// { + /// // Manually creating an input event to change the IME composition + /// var inputEvent = IMECompositionEvent.Create(Keyboard.current.deviceId, "CompositionTestCharacters! ɝ", Time.time); + /// Keyboard.current.OnIMECompositionChanged(inputEvent.compositionString); + /// } + /// } + /// + /// + /// + /// public void OnIMECompositionChanged(IMECompositionString compositionString) { if (m_ImeCompositionListeners.length > 0)