05

Focus

Anchor and Focus

Registering/Unregistering a Remote Control Key

Handling Remote Control Events

Moving the Focus

Handling a Mouse Event

Summary

Anchor and Focus

Anchor elements are often used to navigate between HTML pages in a web service. However, it is used for a somewhat different purpose in a general SmartTV application. An anchor is capable of focusing an element in addition to navigating among pages using the href property. This property is often used in SmartTV applications to control scenes.

In a SmartTV application, HTML/JavaScript focus is used to select and mark one of several items simultaneously displayed on the screen. Try to re-call using remote control directional keys (up/down/left/right) to focus different items on a SmartTV or a set-top box type IPTV service, in which the OK key activates the focused content.

Anchors and focuses are the fundamental tools of controlling a Samsung SmartTV application using a remote controller. Gesture Recognition has been added recently to allow more freedom in moving focus and selecting content with hand movement.

Registering/Unregistering a Remote Control Key

Registering a remote control key means that the application will have its own functions to handle the key input. Unregistering a key means using a SmartTV's default OSD (On Screen Display) functions to handle it. When an application is executed, basic remote control keys (directional keys and the OK key) are automatically registered for the application to use. To return control of a registered key to the basic OSD, the key can be unregistered. See the following remote control volume key example to help understand this concept.

If an application is a FullWidget app, volume keys are automatically registered when the application is executed. To allow users to use volume keys' original TV OSD function of controlling volume, those keys need to be unregistered by the application. To use the volume up key for another function (such as controlling an application's internal gage), the KEY_VOL_UP key event needs to be registered in the application and controlled by a custom event handling for the KEY_VOL_UP event.

Commonly used keys are automatically registered when an app is executed to relieve developers. Just remember to unregister a key event if you want to return control of the key to the original OSD functions of a TV.

The SDF provides various APIs for registering and unregistering the keys.

Here is a sample source code that registers the KEY_TOOLS key.

// Create a plug-in instance of the Common Module API.
var pluginAPI = new Common.API.Plugin();

Main.onLoad = function() {
    window.onShow = onShowEvent;
    widgetAPI.sendReadyEvent();
};

onShowEvent = function() {

    // Register TOOLS key.
    pluginAPI.registKey(tvKey.KEY_TOOLS);
};

The SDF also provides an API that registers multiple keys simultaneously. See the following example that registers multiple keys that are used by a FullWidget type application.

// Create a plug-in instance of the Common Module API.
var pluginAPI = new Common.API.Plugin();

Main.onLoad = function() {

    window.onShow = onShowEvent;
    widgetAPI.sendReadyEvent();
};

onShowEvent = function() {

    // Register all keys that are used by a FullWidget type application.
    pluginAPI.registFullWidgetKey();
};

Now let's see how unregistering is implemented. The next example unregisters volume up/down keys and mute keys so that the original TV OSD function can be used.

// Create a plug-in instance of the Common Module API.
var pluginAPI = new Common.API.Plugin();

Main.onLoad = function() {
    window.onShow = onShowEvent;
    widgetAPI.sendReadyEvent();
};

onShowEvent = function() {
    var nnaviPlugin = document.getElementById(‘pluginObjectNNavi’);
    naviPlugin.SetBannerState(1);

    // Unregister keys for volume OSD.
    pluginAPI.unregistKey(tvKey.KEY_VOL_UP);
    pluginAPI.unregistKey(tvKey.KEY_VOL_DOWN);
    pluginAPI.unregistKey(tvKey.KEY_MUTE);
};

It is more logical to register and unregister remote control keys during application initialization by placing them within the body.onload function. But the example source code shows that they are placed within the window.onShow function that is called after the body.onload function. This is to avoid any conflict that may occur when key registering and unregistering for the Smart Hub and for the application execution. Using the window.onShow function guarantees that the Smart Hub's processes are already completed.

Note that only a few keys are automatically registered except on a full-screen application. All the necessary keys need to be manually registered.

Handling Remote Control Events

Remote control key codes are mapped into JavaScript codes that switch focus between elements, by assigning an appropriate process to each of the registered key events. See the following table for a list of registered key values, for both a full-screen application and a single-wide application (ticker).

If an application has a handler and an assigned function for a KEY_UP event, it will process efficiently when a user presses the Up key of the remote controller. But nothing will happen if the application is not programmed to handle the KEY_UP event.

Let's see an example source code for the preceding case. The following example will handle the most commonly used four directional keys, back key, and OK key events. First, add an anchor element to handle the key events.

<!–Anchor element to handle four directional keys, back key, and ok key. -->
 <a href=“javascript:void(0);” id=“anchor” onkeydown=“Main.keyDown();”></a>

The anchor element must have an href property, but any value assigned for this property will cause the browser to open a new page with the value as its address. That is an unnecessary function for the scene-based development method of this book, and can be blocked by calling the void(0) function that always returns null value.

The currently focused anchor will use the onkeydown handler to process the event generated when a SmartTV user presses a remote control key. The handler calls the function if there is a registered function for the event.

The following example uses an event-handling function to process the four directional keys, the Back key, and the OK key, which are received by the previously defined anchor.

// Create a TVKeyValue instance of the Common Module API.
var tvKey = new Common.API.TVKeyValue();

// Event handling function registered on the anchor's handler.
Main.keyDown = function () {
    var keyCode = event.keyCode;

    switch (keyCode) {
        case tvKey.KEY_LEFT:
            break;
        case tvKey.KEY_RIGHT:
            break;
        case tvKey.KEY_UP:
            break;
        case tvKey.KEY_DOWN:
            break;
        case tvKey.KEY_ENTER:
            break;
        case tvKey.KEY_RETURN:
            break;
    }
};

See the variable tvKey on the source code. This is an instance of the Common Module API library TVKeyValue.js. All remote control key code values are saved in this object as member properties.

Also, note the object type global variable event.keyCode, which stores the last pressed remote control key value. This value is passed to the local variable keyCode, then is used by a switch statement to process four directional keys, ok key, and return key inputs. The switch statement ignores any other keys.

While there are many key codes, memorizing them is not necessary because only a few common keys will be used by most applications. Visit the SDF for detailed information about the remote control events.

Moving the Focus

As shown, placing the browser focus on an anchor element, to handle remote control key events and navigate between scenes, is the fundamental design concept of this book. The example uses only one anchor element for an easier demonstration. But commercial applications use many interacting anchor elements that pass the focus back and forth. Understanding this concept is essential for a SmartTV application developer.

Before covering the focus moving in detail, let's clearly define a UI component and an anchor element. A UI component is commonly shown on the screen as a menu button or a content image thumbnail, and is a displayed element. An anchor element is an HTML <a> tag that handles remote-control events and actually receives focus. To implement a natural focus system with distinct styles, these anchor elements and UI components must be defined.

See the next example that shows focus movement between two elements, “left ” and “right.”

<!–Left element -- >
<div id=“left”>
    <a href=“javascript:void(0);” id=“left_anchor” onkeydown=“left.
keyDown();”>left</a>
</div>

<!–Right element -- >
<div id=“right”>
    <a href=“javascript:void(0);” id=“right_anchor” onkeydown=“right.
keyDown();”>right</a>
</div>

var tvKey = new Common.API.TVKeyValue();

var left = {};
var right = {};

// Left anchor event handling function
left.keyDown = function()
{
    var keyCode = event.keyCode;

    switch(keyCode)
    {

        case tvKey.KEY_RIGHT:
            jQuery(‘#right_anchor’).focus();     // Right anchor focus
            jQuery(‘#right’).addClass(‘focus’);
            jQuery(‘#left’).removeClass(‘focus’);
            break;
        default:
            break;
    }
};

// Right anchor event handling function
right.keyDown = function()
{

    var keyCode = event.keyCode;

    switch(keyCode)
    {

        case tvKey.KEY_LEFT:
            jQuery(‘#left_anchor’).focus();    // Left anchor focus
            jQuery(‘#left’).addClass(‘focus’);
            jQuery(‘#right’).removeClass(‘focus’);
            break;
        default:
            break;
    }
};

#left{
    display:inline-block;
    float: left;
    width: 200px;
    height: 200px;
}

#left.focus{
    background-color: blue;
}

#right{
    display:inline-block;
    float: right;
    width: 200px;
    height: 200px;
}

#right.focus{
    background-color: blue;
}

Styles need to be modified to visually indicate which element is currently focused. See the above Main.css source code that has added a “.focus” class that was used to modify the background style. Note that each element's class is controlled by the jQuery. The source code does not specify the initial focus. But if the left anchor is focused, the remote controller's right directional key event will move the focus to the right anchor. With the focus movement, the UI component paired with the newly focused anchor will be modified by adding the .focus class using the jQuery's addClass function. The previous anchor's UI component will also be modified by removing the .focus class. This practice visually indicates the focus movement with the style element.

Handling a Mouse Event

Let's briefly review the new mouse event supported since Samsung SmartTV 2012 models. An application can be configured to support mouse input using a mouse element in the config.xml file, as shown below.

<mouse itemtype=“string”>y</mouse>

The Smart Interaction's gesture recognition feature works like the mouse event. Details will be covered in chapter 13, Advanced Features – SI Gesture Recognition.

When both a Remote Controller and a Mouse are used together

This book focuses on event handling with remote controller-based anchors, and mouse events are used together only in special cases. This is to avoid a browser's basic tendency of moving the focus to a mouse-clicked element that causes unintentionally losing anchor focus for a random mouse click. When a mouse clicks an element that either does not need to or should not have the focus, the focus is unintentionally moved to the element, which causes the remote controller to lose navigation capability.

To solve the problem, the anchor-based event-handling method needs to be modified. One way would be processing the onkeydown handler in the <body> tag instead of in an anchor.

<body onload=“Main.onLoad();” onunload=“Main.onUnload();” onkeydown=“Main.
keyDown();”>

This allows the top-most body element to handle the events and solves the focus-losing problem. Many different solutions are suitable for different situations.