Keyboard Support

The Keyboard class defines a device with a set of keys controls defined by the Key enumeration.

The location of individual keys is agnostic to keyboard layout meaning that, for example, the A key is always the key to the right of the Caps Lock key regardless of where the currently active language layout places the key that generates an A character (if the layout even has a key assigned to that character).

To query which (if any) character is generated by given key, use the key's displayName property. The value of the property will change automatically when the keyboard layout is changed at the system level.

Keys can be looked up by their produced character using control paths. For example, the key producing the "a" character can be queried from Keyboard using Keyboard.current["#(a)"].

NOTE: We do not yet support on-screen keyboards in the new input system. For now, please Unity's existing API in UnityEngine.TouchScreenKeyboard.

Controls

A given key can be retrieved from Keyboard using either one of the accessor properties (e.g. Keyboard.spaceKey) or using Keyboard's indexer and the Key enumeration (e.g. keyboard[Key.Space].

Look at the scripting API reference for the Keyboard class to look up all the properties for the individual key controls.

Two special controls worth pointing out here are the anyKey and the imeSelected controls, both of which don't directly map to individual keys. anyKey is a synthetic button control which will report whether any key on the keyboard is pressed.

imeSelected will report whether IME text processing is enabled or not.

Text Input

It is recommended to not manually translate text input from key presses by trying to trying to string together the characters corresponding to the keys. Instead, to listen to text input, hook into Keyboard.onTextInput. This will deliver character-by-character input as reported by the platform (including input from on-screen keyboards).

Note that the text input API does not allocate GC memory as it does not deliver fully composed strings.

Keyboard Layouts

The name of the current keyboard layout can be queried with Keyboard.keyboardLayout. Note that the names are platform-specific.

There is no support for setting keyboard layouts from the application.

To monitor for when the keyboard layout changes, hook into InputSystem.onDeviceChange and check for InputDeviceChange.ConfigurationChanged on a Keyboard device.

IME

Some writing systems (for instance several east asian scripts) are too complex to represent all characters as individual keys on a keyboard. In those cases, 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. When using Unity's UI frameworks for text input, these will take care of handling IME for you, so you don't need to deal with this. However, when you are building your own UI for text input, the Keyboard class lets you work with input from IMEs using the following APIs:

• imeSelected is a virtual input control, which will report whether IME text processing is enabled or not.

• SetIMEEnabled() is a method which lets you turn IME processing on or off. Typically, IME processing is desirable when the user wants to edit text, but not so much when the user is using the keyboard to control a game.

• SetIMECursorPosition(). IMEs may open system windows which let users interactively edit the text they want to input. These are expected to open up next to the UI used for text editing. You can use the SetIMECursorPosition() method to tell the OS where that is.

• onIMECompositionChange is an event you can subscribe to to receive any updates to the IME composition string. The composition string is the text input the user is currently editing using an IME. It is expected that 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.