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 2. IME

IME Layout

IME support two layouts of QWERTY and ABC. If input type is email and password, use the QWERTY style layout. Otherwise, use the ABC style layout.

Figure 3. QWERTY layout: Conventional Order
Figure 4. ABC layout: Alphabetical Order


IME Return Key

  • For email/number/password/tel/url/text input type，use “Done” as the default Return Key. When these input element is in form tag, use “Go” as Return Key.

Figure 5. Done as the IME Return Key
Figure 6. Go as the IME Return Key

  • For password input type with minlength attributes, the initial IME Return Key(“Done” or “Go”) is disabled; and until the input text length meet minlength, the IME Return Key been enabled:

    <input type ="password" minlength=6>

  • For search input type, use search icon as the Return Key.

Figure 7. Search icon as the IME Return Key

  • For textarea tag and contenteditable attributes, use “Go” as the Return Key.

Figure 8. Go as the IME Return Key

IME Enable/Disable

Using IME to interacts with the application is enabled by default. But if application want to disable it, application can set as the table:

  • Disbale IME Method:
<tizen:metadata key="http://samsung.com/tv/metadata/use.ime" value="false"/>
  • Disbale IME only when non-user action Method:
<tizen:metadata key="http://samsung.com/tv/metadata/use.keypad.without.useraction" value="false"/>

IME Show/Hide Scene

  • IME Show Scene
    IME will be shown by user action, such as press on editable element by Remote Control or click on the editable element by mouse; also can be shown by non-user action. The table lists the whole scene of IME show.
Input Device Operation to Show IME
Remote Control Press “Enter” key on the input element by Remote Control
Mouse Click on the input element by mouse
js js set focus to the input element

Table 2. IME show scene table

  • IME Hide Scene
    IME will be hidded by user action, such as press the “Back” key on Remote Control or press the “Done” key on IME, also can be hidden by non-user action.The table lists the whole scene of IME hide:
Input Device Operation to Hide IME
Remote Control When IME shows, Press “Done”/“Go”/“Search” key on IME panel by Remote Control
When IME shows, press “Back” key on Remote Control
When IME shows, move the focus on the top of IME, then press “Up” key on Remote Control
keyboard When IME shows, connect a physical keyboard, and press any key on the physical keyboard
Mouse When IME shows, click “Done”/“Go”/“Search” key on IME panel by Mouse
When IME shows, click any uneditable element which out of IME
js When IME shows, js change the current focused input element to uneditable or blur.

Table 3. IME hide scene table


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.

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

Table 5. Keyboard equivalents to remote control keys

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

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

Table 6. IME keyCode values

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" key 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" 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;
  }
});