Site Logo

System UI Visibility

From webOS TV 3.0, the visibility of the virtual keyboard and the cursor can be detected by using the following events:

  • keyboardStateChange: Visibility event for the virtual keyboard.
  • cursorStateChange: Visibility event for the cursor of the Magic Remote or HID pointing device.

You can use these events in your app to figure out whether the cursor is on for navigation with Magic Remote or whether your app has the focus and can receive pointer inputs.

Visibility of the virtual keyboard

When the virtual keyboard appears or disappears, a keyboardStateChange event is raised. It returns the event.detail.visibility property with one of the following values:

  • true, if the virtual keyboard appeared.
  • false, if the virtual keyboard disappeared.
Note

The keyboardStateChange event is raised twice by the voice button on the virtual keyboard. When the voice button is selected, the virtual keyboard disappears for a while, and the voice UI comes up. When the virtual keyboard disappears, the visibility value of the keyboardStateChange event changes from true to false. After a while, when the voice UI comes up, the value changes back to true.

The following code snippet shows how to handle the keyboardStateChange event.

function keyboardVisibilityChange(event) {
  var visibility = event.detail.visibility;
  if (visibility) {
    console.log('Virtual keyboard appeared');
    // Do something.
  } else {
    console.log('Virtual keyboard disappeared');
    // Do something.
  }
}
document.addEventListener(
  'keyboardStateChange',
  keyboardVisibilityChange,
  false
);

You can examine the visibility of the virtual keyboard using the code below.

<html>
  <head>
    <script>
      function load() {
        document.addEventListener(
          'keyboardStateChange',
          keyboardVisibilityChange,
          false
        );
        var textinput = document.getElementById('text1');
        textinput.addEventListener('input', inputfunc, false);
        textinput.addEventListener('change', inputfunc, false);
        textinput.addEventListener('keypress', keyfunc, false);
        textinput.addEventListener('keyup', keyfunc, false);
        textinput.addEventListener('keydown', keyfunc, false);
      }

      function keyboardVisibilityChange(event) {
        var visibility = event.detail.visibility;
        if (visibility) Log('Virtual keyboard appeared');
        else Log('Virtual keyboard disappeared');
      }

      function inputfunc(event) {
        var x = document.getElementById('text1');
        Log(event.type + ': ' + x.value);
      }

      function keyfunc(event) {
        Log(
          event.type + ': keyCode=' + event.keyCode + ' which=' + event.which
        );
      }

      var line = 0;
      function Log(msg) {
        console.log(msg);
        document.getElementById('log').innerHTML +=
          ++line + ': ' + msg + '<br>';
      }
    </script>
  </head>
  <body onload="load()" style="background-color:black; color:white">
    <input id="text1" type="text" />
    <div id="log"></div>
  </body>
</html>

This code also includes event handlers for key input (input, change, keypress, keyup, and keydown) events. Details about each key input event handler are as follows:

  • input event handler : Detects every character input in a text input field.
  • change event handler : Detects a value change in a text input field.
  • keypress, keyup, and keydown event handlers : These are usually used for detecting keypresses. However, they do not work on the virtual keyboard, except control keys such as enter and back space. Therefore, the keyfunc callback function in the code above will not work when using the virtual keyboard.

Visibility of the cursor

On webOS TV 2.x or later, the cursorStateChange event is supported. When the cursor of the Magic Remote or HID pointing device appears or disappears, the cursorStateChange event is raised and returns one of the following values in the event.detail.visibility property:

  • true, if the cursor appeared.
  • false, if the cursor disappeared.
Note: Supported webOS TV platform version

On the webOS TV 1.x, the cursorStateChange event is not supported. To check the cursor state, you need to use the keydown event. The following are the keycode values for the cursor.

  • 1536: cursor_show
  • 1537: cursor_hide

The following code snippet shows how to handle the cursorStateChange event.

function cursorVisibilityChange(event) {
  var visibility = event.detail.visibility;
  if (visibility) {
    console.log('Cursor appeared');
    // Do something.
  } else {
    console.log('Cursor disappeared');
    // Do something.
  }
}
document.addEventListener('cursorStateChange', cursorVisibilityChange, false);

You can test cursor visibility with the code below. This code includes additional event handlers:

  • blur and focus event handlers: These events are raised when your app loses or gains the focus. When an overlay-type system UI element, such as Launcher or Settings menu, appears, your app cannot receive pointer events. To prevent such case, you can test whether your app has the focus or not using these events .
<html>
  <head>
    <script>
      function load() {
        document.addEventListener('cursorStateChange', onCursor, false);
        document.addEventListener(
          'visibilitychange',
          function () {
            Log(document.visibilityState);
          },
          false
        );
        window.addEventListener(
          'blur',
          function () {
            Log('Focus off');
          },
          false
        );
        window.addEventListener(
          'focus',
          function () {
            Log('Focus on');
          },
          false
        );
      }

      function onCursor(event) {
        if (event.detail.visibility) Log('Cursor on');
        else Log('Cursor off');
      }

      var line = 0;
      function Log(msg) {
        console.log(msg);
        document.getElementById('log').innerHTML +=
          ++line + ': ' + msg + '<br>';
      }
    </script>
  </head>
  <body onload="load()" style="background-color:black; color:white">
    <div id="log"></div>
  </body>
</html>
No Headings