TutorialsInteraction with the remote control
Introduction
This example will build on our Hello world example and will demonstrate the interaction of HbbTV applications with remote control. Remote control keys supported within applications are set within the ETSI TS 102 796 V1.1.1 standard document, chapter 10.2.2 User input:
| Button (for conventional remote controls) | Key event | Status |
| 4 colour buttons (red, green, yellow, blue) | VK_RED, VK_GREEN, VK_YELLOW, VK_BLUE | Mandatory |
| 4 arrow buttons (up, down, left, right) | VK_UP, VK_DOWN, VK_LEFT, VK_RIGHT | Mandatory |
| ENTER or OK button | VK_ENTER | Mandatory |
| BACK button | VK_BACK | Mandatory |
| Number keys | VK_0 to VK_9 inclusive | Mandatory |
| Play, stop, pause | VK_STOP and either VK_PLAY and VK_PAUSE or VK_PLAY_PAUSE | Mandatory |
| Fast forward and fast rewind | VK_FAST_FWD VK_REWIND | Mandatory |
| TEXT or TXT or comparable button | Not available to applications | Mandatory |
| 2 program selection buttons (e.g. P+ and P-) | Not available to applications | Optional |
| WEBTV or comparable button | Not available to applications | Optional |
| EXIT or comparable button | Not available to applications | Optional |
Beware that the applications themselves define which key events they request to receive. This is done by setting the KeySet object to a bitwise mask constructed from the constants in the following table:
| Constant name | Numeric Value | Use |
| RED | 0x1 | Used to identify the VK_RED key event. |
| GREEN | 0x2 | Used to identify the VK_GREEN key event. |
| YELLOW | 0x4 | Used to identify the VK_YELLOW key event. |
| BLUE | 0x8 | Used to identify the VK_BLUE key event. |
| NAVIGATION | 0x10 | Used to identify the VK_UP, VK_DOWN, VK_LEFT, VK_RIGHT, VK_ENTER and VK_BACK key events. |
| VCR | 0x20 | Used to identify the VK_PLAY, VK_PAUSE, VK_STOP, VK_NEXT, VK_PREV, VK_FAST_FWD, VK_REWIND, VK_PLAY_PAUSE key events. |
| SCROLL | 0x40 | Used to identify the VK_PAGE_UP and VK_PAGE_DOWN key events. |
| INFO | 0x80 | Used to identify the VK_INFO key event. |
| NUMERIC | 0x100 | Used to identify the number events, 0 to 9. |
| ALPHA | 0x200 | Used to identify all alphabetic events. |
| OTHER | 0x400 | Used to indicate key events not included in one of the other constants in this class. |
Implemented functionality
The example application, once started, shall demonstrate a typical red button scenario, when the application at first only reacts to the red button which, when pressed, invokes the full application that requests to receive more key events. To keep this example minimal, we will not use an image for the call-to-action banner:
In this state, the app receives only the red button event and reacts to it by showing the full application scene:
When full application scene is active, the app will react to all coloured RC buttons as follows:
- RED BUTTON to hide the scene and go back to call-to-action scene
- GREEN BUTTON to enable / disable reception of playback RC buttons (PLAY / PAUSE / STOP / FFWD / RWD) by the app
- YELLOW BUTTON to enable / disable reception of numeric RC buttons (0 … 9) by the app
- BLUE BUTTON to prevent reception of all RC buttons by the app for 10 seconds
When the full application scene is active, the app will also show the last RC button pressed on screen.
Source code
Full source code is available here: https://github.com/HbbTV-Association/Tutorials/tree/main/rc-interaction
The code consists of:
- rc-interaction.html HTML document holding the application scene
- rc-interaction.css CSS document holding the application scene styling
- rc-buttons.js JavaScript file which defines global variables for RC button events and 2 utility functions
- rc-interaction.js JavaScript file holding the application logic
rc-interaction.html
Application HTML document rc-interaction.html starts off as a “usual” HbbTV app (see Hello world example):
<!DOCTYPE html PUBLIC "-//HbbTV//1.1.1//EN" "http://www.hbbtv.org/dtd/HbbTV-1.1.1.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>RC interaction demo app</title>
<meta http-equiv="Content-Type" content="application/vnd.hbbtv.xml+xhtml; utf-8" />
<link rel="stylesheet" href="rc-interaction.css" />
<script type="text/javascript" src="rc-buttons.js"></script>
<script type="text/javascript" src="rc-interaction.js"></script>
</head>
<body onload="start();">
<div>
<object type="application/oipfApplicationManager" id="applicationManager"> </object>
</div>
Observe that 2 JS documents are loaded:
- rc-buttons.js which defines global variables for RC button events and 2 utility functions
- rc-interaction.js which contains the application logic
The onload attribute of the body tag calls the app entry function start(). Document body also includes the application/oipfApplicationManager embedded object which is used within application logic in order to acquire the Application object, as set by standard.
The rest of the rc-interaction.html document contains main application scene within the safe area as recommended by the standard and a separate div outside of safe area containing the red button call to action notification:
In order to keep this example as simple as possible the call-to-action banner (Press the red button on the RC to start!) is implemented as text.
rc-interaction.css
The rc-interaction.css starts with HbbTV specifics explained in the Hello world example.
The difference in this example is that initial visibility state of safe area (containing main application scene) is set to hidden since on application start only red button call-to-action notification is visible:
Red button call-to-action notification div and text style (contains nothing specific for HbbTV):
Main scene and bottom legend style concludes the CSS (contains nothing specific for HbbTV):
rc-buttons.js
The rc-buttons.js defines global variables for RC button events:
Key events for different RC buttons are defined in KeyEvent class, but we choose to define global variables, since we want to add support for key events on emulators running on computer browsers which receive input from a computer keyboard, which we do like so:
This approach ensures that we always have a global variable defined for every key event. The rest of rc-buttons.js defines 2 utility functions:
- setKeyset(app, mask), which is used to set a KeySet mask (this is how applications define which key events they request to receive). This example application is built for maximum compatibility, so in order to support terminals implementing version 1.1.1 of the ETSI TS 102 796 standard the setKeyset(app, mask) function has to compensate for a change in OIPF DAE Application class private property name change to privateData (OIPF DAE specification version 1.1 to version 1.2);
- registerKeyEventListener(), which is used to invoke the callback function for processing RC button events (in our case it is the handleKeyCode(kc) function);
rc-interaction.js
The rc-interaction.js starts of with scene initialization implementation:
Followed by utility function used to show / hide main scene and retrieve the KeySet mask relevant for current state of main scene (numeric / playback RC buttons enabled or disabled):
Main application scene is rendered using the render() function:
When a user presses the BLUE RC button, all user input is disabled for 10 seconds. This is a demonstration of controlling the RC button events application will receive when setting the keyset value to different button masks. The waiting is implemented in timerTick() function like so:
RC button events handling is implemented in handleKeyCode(kc) function:
Observe that the key handler function code ends with returning true to suppress the default behaviour of the terminal for the pressed RC button.
The rc-interaction.js ends with app entry function:
This function tries to acquire the Application object and, when successful, initializes and shows it’s user interface (initial state set by CSS is app_area hidden, red button call-to-action banner visible).