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.

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.

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.

• 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.

• For textarea tag and contenteditable attributes, use “Go” as the 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.

Table 5. Keyboard equivalents to remote control keys

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

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

  ImportantThe 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.