Navigation

​

Remote Control

Typically, the remote control facilitates standard 5-way navigation with additional physical keys serving as shortcuts for common operations. The following buttons are available for application use:

​

Keys & App Usage

​

Keycodes

​

Back Behavior

The Back/Return button is a mandatory button on the remote control to go back or close the app. The app may handle the Back/Return key event. If it handles the Back/Return key, the app must handle both 8 / VK_BACK and VK_BACK_SPACE to ensure compatibility between current and legacy devices. On the remote control, the key may be marked with “Back”, “Return” or similar. The Back/Return key should provide the user with typical back navigation, and finally, an exit path via window.close(); to leave the app and return to the previous screen.

NOTE: Ensure the app does not use incorrect keycodes like 27 (ESC key) for the back key.

document.addEventListener(
  "keydown",
  function (e) {
    /* Handling keydown event */
    switch (e.keyCode) {
      case VK_BACK:
        if (e.keyCode === VK_BACK || e.keyCode === VK_BACK_SPACE) {
          // Add prevent Default if focus is not on input field
          if (!isInputFieldFocused()) {
            e.preventDefault();
            // Now add your code below to handle BACK key
          }
        }
        break;
    }
  },
  true
);
// To detect the focus is in input field or not use below code
function isInputFieldFocused() {
  var activeElement = document.activeElement;
  if (
    activeElement &&
    (activeElement.tagName.toLowerCase() === "input" ||
      activeElement.tagName.toLowerCase() === "textarea")
  ) {
    console.log("focus is in input field");
    return true;
  } else {
    console.log("focus is not in input field");
    return false;
  }
}

​

How to use BACK key

In case of multi-page application: The app should use the historical behavior like window.history.go(-1)

Back Behavior: window.history.go(-1)

Clean Exit:

if (typeof SmartTvA_API !== "undefined") {
  SmartTvA_API.exit();
} else {
  window.close();
}

In case of single-page application: The app should use hierarchical behavior.

To Exit the app, use window.close() method.

​

Important Recommendation

• Pressing the back key should navigate the user to the previous screen or menu within the app. When the back key is pressed at the top level of the application or when an on-screen exit button (optional) is pressed, the app should prompt the user with an exit confirmation message before exiting the app.
• During video playback, pressing the back key should bring up the player controls or navigate to the previous menu or content selection screen.
• NOTE: Ensure that the back key does not exit the app or stop the playback unless explicitly intended
• When pressing the remote control back key repeatedly, it should eventually exit the app.

​

Consistent Keycode Event Handling

Every single key press operation consists of corresponding keydown and keyup events. To prevent processing a key twice, act on either the keydown event or the keyup event, not both. Handling both events can lead to overlapping actions. It is most common to act on keydown.

​

Common Issues and Troubleshooting

​

Issue 1: Key Press Events Overlapping

• Description: Actions are triggered twice due to handling both keydown and keyup events.

• Solution: Ensure the app handles only one of the events, preferably the keydown event.

​

Issue 2: Incorrect Keycode for Back Key

• Description: The app listens for the wrong keycode (e.g., 27 instead of 8).

• Solution: Update the app to use the correct keycode (8) or the constant window.VK_BACK for better readability.

​

Issue 3: Back Key Not Handled Properly

• Description: The back key does not perform the expected action, such as navigating to the previous screen.

• Solution: Verify the keycode handling in the app and ensure it aligns with TitanOS standards. Check if VK_BACK is implemented correctly in the app’s code.

​

Issue 4: Back Key Causes App Exit

• Description: Pressing the back key exits the app instead of navigating within it.

• Solution: Ensure the back key functionality is limited to navigation within the app and only exits the app from the main menu or home screen.

​

Issue 5: Intermediate Screen Display During Navigation

• Description: When pressing the back key during video playback, an intermediate screen is briefly displayed before returning to the content page.

• Solution: Review and adjust the key event handling and navigation logic to ensure that pressing the back key during playback directly returns to the content page without intermediate screens. Ensure proper state management to avoid temporary state changes that cause intermediate screens to display.

​

Best Practices

Test Thoroughly: Regularly test the back key functionality in various scenarios to ensure consistent behavior.

Follow Standards: Adhere to TitanOS documentation and guidelines for keycode handling and app behavior.

User Experience: Consider user experience when implementing the back key functionality, ensuring intuitive and expected navigation within the app.

​

OSKB

Titan OS features a system keyboard that is automatically displayed on the screen when the focus is placed in an input field. Referred to as the on-screen keyboard (OSKB), it serves as the primary text input method for Titan OS. Utilising the system keyboard is optional - it is possible to use your own on-screen keyboard solution if preferred or required.

​

System keyboard UI

Titan OS’ OSKB incorporates variations in its user interface across different devices to ensure usability. However, it generally adheres to the following characteristics:

• Emerges from the bottom of the screen
• Occupies 100% of the screen width
• Occupies 1/3 of the screen height
• Initially set to English language; future updates will align with the device’s country settings

The OSKB supports multiple layouts, including:

• Standard QWERTY
• Alpha-numeric
• Standard numeric with numbers 0-9
• Standard numeric with alternate characters such as %, +

​

Custom keyboard

If the system keyboard does not meet your application’s requirements or if you seek UI consistency within your app, you can define a custom keyboard. Considerations for implementing a custom keyboard include:

• Keyboard usability
• UI coherence with the application
• Smooth focus movement

Enabling a custom keyboard will require adjustments to the input box, such as adding disabled properties, etc.

​

Common Issues and Troubleshooting

When a user presses the Enter key in an <input> tag, it triggers the platform OSKB (On-Screen Keyboard). This may cause two keyboards to appear on the screen. This behavior can be adjusted by following one of the approaches below.

1. Avoid using <input> tags.

   Instead of using the <input> tag, implement the input field using a different element, such as a <div>. This allows you to use the app’s OSKB without interference from the platform OSKB.

2. Use <input> tags with Platform OSKB

   If you prefer to use the <input> tag, ensure that only the platform OSKB is called and not the app’s OSKB. This ensures a consistent user experience without triggering multiple keyboards.