14

Exception Handling

Exception Handling for the Focus

Exception Handling for the Return/Exit Key

Exception Handling for the Player Exit Event

Exception Handling for the IME

Summary

The SmartTV application development needs to handle more exceptions than other platforms. However, understanding characteristics of the remote controlled TV and SDF provides guides that will help handling the exceptions. This chapter will cover a few important points using the Hands Frame advanced version application.

Exception Handling for the Focus

As emphasized many times already, a SmartTV uses a remote controller to move the focus to control an application. The focus must be controlled during the entire time that an application runs. Losing the focus means that a user lost the only control tool to use the application. This can cause erroneous feedback to remote control inputs, or simply no feedback at all.

When the focus is lost while running an application, due to inadequate exception handling, the only solution is ending and restarting the application. See the below example.

// Empty an element and output data from the IME input on the element.
var form_submit = function(){
      Main.login.elem.empty();
      Main.login.elem.text(‘Welcome ! ‘+Main.login.form.val() + ’.’);
};

The above code was used in the Hands Frame advanced version to implement the login feature. The code uses the IME to get user data for the login form, empty the Main.login.elem element, and enter the received data on there. Although the previous chapter already took care of exception handling for this function, it's shown here to demonstrate a point.

Deleting a subelement of the login element using the jQuery empty() function causes the currently focused anchor to also be deleted. Unless the focus was already moved to another element, the application loses the focus. To solve this problem, set an anchor and move the focus to the anchor.

// Empty an element and output data from the IME input on the element.
// Move the focus after displaying the data.
var form_submit = function(){
      Main.login.elem.empty();
      Main.login.elem.text(‘Welcome ! ‘+Main.login.form.val() + ’.’);
      Main.category.anchor.focus();
};

The focus can also be lost when the opposite blur() function is used.

Main.anchor.blur();

The blur() function is often used when calling the AVPlayer or manually ending an IME session. Just remember to move the focus whenever using the blur() function.

Main.anchor.blur();
Main.Element.anchor.focus();

There are other situations that can lose the focus—loading or ending a module, changing screens, using a pop-up event, etc. The focus will be lost unless proper exception handling is added. The focus is the connection point between a user and an application. Always be careful not to lose it.

Exception Handling for the Return/Exit Key

Unless programmed otherwise, pressing the Return or Exit key ends a running Samsung SmartTV application. However, a common multiple application with multiple screens needs to reprogram the Return key to show the parent screen, instead of ending the application. Since a user habitually presses the Return key to control a SmartTV, a well-designed application will ask the user if she really wants to end the application.

event.preventDefault();  // Prevent the Return key event from automatically
ending the application

The above function prevents the Return key event's default action of ending the application. See below for how it is used.

Main.keyDown = function()
{
     var keyCode = event.keyCode;

     switch(keyCode)
     {
         case tvKey.KEY_RETURN:
              event.preventDefault();
              break;
     }
};

Note that the event.preventDefault() function was added in the Return key's event handling. This exception handling is also used to show a confirmation window when the Exit key is pressed. In this case, add the above function and a confirmation pop-up window to the Exit key's event handling code to design a refined application.

Exception Handling for the Player Exit Event

When a VOD playback is complete, the AV Player object's Stop function must be manually called to prevent a system error caused by multiple player modules being called. A second VOD may not play or the application may crash if this step is neglected. Do not forget this exception handling.

Main.AVPlayer.Stop();

The onstreamcompleted call function should be registered for the AV Player, so that it will be called when a playback is complete. Add the Stop function in it.

// Exception handling for the Return key while the Player anchor is focused.
onstreamcompleted: function() {
     Main.AVPlayer.Stop();
}

This exception handling is combined with the previous Return key exception handling, as shown below. The AV Player module is declared as a scene and receives key events through its anchor. If the Return key is pressed for the anchor, it should call the Stop() function as well.

// Exception handling for the Return key while the Player anchor is focused.
case tvKey.KEY_RETURN:
      event.preventDefault();
      Main.AVPlayer.Stop();
      break;

The AV Player may end for various reasons. The above Stop() function must be used for all possible situations. And an application must check if there is any open player object during its exit.

Exception Handling for the IME

IME is an internal Samsung SmartTV module for collecting user data input. Like the AV Player module, the IME module also uses callback functions for various situations. The IME module requires careful handing for the callback functions; in addition to that, it is called with a <form> element. The following exception handlings are necessary.

• Maximum input length
• IME onClose

An <input> element must have a maximum length for the IME module. The SDF allows a maximum of 256 letters. An application may crash after that. Set the maxlength as shown below.

<input type=“text” id=“login_form” maxlength=“5” onkeydown=“Main.login.
keyDown();”/>

The second exception handling is for the IME module's exit. The IME module is opened with the onShow() function and closed with the onClose() function.

If an application suddenly ends without properly ending an open IME module first, the IME module will be forced to close as well. However, this may fail if the system resource was busy closing the application, causing a system error.

To prevent the above situation, the following code must be included in the onUnload function that handles the application exit event.

// Event handling function for the application exit
Main.onUnload = function ()
{
     if (oIME){
           oIME.onClose();
     }
};