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 Floating Style

The IME Floating Style is disabled by default. It is supported starting from 2022 products (since Tizen 6.5).

• Enable IME Floating Style:

<tizen:metadata key="http://samsung.com/tv/metadata/use.conformant" value="floating"/>

IME Return Key

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

• For the password input type with a minlength attribute, the initial IME Return Key (“Done” or “Go”) is disabled until the input text length meets the definited minlength. Once the input text length meets the minimum, the IME Return Key is enabled.

  <input type ="password" minlength=6>
  

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

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

IME Enable/Disable

Using IME to interact with the application is enabled by default. But if an application wants to disable the IME, set the requisite metadata key as false.

• Disable IME Method:

<tizen:metadata key="http://samsung.com/tv/metadata/use.ime" value="false"/>

• Disable 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 is shown based on user action, such as pressing on an editable element with the Remote Control or clicking on an editable element with the mouse; the IME can also be shown based on non-user action. The table below 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 is hidden by user action, such as pressing the “Back” key on the Remote Control or pressing the “Done” key on the IME; it can also be hidden based on non-user action. The table below 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 pressed, 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.