top

Keyboard/IME

This topic describes how your application can receive input from a physical keyboard or a virtual keyboard (IME).

The user can interact with your application by entering text with a virtual keyboard (IME). When an input or textarea element in your application is focused, the virtual keyboard is shown.

The user can also connect a physical keyboard to the TV to enter text more conveniently. When a physical keyboard is connected, the IME is automatically hidden by pressing any key on the physical keyboard.

Figure 1. Physical keyboard

Figure 1. Physical keyboard

Figure 2. IME

Figure 2. IME

Detecting Keyboard and IME Input

Keyboard and IME input is detected in much the same way as remote control input, except that you do not need to register individual keyboard and IME keys.

Some of the keys on a physical keyboard correspond to keys on the TV remote control.

Table 1. Keyboard equivalents to remote control keys
Remote Control Key Keyboard Key Remote Control Key Keyboard Key
ArrowLeft Left Smart Hub F5
ArrowUp Up Source F6
ArrowRight Right ChannelList F7
ArrowDown Down VolumeMute F8
Enter Enter VolumeDown F9
Back ESC VolumeUp F10
ChannelDown F11
ChannelUp F12

The keyCode for most IME keys is 229, but special keys have unique keyCode values.

Table 2. IME keyCode values
IME Key keyCode IME Key keyCode IME Key keyCode
Done 65376 Left 37 Space 32
Cancel 65385 Up 38 Backspace 8
Right 39 Delete All 46
Other keys 229 Down 40

When a physical keyboard is connected, an input or textarea element is focused, and the IME is hidden, the physical keyboard acts in place of the IME and sends the IME keyCode values. For example, pressing “Enter” on the keyboard sends the keyCode for the IME “Done” key, not the remote control “Enter” key; pressing “Esc” on the keyboard sends the keyCode for the IME “Cancel” key, not the remote control “Back” key.

Handling the IME

The IME is automatically shown when an input or textarea element is focused, and hidden when the element loses focus.

  • To handle the IME input, create listeners for the input element events:

    • The focus event is fired when the input element is focused.
    • The blur event is fired when the input element loses focus.
    • The change event is fired when the value of the input element changes.
    <input id='input' type='text'>
    
    document.getElementById('input').addEventListener('focus', function() {
      console.log("input element is focused and ready to get user input.");
    });
    
    document.getElementById('input').addEventListener('blur', function() {
      console.log("input element loses focus.");
    });
    
    document.getElementById('input').addEventListener('change', function() {
      console.log("input element value is changed.");
    });
    
  • To retrieve the user input value:

    var value = document.getElementById('input').value;  
    console.log(value); 
    
  • To close the IME when the “Done” or “Cancel” IME key, or the remote control “Back” key, is clicked, listen for the appropriate keyCode values. You must also remove focus from the input element:

document.body.addEventListener('keydown', function(event) {
  switch (event.keyCode) {
    case 65376: // Done
      document.getElementById('input').blur();
      break;
    case 65385: // Cancel
      document.getElementById('input').blur();
      break;
  }
});
Note

If you do not blur the input element when the IME closes, the remote control keys send the wrong keyCode values. When the IME is visible, clicking the remote control “Back” key sends a keyCode value of 65285 (for “Cancel”) and hides the IME. However, if the input element is still focused, clicking the “Back” key again sends a keyCode value of 229 (for an IME key) instead of the expected 10009 value (for the remote control “Back” key).

Important

The preventDefault() method prevents the default action (insert or delete text) of the input element from triggering. Do not call the preventDefault() method for the keydown event.