This is an extended button control which adds various features to account for the fact that keys have symbols associated with them which may change depending on keyboard layout as well as in combination with other keys.

Note: Unity input system key codes and input manager key codes are designed with game controls in mind.

This means the way they are assigned is intended to preserve the location of keys on keyboards, so that pressing a key in the same location on different keyboards should result in the same action regardless of what is printed on a key or what current system language is set.

This means, for example, that A is always the key to the right of CapsLock, regardless of which key (if any) produces the "a" character on the current keyboard layout.

Unity relies on physical hardware in the keyboards to report same USB HID "usage" for the keys in the same location.This puts a practical limit on what can be achieved, because different keyboards might report different data, and this is outside of Unity's control.

For this reason, you should not use key codes to read text input. Instead, you should use the onTextInput callback. The onTextInput callback provides you with the actual text characters which correspond to the symbols printed on a keyboard, based on the end user's current system language layout.

To find the text character (if any) generated by a key according to the currently active keyboard layout, use the displayName property of KeyControl.

Properties

keyCode

The code used in Unity to identify the key.

Declaration

public Key keyCode { get; set; }

Property Value

Type	Description
Key

Remarks

This property must be initialized by FinishSetup() of the device owning the control. You should not use keyCode to read text input. For more information, KeyControl

scanCode

The code that the underlying platform uses to identify the key.

Declaration

public int scanCode { get; }

Property Value

Type	Description
int

Methods

RefreshConfiguration()

Refresh the configuration of the control. This is used to update the control's state (e.g. Keyboard Layout or display Name of Keys).

Declaration

protected override void RefreshConfiguration()

Overrides

InputControl.RefreshConfiguration()

Remarks

The system will call this method automatically whenever a change is made to one of the control's configuration properties. This method is only relevant if you are implementing your own devices or new types of controls which are fetching configuration data from the devices (such as KeyControl which is fetching display names for individual keys from the underlying platform). See RefreshConfigurationIfNeeded().

Examples

  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;
                                }
                            }
                        }