Professional Documents
Culture Documents
App Development Guide For Samsung Smart TV (V1.20)
App Development Guide For Samsung Smart TV (V1.20)
Version 1.20
Samsung Smart TV
PREFACE ............................................................................................................................................................................ 7 1. INTRODUCTION .................................................................................................................................................... 8 1.1. 2. WHAT IS SAMSUNG SMART TV? .......................................................................................................................... 8
SAMSUNG SMART TV ........................................................................................................................................... 9 2.1. 2.2. OPERATING PRINCIPLE ......................................................................................................................................... 9 OPERATING ENVIRONMENT .................................................................................................................................. 9
3.
APPLICATIONS .................................................................................................................................................... 10 3.1. 3.2. 3.3. 3.4. 3.5. 3.6. WHAT ARE APPLICATIONS? ................................................................................................................................. 10 STRUCTURE OF AN APPLICATION ........................................................................................................................ 10 DISPLAY TYPE OF APPLICATIONS ........................................................................................................................ 11 RUNNING AN APPLICATION ................................................................................................................................. 12 APPLICATION MANAGER .................................................................................................................................... 12 FEATURES OF SAMSUNG APPLICATIONS ............................................................................................................. 13
4.
CREATING AN APPLICATION .......................................................................................................................... 14 4.1. 4.2. WHAT YOU NEED TO CREATE AN APPLICATION.................................................................................................... 14 HOW TO MAKE AN APPLICATION ........................................................................................................................ 14 Writing config.xml ..................................................................................................................................... 15 Writing index.html ..................................................................................................................................... 16 Writing JavaScript .................................................................................................................................... 16 Writing a CSS ............................................................................................................................................ 17 Use of the remote control .......................................................................................................................... 18 Complete your work & Sample code......................................................................................................... 20
config.xml ...............................................................................................................................................................20 index.html ...............................................................................................................................................................21 Main.js ....................................................................................................................................................................21 Main.css ..................................................................................................................................................................22
4.3.
CONFIG.XML ....................................................................................................................................................... 23
SINGLE-SIGN-ON ............................................................................................................................................... 27 What is Single-Sign-On ............................................................................................................................. 27 Registration of Account Information on Service Sites............................................................................... 28
4.4.1. 4.4.2.
RESET ................................................................................................................................................................ 32 What is Reset? ........................................................................................................................................... 32 How Reset Works? .................................................................................................................................... 32 Necessary Features Developers Should Realize ....................................................................................... 32 Guide for Config.xml Realization ............................................................................................................. 32 Guide for Module Realization ................................................................................................................... 32
COMMON MODULES .......................................................................................................................................... 37 5.1. 5.2. 5.3. 5.4. APPLICATION MANAGERS COMMON MODULES ................................................................................................. 37 HOW TO USE COMMON MODULES ....................................................................................................................... 37 TVKEYVALUE ................................................................................................................................................... 37 WIDGET ............................................................................................................................................................. 40 sendReadyEvent() ..................................................................................................................................... 40 sendExitEvent() ......................................................................................................................................... 41 sendReturnEvent() .................................................................................................................................... 41 blockNavigation() ..................................................................................................................................... 41 putInnerHTML() ....................................................................................................................................... 42 getChannelWidgetListPath() ..................................................................................................................... 43 getSearchWidgetListPath() ....................................................................................................................... 43 runSearchWidget() .................................................................................................................................... 44 checkSapTicket () ...................................................................................................................................... 44 requestSapTicket () .................................................................................................................................... 45
5.4.1. 5.4.2. 5.4.3. 5.4.4. 5.4.5. 5.4.6. 5.4.7. 5.4.8. 5.4.9. 5.4.10. 5.5.
PLUGIN .............................................................................................................................................................. 45 setOnWatchDog() ...................................................................................................................................... 47 setOffWatchDog()...................................................................................................................................... 47 setOnOSDState() ....................................................................................................................................... 48 setOffOSDState() ....................................................................................................................................... 48 registKey()................................................................................................................................................. 49 unregistKey()............................................................................................................................................. 49 registIMEKey() ......................................................................................................................................... 49 unregistIMEKey()...................................................................................................................................... 50 registAllKey............................................................................................................................................... 50 unregistAllKey() ........................................................................................................................................ 51 registFullWidgetKey() ............................................................................................................................... 51 registPartWidgetKey() .............................................................................................................................. 52
5.5.1. 5.5.2. 5.5.3. 5.5.4. 5.5.5. 5.5.6. 5.5.7. 5.5.8. 5.5.9. 5.5.10. 5.5.11. 5.5.12.
CIMAGEVIEWER ................................................................................................................................................ 57 CImageViewer? ......................................................................................................................................... 57 Specifications ............................................................................................................................................ 57 Basic Instructions ..................................................................................................................................... 57 Transition Effect ........................................................................................................................................ 58
Action Principles of Slideshow ...............................................................................................................................59 How to Realize Transition Effect ............................................................................................................................60 Slideshow Mode and Restrictions ...........................................................................................................................61
5.6.5. 5.6.6.
5.6.6.1. 5.6.6.2.
5.6.7.
5.6.7.1. 5.6.7.2. 5.6.7.3. 5.6.7.4. 5.6.7.5. 5.6.7.6. 5.6.7.7. 5.6.7.8. 5.6.7.9.
Reference................................................................................................................................................... 64
CImageViewer ........................................................................................................................................................64 Effect ......................................................................................................................................................................65 clearScreen() ...........................................................................................................................................................66 destroy() ..................................................................................................................................................................66 endSlideshow() .......................................................................................................................................................67 getStopFlag() ..........................................................................................................................................................67 hide().......................................................................................................................................................................68 isEffectAvailable() ..................................................................................................................................................68 play().......................................................................................................................................................................68 prepareNext() .....................................................................................................................................................69 setFrameArea() ...................................................................................................................................................70 setOnBufferingComplete() .................................................................................................................................71 setOnBufferingStart() .........................................................................................................................................71 setOnNetworkError() ..........................................................................................................................................72
6.
TIPS FOR APPLICATION DEVELOPERS ........................................................................................................ 76 6.1. 6.2. 6.3. 6.4. 6.5. 6.6. 6.7. 6.8. 6.9. 6.10. 6.11. 6.12. 6.13. 6.14. 6.14.1. 6.14.2. 6.15. 6.16. 6.17. 6.18. 6.19. 6.20. 6.20.1. 6.20.2. 6.20.3. 6.21. FUNCTION NECESSARY TO BE CALLED WHEN YOU OPEN AN APPLICATION .......................................................... 76 ACCESS POINT ................................................................................................................................................... 76 HANDLING REMOTE CONTROL KEY EVENTS ....................................................................................................... 76 REMOTE CONTROL KEYS FOR APPLICATIONS ...................................................................................................... 77 CLOSING AN APPLICATION .................................................................................................................................. 79 PREVENTION OF CLOSING THE TV SCREEN BY THE RETURN OR EXIT KEY.......................................................... 79 ADDITIONAL INFORMATION ............................................................................................................................... 79 WHAT CSS NEED TO CONTAIN ........................................................................................................................... 80 LOADING IMAGES IN ADVANCE .......................................................................................................................... 80 CHARACTER OF THE <INPUT> TAG ................................................................................................................. 81 SCROLL BAR ...................................................................................................................................................... 81 MAKING DYNAMIC WEB PAGES ...................................................................................................................... 81 SETTING FOR LETTER-SPACING ...................................................................................................................... 82 MEMORY MANAGEMENT ................................................................................................................................ 82 Using XMLHttpRequest ............................................................................................................................ 82 Freeing up the memory ............................................................................................................................. 82 WATCH DOG .................................................................................................................................................. 82 PREVENTION FOR OSD DISTORTION............................................................................................................... 83 SUPPORT CSS TEXT-OVERFLOW ..................................................................................................................... 83 DIRECTIONS FOR CREATING VIDEO APPLICATION............................................................................................ 83 USING IME .................................................................................................................................................... 83 MINIMIZING INITIAL ENTRY SPEED OF AN APPLICATION .................................................................................. 83 Load Javascript On-Demand .................................................................................................................... 83 Load CSS Background Image On-Demand ............................................................................................... 84 Separation of Main.onLoad functions ....................................................................................................... 84 DIRECTIONS FOR DYNAMIC LOADING OF CSS ............................................................................................... 85
7.
FILE API ................................................................................................................................................................. 88 8.1. 8.2. FILE API? .......................................................................................................................................................... 88 API .................................................................................................................................................................... 88 FileSystem() .............................................................................................................................................. 88 openCommonFile() ................................................................................................................................... 89 closeCommonFile() ................................................................................................................................... 90 deleteCommonFile() ................................................................................................................................. 90 createCommonDir() .................................................................................................................................. 91 deleteCommonDir() .................................................................................................................................. 91 isValidCommonPath() ............................................................................................................................... 92 readLine() ................................................................................................................................................. 92 writeLine() ................................................................................................................................................ 93 readlAll() ................................................................................................................................................... 93 writeAll() ................................................................................................................................................... 94 readDir() ................................................................................................................................................... 94 openFile() ................................................................................................................................................. 95
8.2.1. 8.2.2. 8.2.3. 8.2.4. 8.2.5. 8.2.6. 8.2.7. 8.2.8. 8.2.9. 8.2.10. 8.2.11. 8.2.12. 8.2.13. 9.
APPENDIX.............................................................................................................................................................. 96 9.1. 9.2. 9.3. 9.4. 9.5. COUNTRY CODE ................................................................................................................................................. 96 LANGAUAGE CODE ............................................................................................................................................ 97 REGION CODE .................................................................................................................................................... 99 PRODUCT CATEGORY ....................................................................................................................................... 100 CAUTION INFORMATION ................................................................................................................................... 100 Character sensitive target device ............................................................................................................ 100
9.5.1.
Preface
Purpose of Document
This document is written to help application developers who enjoy the Samsung Smart TV service by providing an overview of the service and basic knowledge required to be obtained by application developers. Using this document, developers can develop and manage applications for digital TVs. Target Readers
This document is aimed at programmers who have used web development languages such as HTML, CSS and JavaScript. This document will be even more helpful for those who have web development experience.
1. Introduction
This section describes what Samsung Smart TV is, how it is configured and how it works.
Samsung Smart TV
HubSite
2. Samsung Smart TV
This section describes the operating principle and environment of Samsung Smart TV.
We will look at App Engine, the browser dedicated to internet TVs manufactured by Samsung, in Chapter 7. App Engine.
3. Applications
This section looks at applications that we will develop for Samsung TVs.
10
Full-screen application
Single-wide application
Keeps an application on the Ticker screen while you do other things with your TV.
11
Step
Get the Application Manager started
Instruction description
Press the INTERNET(INFO.L) button on the remote control or go through Menu> Application>Samsung Smart TV to open the application
Select an application
Press arrow button located in the center of the remote control to select an application.
Press the Enter button to implement an application. The Application Manager Implement an application reads the information from the config.xml file of the currently running application to set an operating environment, and reads index.html to implement the application.
Smart Hub
12
Samsung Apps
Settings
Edit Mode
Sort by
13
4. Creating an application
This section guides you to create a simple application.
Lets make an application that displays text written in CSS and responds to remote control buttons events. The structure and look of an application we will make now are shown as below.
14
<?xml version="1.0" encoding="UTF-8"?> <widget> <ThumbIcon>Resource/image/icon/picasa_106.png</ThumbIcon> <BigThumbIcon>Resource/image/icon/picasa_115.png</BigThumbIcon> <ListIcon>Resource/image/icon/picasa_85.png</ListIcon> <BigListIcon>Resource/image/icon/picasa_95.png</BigListIcon> <category>lifestyle</category> <autoUpdate>y</autoUpdate> <cpname>MyCP</cpname> <cpauthjs></cpauthjs> <login>y</login> <ver>0.930</ver> <mgrver>1.000</mgrver> <fullwidget>n</fullwidget> <srcctl>n</srcctl> <ticker>n</ticker> <childlock>n</childlock> <audiomute>n</audiomute> <videomute>n</videomute> <dcont>y</dcont> <network>y</network> <hubsite>n</hubsite> <widgetname>HelloWorld</widgetname> <description>Welcome!</description> <width>960</width> <height>540</height> <author> <name>Samsung Electronics Co. Ltd.</name> <email></email> <link>http://www.sec.co.kr/</link> <organization>Samsung Electronics Co. Ltd.</organization> </author> </widget>
15
If you have done all the work, you will get a debug message of Main.onLoad(). But the Welcome to Samsung application world! that you entered will not appear on the TV screen. If the application is successfully loaded, it has to ask the Application Manager to display itself on the screen using the common module provided by the Application Manager. The common module is a library containing essential functions provided by the Application Manager. For more information, refer to Ch. 5 Common Modules. Add the following code to <head> of index.html.
16
If the above code is added, a common module is available to use by JavaScript. Declare the common module as a global variable for Main.js you were working on and call the sendReadyEvent() function. By doing this, you can make the Application Manager display an application on the screen. var Main = { } var widgetAPI = new Common.API.Widget(); Main.onLoad = function () { alert("Main.onLoad()"); widgetAPI.sendReadyEvent(); /** * JavaScript code Here! */ } // Create Common module // called by <body>'s onload event // Send ready message to Application Manager // Main object
Ok, now run the application youve just made. You will see the words Welcome to Samsung application world! that you entered in the index.html file appearing on the screen. Maybe you dont like the look of the application because its font size is too small and font color is just simple black. You may want to make your application more stylish. Then, you can give the application a style using CSS.
Create a file in the CSS folder and enter text as you see in the below box to specify the style of the welcome element. body { margin: 0; padding: 0;
17
18
Modify Main.js in order to change the contents of welcome Div. This creates common module objects, classify keys in keydown() method, and define actions for each key. For detailed information on common modules and key code list, see Chapter 5. Common Modules. var Main = { } var widgetAPI = new Common.API.Widget(); var tvKey = new Common.API.TVKeyValue(); Main.onLoad = function(){ alert("Main.onLoad()"); widgetAPI.sendReadyEvent(); document.getElementById("anchor").focus(); /** * JavaScript code Here! */ } Main.keyDown = function(){ var keyCode = event.keyCode; alert("Main Key code : " + keyCode); // Key handler // Main object // Create Common module // called by <body>'s onload event // Send ready message to Application Manager // Focus to Anchor for handling key inputs // from remote controller
switch (keyCode) { case tvKey.KEY_LEFT: alert("left"); document.getElementById("welcome").innerHTML /** * Code for Left key event! */ break; case tvKey.KEY_RIGHT: alert("right"); document.getElementById("welcome").innerHTML break; case tvKey.KEY_UP: alert("up"); document.getElementById("welcome").innerHTML break; case tvKey.KEY_DOWN: alert("down"); document.getElementById("welcome").innerHTML break; case tvKey.KEY_ENTER:
= "I'm so happy.";
= "Good job.";
19
4.2.6.1.
config.xml
<?xml version="1.0" encoding="UTF-8"?> <widget> <ThumbIcon>Resource/image/icon/picasa_106.png</ThumbIcon> <BigThumbIcon>Resource/image/icon/picasa_115.png</BigThumbIcon> <ListIcon>Resource/image/icon/picasa_85.png</ListIcon> <BigListIcon>Resource/image/icon/picasa_95.png</BigListIcon> <previewjs>PreviewHelloWorld</previewjs> <cpname>Samsung</cpname> <cplogo>Resource/image/settings_logo.png</cplogo> <cpauthjs></cpauthjs> <ver>0.930</ver> <mgrver>1.000</mgrver> <fullwidget>n</fullwidget> <srcctl>n</srcctl> <ticker>n</ticker> <childlock>n</childlock> <audiomute>n</audiomute> <videomute>n</videomute> <dcont>y</dcont> <network>y</network> <hubsite>n</hubsite> <widgetname>HelloWorld</widgetname> <description>Welcome!</description> <width>960</width> <height>540</height>
20
4.2.6.2.
<!DOCTYPE html> <html> <head>
index.html
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <title>Hello World!!</title> <script type="text/javascript" language="javascript" src="$MANAGER_WIDGET/Common/API/Widget.js"></script> <script type="text/javascript" language="javascript" src="$MANAGER_WIDGET/Common/API/TVKeyValue.js"></script> <script type="text/javascript" language="javascript" src="JavaScript/Main.js"></script> <link rel='stylesheet' type='text/css' href = 'CSS/Main.css'/> </head> <body onload="Main.onLoad();"> <div id='welcome'>Welcome to Samsung widget world!</div> <a href='javascript:void(0);' id='anchor' onkeydown='Main.keyDown();'></a> </body> </html>
4.2.6.3.
var Main = { }
Main.js
// Main object // Create Common module // called by <body>'s onload event // Send ready message to Application Manager // Focus to Anchor for handling key inputs // from remote controller
var widgetAPI = new Common.API.Widget(); var tvKey = new Common.API.TVKeyValue(); Main.onLoad = function(){ alert("Main.onLoad()"); widgetAPI.sendReadyEvent(); document.getElementById("anchor").focus(); /** * JavaScript code Here! */ } Main.keyDown = function(){ var keyCode = event.keyCode;
// Key handler
21
= "I'm so happy.";
= "Good job.";
4.2.6.4.
body {
Main.css
margin: 0; padding: 0; background-color: transparent; } #welcome { position: absolute; left: 50px; top: 50px; width: 500px; height: 50px; background-color: #AFAFAF; color: #99FFFF; font-size: 30px; text-align: center; }
22
4.3. config.xml
The config.xml file contains information about the applications execution, update, operating environment setting and other related issues. Depending on that information, the Application Manager controls the version of your application, sets an environment in which your application is run, and creates and manages user accounts. The config.xml file should be located in the directory in which the application is installed, and contain the following elements.
Description
Indicates that the information is relevant to the application. An icon image displayed in the Application Manager. It is used in case of no focus and its size is 106 x 86pixel. An icon image displayed in the Application Manager.
Value
File path
<BigThumbIcon>
It is used in case that the focus is placed on an image and its size is 115 x 95 pixel.
File path
<ListIcon>
An icon image displayed in the Application Manager. The size is 85 x 70 pixel. An icon image displayed in the Application Manager. The size is 95 x 78 pixel. The category to distinguish applications, available items are video, sports, game, lifestyle, information, others. Decides whether to synchronize with hub site. The application which doesnt need synchronization chooses n. Shows information on contents type 11: HTML + java-script + Flash Player Object
File path
<BigListIcon>
File path
<category>
String
<autoUpdate>
y|n
<apptype>
12: Adobe SWF ( Ver. Flash Lite 3.1 ) 13: Adobe SWF ( Ver. Flash 10.1 ) 14 : Lua Script
Number
File path and name at the initial execution of contents Only the following apptype needs contents tag. <contents> <channelType> <channelRoot> 12: Adobe SWF ( Ver. Flash Lite 3.1 ) 13: Adobe SWF ( Ver. Flash 10.1 ) 14 : Lua Script root | child Application File Path
Channel Bound Service Type(optional) Confirms the relations with root-child clarifying root application ID.
23
information, application.
corresponding
<mgrver>
Indicates the Application Managers version that is required to run an application having the config.xml file. Indicates whether the application is a full-screen or a single-wide one.
x.xxx
<fullwidget>
Display type affects the audio policy of the application when its run. Refer to Chapter. 6.4. Using Keys on Remote Control for details. If source conversion is needed, set this tag to y. (ex. YouTube application).
y|n
<srcctl>
If you select y, the TV source automatically switched from current TV channel or external input to the internal media player, and back again when the application is finished.
y|n
<childlock> <audiomute>
Determines whether to use the childLock function. This function enables the user to lock an application. Turns on and off the audio. If you select y, TV broadcasting sound is
y|n y|n
24
<movie>
2. Sparkling at the entry for appliction due to the difference of Frame rate between the TV image and playing video file. If you select y, you can prevent it from the problem above by ending operating the connected HDMI device when executing the application and fixing the Frame rate.
y|n
Enter a name of application. Enter a brief description of the application. Enter the screen area that the application will be occupying. Generally, it is recommended to enter 960 * 540 pixels, digital TV specification. Enter a description of the author. This tage is used when needed to check network while operating an application. If the tage value is y and the network test result is fail,
<network>
entry for the application can be blocked with a message indicating the failure. Without any set value, default is y. This tage is used when needed to check whether the hubsite has been
y|n
<hubsite>
authorized or not while operating an application. If the tage value is y, and the hubsite has not been authorized, entry for the application can be blocked with a message indicating the failure.
y|n
25
<pushControl>
y|n
<pushUerbinding>
y|n
<flashplayer>
y|n
4.3.2. Example
<?xml version="1.0" encoding="UTF-8"?> <widget> <ThumbIcon>Resource/image/icon/picasa_106.png</ThumbIcon> <BigThumbIcon>Resource/image/icon/picasa_115.png</BigThumbIcon> <ListIcon>Resource/image/icon/picasa_85.png</ListIcon> <BigListIcon>Resource/image/icon/picasa_95.png</BigListIcon> <category>lifestyle</category> <autoUpdate>y</autoUpdate> <cpname>Picasa</cpname> <cpauthjs>Auth11101000000</cpauthjs> <login>y</login> <ver>2.000</ver> <mgrver>1.035</mgrver> <fullwidget>y</fullwidget> <srcctl>n</srcctl> <ticker>n</ticker> <childlock>n</childlock> <audiomute>y</audiomute> <videomute>y</videomute> <dcont>y</dcont> <movie>y</movie> <network>y</network> <hubsite>n</hubsite> <widgetname>Picasa Web Albums</widgetname> <description>View photo albums online</description> <width>960</width> <height>540</height> <author> <name>Samsung Electronics Co. Ltd.</name> <email></email> <link>http://www.sec.co.kr/</link> <organization>Samsung Electronics Co. Ltd.</organization> </author> </widget>
26
4.4. Single-Sign-On
This section describes SSO functions supported by the application manager, how to register account information and get the information from the application.
Use account information on service sites In an application, account information coexists with various circumstances information provided by the
27
<cpname>YourCompany</cpname> <login>y</login>
Then, you can find YourCompany item in the list of service sites. If you cant, restart TV. Application manager could need to be reloaded. Now, the account information on service site, YourCompany can be entered. However, if there is no module which confirms validity of the entered account information, the registration cannot be completed. You should generate the module in person. Validity Confirmation is to make sure that the entered account information is consistent with the ID and Password which are available to sign-in on the real service site. If sign-in can be made by API in each service site, the information is turned out to be valid. In Google, there is ClientLogin to judge validity. If sign-in is successfully done and auth token is granted, the account information is regarded valid. Refer to the URL states below regarding Client Login. (http://code.google.com/intl/ko/apis/accounts/docs/AuthForInstalledApps.html) The module to confirm validity of account information is drawn up as shown below. Enter the name of js file whose config.xml has a module. Put the name of js file which has a module to confirm account information validity in <cpauthjs> item. If the file name is Auth11101000000.js, put Auth11101000000. The application manager executes the module including the file. File names should be unique for each application. Check the variables such as curWidget.id and write the name distinctively.
28
Create a file Create a js file corresponding to the entered file name in the process of . A module will be written in this file. This file is embedded in the top level directory where index.html exists. Draw up a module which confirms validity of account information. This module is generated in the file made in , the format should be in observance of regulations. Declare the object whose name is the entered value in . Add a method checkAccount to the object. checkAccount method confirms validity of the account information on the service site, and it should deliver the results to the callback function transferred to the factor. Example // Object Generated var Auth11101000000 = { } // checkAccount Method Added Auth11101000000.checkAccount = function (id, pw, fnCallback) { /** * The id and pw inputted from the application manager are transferred to the factor. * Check validity of id and pw, and then operate callback function. */ // ... // Confirmation on Validity // ... // Deliver the results if (isValidAccount) { fnCallback ('TRUE'); } else { fnCallback ('FALSE'); }
29
The value transferring to the Callback function and the effect are like below.
Return value
'TRUE'
Description
If the transferred ID and Password are valid, return TRUE. Application manager registers ID and Password in the TV account.
'FALSE'
If the account information is invalid, return FALSE. The application Manager let the user reenter the account information.
'ERROR'
Errors occur while confirming validity, return ERROR. The application manager regards it as an error, after a while, it leads the user to try reusing account information.
Others
Values other than three values above are processed identically with ERROR.
<cpname>YourCompany</cpname> <login>y</login>
Sign-in to the TV account The account information registered in the account can be available when sign-in process to the TV account is completed. Execution for an application Execute the application. Account information on CP(YourCompany) needs to be registered in the designated TV account in . Generally, several service sites are registered in a TV account, on the other hand, an application can get one service site relevant to the designated CP in . How to parse ID and Password All the conditions are satisfied, ID and Password are transferred to Browser global variable
30
31
4.5. Reset
Reset describes functions to initialize the application.
deleting/initializing. 2. Check if the application needs a module which initializes through the information in config.xml. 3. If the application has the module that initializes, bring information on the module. 4. Execute the module in accordance with rules and try initializing. * Application Manager does not obtain any return value but operate the module to initialize.
<deleteJS>MyReset</deleteJS>
* Without deleteJS Element, the application does not operate the initialization module.
32
33
34
XHRObjet.destroy
Free up the XHR object you created from the memory. Syntax Parameter Return Value Remarks XHRObject.destroy() None None This function, which is executed to optimize the memory usage, is only provided by
35
In the above example, two common modules provided by the Application Manager are included. For more information, turn to Ch. 5 Common modules.
36
5. Common modules
In this section, we will look at a library shared by all your applications.
Create an object.
alert(tvKey.KEY_LEFT);
37
Example
38
39
5.4. Widget
This is an object that has functions needed for desirable operation of an application. A method that notifies the Application Manager of starting of an application, a method that registers and frees up keys users want to use, and other methods are contained in this object.
Widget
Object having functions needed for desirable operation of an application Library path Syntax Parameter Return Value Remarks Example Members var widgetAPI = new Common.API.Widget(); widgetAPI. sendReadyEvent(); None sendReadyEvent sendExitEvent sendReturnEvent Methods blockNavigation putInnerHTML getChannelWidgetListPath getSearchWidgetListPath runSearchWidget $MANAGER_WIDGET/Common/API/Widget.js new Common.API.Widget() None Widget object (Since Samsung Smart TV version 2.265)
5.4.1. sendReadyEvent()
sendReadyEvent
Notifies the Application Manager that the application is ready to be displayed. This event should be passed to display and run the application on the screen. Syntax Parameter Return Value Remarks sendReadyEvent() None None (Since Samsung Smart TV version 2.265)
40
Example Enumeration
5.4.2. sendExitEvent()
sendExitEvent
Brings the same effect as pressing the exit key. Stops the application and goes back to the TV screen. Syntax Parameter Return Value Remarks Example Enumeration var widgetAPI = new Common.API.Widget(); widgetAPI.sendExitEvent (); None sendExitEvent() None None (Since Samsung Smart TV version 2.265)
5.4.3. sendReturnEvent()
sendReturnEvent
Brings the same effect of pressing the Return key. Finishes the application and takes you to the Application Manager. Syntax Parameter Return Value Remarks Example Enumeration var widgetAPI = new Common.API.Widget(); widgetAPI.sendReturnEvent (); None sendReturnEvent() None None (Since Samsung Smart TV version 2.265)
5.4.4. blockNavigation()
blockNavigation
41
Example
Enumeration
5.4.5. putInnerHTML()
putInnerHTML
innerHTML method to fix memory issues. Syntax Parameter Return Value putInnerHTML(div, contents) div: Div Element to use innerHTML contents: Things to insert in innerHTML None Required to use this method because repetitive use of innerHTML can occur memory Remarks issues. (Since Samsung Smart TV version 2.265) Example var widgetAPI = new Common.API.Widget();
42
5.4.6. getChannelWidgetListPath()
getChannelWidgetListPath
Method that brings the path of xml file having the child application list of the current channel bound application Syntax Parameter Return Value getChannelWidgetListPath() None string : xml file path This method is used when the channel bound application needs information on the Remarks currently installed child application. (Since Samsung Smart TV version 2.265) Example Enumeration var widgetAPI = new Common.API.Widget(); var xmlPath = widgetAPI.getChannelWidgetListPath(); None
5.4.7. getSearchWidgetListPath()
getSearchWidgetListPath
Method that brings the path of xml file having the list of applications related Syntax Parameter Return Value getSearchWidgetListPath() None string : xml file path This method is used when a search tag in config.xml requires information on an Remarks application whose search tag is set as y. (Since Samsung Smart TV version 2.265) Example Enumeration var widgetAPI = new Common.API.Widget(); var xmlPath = widgetAPI.getSearchWidgetListPath(); None
43
runSearchWidget
Method called when executing another application in an application Syntax Parameter Return Value runSearchWidget () appID : The application ID you intend to operate extraInfo : The string that transferred to the executing application None This method is used when the channel bound application requires information on the Remarks installed child application at present. (Since Samsung Smart TV version 2.265) Example Enumeration var widgetAPI = new Common.API.Widget(); widgetAPI.runSearchWidget(111011000001,key1=value1&key2=value2); None
5.4.9. checkSapTicket ()
checkSapTicket
Method called when checking to have the valid ticket for current logged-in user. Syntax Parameter Return Value checkSapTicket () None None You should register event handler for passing the return value. If you have valid ticket, the return value is stat=ok&ticket=686a8281-e952-4dccRemarks a67b-57e8f92e5530 Otherwise, it is stat=fail&ticket=null. (Since Samsung Smart TV version 3.037) // Register Event Handler curWidget.onWidgetEvent = AAAA; var widgetAPI = new Common.API.Widget(); widgetAPI.checkSapTicket(); Example function AAAA(event){ if( event.type == Common.API.EVENT_ENUM.PNS_CHECK_TICKET){ // The return value is event.data. // TODO }
44
5.4.10.
requestSapTicket ()
requestSapTicket
Method called when requesting new Sap Ticket for Application Server. Syntax Parameter Return Value requestSapTicket () None None You should register event handler for passing the return value. If new ticket is generated normally, the return value is stat=ok&ticket=686a8281Remarks e952-4dcc-a67b-57e8f92e5530 Otherwise, it is stat=fail&ticket=null. (Since Samsung Smart TV version 3.037) // Register Event Handler curWidget.onWidgetEvent = AAAA; var widgetAPI = new Common.API.Widget(); widgetAPI.requestSapTicket(); Example function AAAA(event){ if( event.type == Common.API.EVENT_ENUM.PNS_REQUEST_TICKET){ // The return value is event.data. // TODO } } None
Enumeration
5.5. Plugin
The Application Manager provides a wrapper class that allows you to use some plugin functions in more convenient ways. If you want to take advantage of this class, just insert objects needed for use of plugins in the index.html document. Then, the Application Manager will give you an appropriate class method.
Plugin
Object that is wrapped for convenient use of plugins
45
46
5.5.1. setOnWatchDog()
setOnWatchDog
Turns on the Watch dog function. Syntax Parameter Return Value Remarks Example Enumeration var pluginAPI = new Common.API.Plugin(); pluginAPI.setOnWatchDog(); None setOnWatchDog() None None (Since Samsung Smart TV version 2.265)
5.5.2. setOffWatchDog()
setOffWatchDog
Turns off the Watch dog function. Syntax Parameter Return Value Remarks Example Enumeration var pluginAPI = new Common.API.Plugin(); pluginAPI.setOffWatchDog(); None setOffWatchDog() None None (Since Samsung Smart TV version 2.265)
47
5.5.3. setOnOSDState()
setOnOSDState
Sets the area where OSD is protected. Syntax setOnOSDState(left, top, width, height) left : left coordinate of the area Parameter top : top coordinate of the area width : width of the area height : height of the area Return Value Remarks Example Enumeration var pluginAPI = new Common.API.Plugin(); pluginAPI.setOnOSDState(0,0, 330, 540); None None (Since Samsung Smart TV version 2.265)
5.5.4. setOffOSDState()
setOffOSDState
Cancels the previously set OSD area. Syntax setOffOSDState(left, top, width, height) left : left coordinate of the area Parameter top : top coordinate of the area width : width of the area height : height of the area Return Value Remarks Example Enumeration var pluginAPI = new Common.API.Plugin(); pluginAPI.setOffOSDState(0,0, 330, 540); None None (Since Samsung Smart TV version 2.265)
48
registKey
Lets the Application Manager register specific key Syntax Parameter Return Value registKey(pNumKeyCode) pNumKeyCode: key code None Registration/Unregistration of keys should be done after window.onshow event. Refer Remarks to Chap. 6.4 How to use keys on remote control for more details. (Since Samsung Smart TV version 2.265) Example Enumeration var pluginAPI = new Common.API.Plugin(); pluginAPI.registKey(tvKey.KEY_ TOOLS); None
5.5.6. unregistKey()
unregistKey
Lets the Application Manager unregister specific key Syntax Parameter Return Value unregistKey(pNumKeyCode) pNumKeyCode: key code None Registration/Unregistration of keys should be done after window.onshow event. Refer Remarks to Chap. 6.4 How to use keys on remote control for more details. (Since Samsung Smart TV version 2.265) Example Enumeration var pluginAPI = new Common.API.Plugin(); pluginAPI.unregistKey(tvKey.KEY_ TOOLS); None
5.5.7. registIMEKey()
registIMEKey
Lets the Application Manager register IME key
49
5.5.8. unregistIMEKey()
unregistIMEKey
Lets the Application Manager unregister IME key Syntax Parameter Return Value unregistIMEKey() None None Unregisters number keys from 0 to 9, -(hyphen), previous channel key used in entering IME. Remarks Registration/Unregistration of keys should be done after window.onshow event. Refer to Chap. 6.4 How to use keys on remote control for more details. (Since Samsung Smart TV version 2.265) Example Enumeration var pluginAPI = new Common.API.Plugin(); pluginAPI.unregistIMEKey(); None
5.5.9. registAllKey
registAllKey
Lets the Application Manager register all keys
50
5.5.10.
unregistAllKey()
unregistAllKey
Lets the Application Manager unregister all keys Syntax Parameter Return Value unregistAllKey() None None Unregisters all keys Remarks Registration/Unregistration of keys should be done after window onshow event. Refer to Chap. 6.4 How to use keys on remote control for more details. (Since Samsung Smart TV version 2.265) Example Enumeration var pluginAPI = new Common.API.Plugin(); pluginAPI.unregistAllKey(); None
5.5.11.
registFullWidgetKey()
registFullWidgetKey
Lets the Application Manager register specific key group Syntax Parameter registFullWidgetKey() None
51
5.5.12.
registPartWidgetKey()
registPartWidgetKey
Lets the Application Manager register specific key group Syntax Parameter Return Value registPartWidgetKey () None None Registers keys for part widget Remarks Registration/Unregistration of keys should be done after window onshow event. Refer to Chap. 6.4 How to use keys on remote control for more details. (Since Samsung Smart TV version 2.265) Example Enumeration var pluginAPI = new Common.API.Plugin(); pluginAPI. registPartWidgetKey (); None
5.5.13.
SetBannerState()
SetBannerState
A function using when you want to put volume and channel OSD with the application. Syntax SetBannerState (nState) nState : Defined value on OSD you want to bring with the application. Parameter PL_NNAVI_STATE_BANNER_NONE = 0; PL_NNAVI_STATE_BANNER_VOL = 1; PL_NNAVI_STATE_BANNER_VOL_CH = 2;
52
Example
5.5.14.
ShowTools()
ShowTools
A function to bring popup windows for screen and sound adjustment. Syntax ShowTools (nTool) nTool: Defined value on a popup window you want to bring. Parameter 0 : Sound Setting popup 1 : Picture Setting popup Return Value None You can see the point when the popup window is closed by signing up for Remarks curWidget.onWidgetEvent. (Since Samsung Smart TV version 2.265) curWidget.onWidgetEvent = function(){ // a code that will be executed after closing the popup window Example } var pluginAPI = new Common.API.Plugin(); pluginAPI.ShowTools(1); Enumeration None
53
setOnIdleEvent
The function to set idle on to close the application in case that there is no input for a certain time Syntax Parameter Return Value setOnIdleEvent() None None 1. Default is set as Idle ON. Remarks 2. Recall the function when idle process is required after calling setOffIdleEvent method.(ex. When closing image playing) (Since Samsung Smart TV version 2.265) Example Enumeration var pluginAPI = new Common.API.Plugin(); pluginAPI.setOnIdleEvent(); None
5.5.16.
setOffIdleEvent()
setOffIdleEvent
The function to set idle off in order not to close the application despite no input for a certain time Syntax Parameter Return Value setOffIdleEvent() None None 1. Default is set as idle ON. Remarks 2. Setting Idle off is needed in case of watching clips for a long time (Since Samsung Smart TV version 2.265) Example Enumeration var pluginAPI = new Common.API.Plugin(); pluginAPI.setOffIdleEvent(); None
5.5.17.
setOnScreenSaver()
setOnScreenSaver
54
Example Enumeration
5.5.18.
setOffScreenSaver()
setOffScreenSaver
The function to set off screen saver Syntax Parameter Return Value Remarks setOffScreenSaver() None None Available after calling setOnScreenSaver (Since Samsung Smart TV version 2.265) var pluginAPI = new Common.API.Plugin(); pluginAPI.setOffScreenSaver(); None
Example Enumeration
5.5.19.
isViewerKey()
isViewerKey
The function to decide whether the key value currently entered is for TV View or application Syntax Parameter Return Value isViewerKey (pKeyCode) pKeyCode: entered remote control key value at present True - Key processing by TV Viewer False Key processing by Application When the TV viewer needs to proceed the entered remote control keys, the inputted value in TV viewer is automatically transferred
Remarks
55
5.5.20.
setOnFullScreen ()
setOnFullScreen
The function to set on full screen. Syntax Parameter Return Value Remarks setOnFullScreen() None None In case of <fullwidget>y</fullwidget>, it is not necessary to call this function. (Since Samsung Smart TV version 2.306) var pluginAPI = new Common.API.Plugin(); pluginAPI.setOnFullScreen(); None
Example Enumeration
5.5.21.
setOffFullScreen()
setOffFullScreen
The function to set off full screen. Syntax Parameter Return Value Remarks setOffFullScreen() None None Available after calling setOnFullScreen. (Since Samsung Smart TV version 2.306) var pluginAPI = new Common.API.Plugin(); pluginAPI.setOffFullScreen(); None
Example Enumeration
56
5.6. CImageViewer
Introduces a common module ClmageViewer and describes how to use it
5.6.1. CImageViewer?
CImageViewer is a common module that enables JPEG files to be played in SAMSUNG DTV. With this module, Images can be displayed on DTV big screen with high resolution,1920 x 1080 pixels. In addition, images are marked by scaling the size you need at the location you prefer, and transition effect in various manners is available. If you want to utilize CImageViewer, TV source should be designated as a Media source. Source Transition can be made by setting <srcctl> item to y or through SetMediaSource() of TVMW Plugin.
5.6.2. Specifications
Features
1920 x 1080 pixels Resolution Images are displayed in Media source. The display pixel of the application is marked as 960 x 540 pixels, but that of the displaying image in media source is marked as 1920 x 1080 pixels. Supported file format JPEG only Designate the area where an image should be displayed and play it, the Scaling range image is scaled in observance of the area you set. At this stage, resolution should be set over 300 pixels. If it is less than 30 pixels, images can be distorted or flicking. Total 10 modes are provided. Transition Effects (NONE, FADE1, FADE2, BLIND, SPIRAL, CHECKER, LINEAR, STAIRS, WIPE, RANDOM) Refer to 5.6.4. Transition Effect for more information.
Description
57
Create instance Create ImageViewer instance. var ImageViewer = new CImageViewer('Common ImageViewer');
Initialize ImageViewer Set the area where images are displayed and functions which will execute each event. show() method shows the area managed by ImageViewer on screen. Area designation via setFrameArea() method is executed based on basic resolution (960x540 pixel). The appointed area operates at 1920x1080 pixel.
ImageViewer.setFrameArea(100, 100, 300, 300); ImageViewer.setOnNetworkError(function(){ alert('Network error occurs!'); }); ImageViewer.show();
Play images Play images. Images remain original proportion at the designated areas and they are indicated by scaling.
Closing the App When the App is closed, ImageViewer should be initialized with calling destroy() method. In case that the application is closed without initialization while playing images in ImageViewer, fatal problems such as TV system pause might occur and there could be toubles using ImageViewer in other applications.
58
Description
It is available to refer to variables of Effect members in an instance of CImageViewer or CImageViewer class. var ImageViewer = new CImageViewer('Common ImageViewer'); ImageViewer.Effect.FADE2 or CImageViewer.Effect.FADE2
5.6.4.1.
Display the first image Prepare the second image Display the second image Prepare the third image
Play the first image through .play(). Buffering complete event occurs while playing, afterward, Rendering complete event which informs that the image are thoroughly scattered on screen takes place. Then, call prepareNext() to prepare next image. The screen has not been changed because preparation is proceeded on background. When the image is ready to show, Buffering complete event informs that. Since this point, Transition Effect is available to see by calling .showNow(). After the Effect is completed, Rendering complete event occurs again to proceed next image.
59
5.6.4.2.
An image display is terminated, the next image is loaded. When loading is completed, Transition effect starts to play. After the Transition effect, the next image is loaded. The points when image display is ended and loading is completed are acknowledged by the Event loaded from ImageViewer. ImageViewer Setup Full screen is designated as area of use for ImageViewer. Register a function to find out the points an image started to be loaded and playing is over.
ImageViewer = new CImageViewer(Common ImageViewer'); ImageViewer.setFrameArea(0, 0, 960, 540); ImageViewer.setOnBufferingComplete(function(){ alert('Image ready!'); }); ImageViewer.setOnRenderingComplete(function(){ alert('You can prepare next image!'); });
Slideshow Mode Setup There are many differences in internal process sequences between general image display and image display by Transition effect. Set a method notifying slideshow mode to enable ImageViewer to execute Transition effect.
ImageViewer.startSlideshow();
Play the first image The first image is played with play() method. Factors such as width and height except URL do not need to
60
Prepare to load the next image The next image is loaded after the first image is displayed. The moment when the first playing is ended is equal to the point when the registered function via setOnRenderingComplete() begins to execute. Then, location of the image and effects you intend to apply are settled by prepareNext(). After a while, Buffering Completed, which means that the next image is ready for display, occurs.
Start Effect Transition effect starts to play once showNow() is called. When Effect animation is completed, Rendering Complete event, which indicates completion of image display, takes place. Successive Transition effect can be realized by reiterating process . Be sure to remember that calling showNow() should be made after Buffering Complete event. End slideshow mode Call endSlideshow() to sneak out of slideshow mode. This method enables next images to display normally.
ImageViewer.endSlideshow();
5.6.4.3.
There are several restrictions in using Transition effect. Scaling is not available.
Transition effect applies to the whole screen, so it is not available to operate with scaling simultaneously. Images should be palyed in full screen (960x540 pixels). Set as shown below.
Images are displayed at the center of screen in original size. If the size of original image is larger than width 1920 pixels and height 1080 pixels, the image will be downscaled in accordance with aspect ratio, and displayed in the center screen.
61
If other methods are operated while proceeding Transition effect, several problems occur such as troubles on image transition. It is recommended that other operations be done after Rendering complete event indicating that the effect is over. Hardware restrictions
SAMSUNG DTV has several models, but some of them could not support Transition effect due to hardware restrictions. CImageViewer provides isEffectAvailable() method to check the availability.
5.6.5. Events
ImageViewer loads various events in order to control image display more precisely. You can operate events after registering a function to the necessary Event.
Event
Buffering start
Description
If the image you intend to play exists on the internet, this occurs when the image starts to be loaded actually after successful connection with server.
Function
setOnBufferingStart()
This happens when the image is ready to display after loading. This occurs when an image is completely displayed on the screen. In case of using Transition effect, this happens when Effect animation has been completed. This appears in case that image URL Is not accessed normally. This takes place when image decoding and rendering are failed.
setOnBufferingComplete()
setOnRenderingComplete()
Network error
setOnNetworkError()
Render error
setOnRenderError()
5.6.6.1.
The string $WIDGET indicates a directory containing an application. Images in the application can be played by sending strings as shown below to ImageViewer.play().
62
5.6.6.2.
The string '$USB_DIR' indicates USB. To display images in USB, the location where the USB is mounted in TV is needed because TV has plural USB ports, and mounting path varies for each USB connection. The location can be found via Storage Plugin. Refer to Plugin guide for more details on Storage Plugin. Here, we apply minimum functions to show examples. How to figure out mount route The path to mount USB is found out by Storage plugin. Root directory path of USB is completed by adding the path mounted by the string $USB_DIR which indicates USB.
// Plugin object Designated var eStoragePlugin = document.getElementById('pluginObjectStorage'); // Provided that one USB is connected var deviceId = eStoragePlugin.GetUSBDeviceID(0); // Provided that USB has one partition var mountPath = eStoragePlugin.GetUSBMountPath(deviceId, 0); var USBRootPath = '$USB_DIR/' + mountPath; // USB root directory path
Your TV has more than two USB ports. If you need to control more than two USBs or use USB with divided partitions, other functions in Storage plugin are required. How to create file routes File information in USB is available, using readDir() API of App Engine. readDir() puts file information on the path in an array and returns it. Below shows an example to refer to whether it is a directory or not and file name. Refer to 8. File API for more information.
var fileSystemObj = new FileSystem(); var dirs = new Array(); var files = new Array(); var data = fileSystemObj.readDir(USBRootPath); for (var i = 0; i < data.length; i++) { if (data[i].isDir) { dirs.push(data[i].name); }
63
The whole path of image files in USB is created by the file information figured above.
'$USB_DIR/sda1/myphotos/picture_2.jpg'
ImageViewer.play(USBImageFile);
CImageViewer
A class to play images Library path Syntax $MANAGER_WIDGET/Common/API/CImageViewer.js New CImageViewer(objectName:String) objectName:String Parameter Includes names to distinguish generated objects. The debug message which occurred from ImageViewer has the name on it. Return Value CImageViewer object ImageViewer provided by TV in reality is only one. Therefore, it is urged that one object of CImageViewer be created. Remarks If an image is played via ImageViewer, destroy() should be called when closing the application. (Since Application Manager 2.269)
64
5.6.7.2.
Effect
Effect
An object defined by Transition Effect Value Library path Syntax Parameter Return Value Remarks Example $MANAGER_WIDGET/Common/API/CImageViewer.js var ImageViewer = new CImageViewer(objectName:String); ImgeViewer.Effect.VALUE None None INIT is for internal action, do not us it. (Since Application Manager 2.269) var ImageViewer = new CImageViewer('Common ImageViewer');
65
Members
Methods
None
5.6.7.3.
clearScreen()
clearScreen
Deletes images displaying on the page Syntax Parameter Return Value Remarks Example Enumeration ImageViewer.clearScreen() None None stop() is not able to remove the playing image. To delete the image, call clearScreen. (Since Application Manager 2.269) var ImageViewer = new CImageViewer('Common ImageViewer'); ImageViewer.clearScreen(); None
5.6.7.4.
destroy()
destroy
Pauses the playing image and initializes ImageViewer Syntax Parameter Return Value ImageViewer.destroy() None None If you have used ImageViewer, this function should be called when closing the Remarks application. It is recommended that the function registered onunload function of (Since Application Manager 2.269) <body> element call this method. The function is called when the application ends.
66
5.6.7.5.
endSlideshow()
endSlideshow
Ends slideshow mode Syntax Parameter Return Value ImageViewer.endSlideshow() None None Call startSlideshow() to enter slideshow mode which includes transition effect. Remarks prepareNext() and showNow() work only in slideshow mode. (Since Application Manager 2.269) var ImageViewer = new CImageViewer('Common ImageViewer'); Example ImageViewer.startSlideshow(); // Use transition effect ImageViewer.endSlideshow(); Enumeration None
5.6.7.6.
getStopFlag()
getStopFlag
Confirms that ImageViewer is stopped or not Syntax Parameter Return Value Remarks Example Enumeration ImageViewer. getStopFlag(); None ImageViewer.getStopFlag(); None Boolean If the ImageViewer is stopped, return true, if it is operating, return false. (Since Application Manager 2.269) var ImageViewer = new CImageViewer('Common ImageViewer');
67
hide
Hides areas managed by ImageViewer Syntax Parameter Return Value Remarks ImageViewer.show(); Example // Play images! ImageViewer.stop(); ImageViewer.hide(); Enumeration None ImageViewer.hide(); None None (Since Application Manager 2.269) var ImageViewer = new CImageViewer('Common ImageViewer');
5.6.7.8.
isEffectAvailable()
isEffectAvailable
Checks if Transition effect is available Syntax Parameter ImageViewer.isEffectAvailable(); None Boolean Return Value If user settings are feasible for Transition effect, return true, if not, return false. (Since Application Manager 2.269) Remarks Example Enumeration Some models do not support Transition effect due to hardware restrictions. In these models, Effect animation is not workable even in slideshow mode. var ImageViewer = new CImageViewer('Common ImageViewer'); ImageViewer.isEffectAvailable(); None
5.6.7.9.
play()
Play
Plays images
68
Parameter
5.6.7.10.
prepareNext()
prepareNext
Method to load the next image to execute Transition effect in slideshow mode Syntax ImageViewer.prepareNext(url:string, effect:ImageViewer.Effect); url:string Available to display image URL, images in Application and USB Parameter effect:ImageViewer.Effect Refer to Transition effect you intend to apply and Effect variables in the instance of CImageViewer. Return Value None When this method is called, an image is started to be loaded. Effect animation is shown by calling showNow() after Buffering Complete event. Remarks Transition effect might not be supported by several models because of hardware restrictions. Use isEffectAvailable() to find out that Transition effect is available in your TV. (Since Application Manager 2.269) Example var ImageViewer = new CImageViewer('Common ImageViewer'); ImageViewer.setFrameArea(0,0,960,540); ImageViewer.startSlideshow();
69
5.6.7.11.
setFrameArea()
setFrameArea
Sets the area where images are marked. Images are displayed within the area. Syntax ImageViewer.setFrameArea(left:Number, top:Number, width:Number, height:Number); left:Number Left coordinate of the area top:Number Top coordinate of the area Parameter width:Number Width of the area height:Number Height of the area * Unit is pixel. Return Value None For instance, if the image is set as setFrameArea(0,0,225,200), the upper left area of TV screen is transferred to Media source, Images at 450 x 400 pixels are realized Remarks remaining intact. If an image you intend to display is larger than the standard, it is scaled in accordance with aspect ratio and displayed in the area. (Since Application Manager 2.269) Example Enumeration var ImageViewer = new CImageViewer('Common ImageViewer'); ImageViewer.setFrameArea(0,0,480,320); ImageViewer.play(image_url, image_width, image_height); None
70
setOnBufferingComplete
Registers a function executed in case of Buffering complete event while loading an image Syntax Parameter Return Value ImageViewer.setOnBufferingComplete(callback:function); callback:function The function executed in the event of Buffering complete event None Buffering complete event occurs after image loading. If this event takes places after Remarks calling prepareNext(), it means that the image is ready for Transition effect. At this stage, calling showNow() begins effect animation. (Since Application Manager 2.269) var ImageViewer = new CImageViewer('Common ImageViewer'); Example ImageViewer.setOnBufferingComplete(function(){ // blah blah }); Enumeration None
5.6.7.13.
setOnBufferingStart()
setOnBufferingStart
Registers a function executed in case of Buffering start event Syntax Parameter Return Value ImageViewer.setOnBufferingStart(callback:function); callback:function The function executed in the event of Buffering start event None If the image you intend to play is on the Internet, this event happens when starting to Remarks load actual image data after connecting to the server successfully. (Since Application Manager 2.269) var ImageViewer = new CImageViewer('Common ImageViewer'); Example ImageViewer.setOnBufferingStart(function(){ // blah blah }); Enumeration None
71
setOnNetworkError
Registers a function executed in case of Network error event Syntax Parameter Return Value Remarks ImageViewer.setOnNetworkError(callback:function); callback:function The function executed in the event of Network error event None This event occurs in case of network errors while loading images. (Since Application Manager 2.269) var ImageViewer = new CImageViewer('Common ImageViewer'); Example ImageViewer.setOnNetworkError(function(){ // blah blah }); Enumeration None
5.6.7.15.
setOnRenderError()
setOnRenderError
Registers a function executed in case of Decoding or Rendering error Syntax Parameter Return Value ImageViewer.setOnRenderError(callback:function); callback:function The function executed in case of Decoding or Rendering error None This event takes place when an error occurs while decoding and rendering after Remarks buffering and when trying playing a format not basically supported. (Image files except for JPEG) (Since Application Manager 2.269) var ImageViewer = new CImageViewer('Common ImageViewer'); Example ImageViewer.setOnRenderError(function(){ // blah blah }); Enumeration None
72
setOnRenderingComplete
Registers a function executed in case of Rendering complete event Syntax Parameter Return Value ImageViewer.setOnRenderingComplete(callback:function); callback:function The function executed in the event of Rendering complete event None This event occurs when the image displays completely on the screen. If Transition Remarks effect is used, the event occurs at the point when Effect animation is ended. (Since Application Manager 2.269) var ImageViewer = new CImageViewer('Common ImageViewer'); Example ImageViewer.setOnRenderingComplete(function(){ // blah blah }); Enumeration None
5.6.7.17.
show()
Show
Shows area managed by ImageViewer on screen Syntax Parameter Return Value Remarks ImageViewer.show(); Example // Play images! ImageViewer.stop(); ImageViewer.hide(); Enumeration None ImageViewer.show(); None None (Since Application Manager 2.269) var ImageViewer = new CImageViewer('Common ImageViewer');
5.6.7.18.
showNow ()
showNow
73
5.6.7.19.
startSlideshow ()
startSlideshow
Starts slideshow mode Syntax Parameter Return Value ImageViewer.startSlideshow() None None If you want to close slideshow mode, call endSlideshow(). Remarks Methods such as prepareNext() and showNow() are available only in slideshow mode. (Since Application Manager 2.269) var ImageViewer = new CImageViewer('Common ImageViewer'); Example ImageViewer.startSlideshow(); // Use transition effect
74
5.6.7.20.
stop ()
stop
Stops image processing Syntax Parameter Return Value ImageViewer.stop(); None None This does not get rid of playing images on screen. It stops image processing such as Remarks image loading and Transition effect animation. If you want to remove playing images from the screen, refer to clearScreen(). (Since Application Manager 2.269) var ImageViewer = new CImageViewer('Common ImageViewer'); ImageViewer.setFrameArea(50,50,480,320); ImageViewer.play(image_url, image_width, image_height); ImageViewer.stop(); Enumeration None
Example
75
var widgetAPI = new Common.API.Widget(); // Create Common module widgetAPI.sendReadyEvent(); // Send ready message to Application Manager
<body onload="Main.onLoad();">
76
Create a function that will be registered in the onkeydown property. Main.keyDown = function(){ var keyCode = event.keyCode; alert("Main Key code : " + keyCode); switch (keyCode) { case tvKey.KEY_LEFT: /** * Code for Left key event! */ 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; } } // Key handler
77
Single-wide Application
KEY_WHEELDOWN KEY_WHEELUP KEY_RED KEY_GREEN KEY_YELLOW KEY_BLUE KEY_RW KEY_PAUSE KEY_FF KEY_PLAY KEY_STOP KEY_ENTER KEY_RETURN KEY_EXIT
Each application registers/unregisters keys additionally by utilizing registKey() of common module, Widget. You should be aware of one thing below. Key registration/unregistration should be done after window.onshow event.
The keys registered/unregistered after window.onshow event are normally processed, but those before window.onshow event could be ignored. Register a function executed in window.onshow prior to calling this method because window.onshow event happens after calling sendReadyEvent() of common module, Widget. Below is an example.
var WIDGET = new Common.API.Widget(); var TVKEY = new Common.API.TVKeyValue(); var PLUGIN = new Common.API.Plugin(); Main.onLoad = function(){ window.onshow = function(){
// For sendReadyEvent() // Remote controller key value object // Plugin common module
PLUGIN.registKey(TVKEY.KEY_VOL_UP);
78
The time of key registration/unregistration after window.onshow event does not matter.
?country=US&language=1&modelid=Valencia&server=development&remocon=2_35_259&area=USA&product =1&mgrver=3.000&id=ori590e@exxx.com&pw=pxxxx&payload={key1:value2,key2:value2}
79
Value
Country code Language code Digital TV Model ID development | operating Region Code Chapter 9.1.
Description
Country code that has already been assigned. Refer to
Replaced with 'lang attribute Digital TV Model ID server type: Development Server or Operating Server No use Region code that has already been assigned. Refer to chapter9.3. Id inputted in SSO. It is passed only when entering application
Id
string
after sign-in. It should be used after calling decodeURIComponent(). Pw inputted in SSO. It is passed only when entering
pw
string
product mgrver
Refer to 9.4. Product Category If your application is enabled after a specific version of Samsung Smart TV, you should check mgrver. Extra Information for specific service. It is passed only when
payload
string(JSON)
entering application after push notification. It should be used after calling decodeURIComponent().
80
By doing the above work, you can make the App Engine decode images. For images that have been decoded once by the browser, they dont have to be decoded again later when they are used elsewhere, so that your TV can display them faster.
81
6.14.1.
Using XMLHttpRequest
If you create and use XHR objects repeatedly in Samsung TVs, you will be faced with a problem of your applications working in a wrong way. The solution to this problem is set forth in Ch. 4.5 Example for XHR communication.
6.14.2.
If the content in the tag is replaced with the innerHTML property, the corresponding node in the DOM tree is closed and a new one is created and connected. The closed node remains in the memory. If this procedure occurs repeatedly, you could face memory full. The solution to this problem is to use the putInnerHTML() method of the Widget object in the common module. For more information on this method, refer to Ch. Common modules.
82
You can save javascript loading time by minimizing javascript in the initial page. On-Demand Javascript Loading is that Download Javascript when it required, instead of downloading it all in the initial page. Divide a big javascript file into several javascript file. And then only some Javascript files needed to generate the initial page amog others. Therefore you can include javascript files minimally in the initial page. And you can load other javascript files by inserting script element as following.
83
6.20.2.
App Engine loads an image for an elements background style when its background style matching is invoked. Because deleting background style of some elements not nessasary in initial page can speed the application loading up. You can apply elements background style when it required as follows.
function loadBackgroundImage(eid, url){ document.getElementById(eid).style.backgroundImage = "url("+url+")"; } function loadCSSImage(){ loadBackgroundImage("Full1", "img/Full_1.png"); loadBackgroundImage("Full2", "img/Full_2.png"); loadBackgroundImage("Full3", "img/Full_3.png"); }
6.20.3.
If you using setTimeout function properly, a background of initial page can be shown more quikly. Separate Main.onLoad function into two steps. The first step is to generate background of initial page. The second step is to do other works not necessary to generate the background of initial page. Following shows this technique.
84
Main.onLoad = function(){ generate background var widgetAPI = new Common.API.Widget(); widgetAPI.sendReadyEvent(); setTimeout('Main_onLoad2()',0); } function Main_onload2(){ IncludeJavascript(); // refer to 6.20.1 generateDetailPage(); }
var Main = { } var WIDGET = new Common.API.Widget(); Main.onLoad = function() { alert("Main : onLoad()"); WIDGET.sendReadyEvent(); includeCSS ('red_box.css'); setTimeout("insertHTML()", 3000); // // } insertHTML(); setTimeout("includeCSS ('red_box.css')", 3000); // For sendReadyEvent() // The first function
85
Add HTML Element and load CSS dynamically. Get ride of the annotation from Main.onLoad() in the example above. CSS is loaded 3 secs after HML Div element is added. Therefore, there is no change.
86
7. App Engine
This section sets forth the browser for running applications provided with Samsung Smart TV, App Engine.
When an application is displayed and behaves on the screen, its image and text generation should be controlled and managed. For Samsung TVs with Samsung Smart TV installed, it is App Engine that performs such work. An applications behaviors and displays are made by App Engine. While Internet Explorer and Firefox are PC-based browsers, App Engine is Samsung TV-based browser.
87
8. File API
This section introduces the file input/output operation system which the Samsung TV application engine supports.
8.2. API
The following is a list of interfaces that are provided by the Samsung TV application engine. You can use them in JavaScript.
8.2.1. FileSystem()
FileSystem
Generates file system instance available to be used in an application Syntax Parameter Return Value new FileSystem(); None App Engine FileSystem object This function Returns FileSystem instance defined in App Engine. Through this Remarks operation, reading and writing texts are available. Binary format file is not supported. Example Members var fileSystemObj = new FileSystem(); None
88
8.2.2. openCommonFile()
openCommonFile
Opens file in common storage area of an application. Syntax fileSystemObj.openCommonFile(filePath:String, mode:String) filePath:String path including a file name. mode:String r : Open a file for reading. The file must exist. w : Create an empty file for writing. If a file with the same name already exists its content is erased and the file is treated as a new empty file. a : Append to a file. Writing operations append data at the end of the file. The file is Parameter created if it does not exist. r+ : Open a file for update both reading and writing. The file must exist. w+ : Create an empty file for both reading and writing. If a file with the same name already exists its content is erased and the file is treated as a new empty file. a+ : Open a file for reading and appending. All writing operations are performed at the end of the file, protecting the previous content to be overwritten. You can reposition (fseek, rewind) the internal pointer to anywhere in the file for reading, but writing operations will move it back to the end of file. The file is created if it does not exist. Return Value App Engine file object
89
8.2.3. closeCommonFile()
closeCommonFile
Closes files opened by openCommonFile(). Syntax Parameter Return Value Remarks fileSystemObj.closeCommonFile(fileObj:App Engine file object) fileObj: App Engine file object The file instance returned by openCommonFile() Boolean Opened files should be closed. Especially, if a file is outputted by methods such as writeAll(), the output is not saved without closing the file object. var fileSystemObj = new FileSystem(); Example var fileObj = fileSystemObj.openCommonFile(curWidget.id + '/testFile.data', 'w'); fileObj.writeAll('something to write.'); fileSystemObj.closeCommonFile(fileObj); Enumeration None
8.2.4. deleteCommonFile()
deleteCommonFile
Deletes files in Input/Output area Syntax Parameter fileSystemObj.deleteCommonFile(filePath:String) filePath:String path including the name of a file to delete
90
8.2.5. createCommonDir()
createCommonDir
Creates directories in file input/output area Syntax Parameter Return Value Remarks fileSystemObj.createCommonDir(directoryPath:String) directoryPath:String path including the name of a directory to create Boolean Creating a directory named curWidget.id to avoid crash between file names in other applications. var fileSystemObj = new FileSystem(); var bResult = fileSystemObj.createCommonDir(curWidget.id); None
Example Enumeration
8.2.6. deleteCommonDir()
deleteCommonDir
Deletes directories in file input/out area Syntax Parameter Return Value Remarks Example Enumeration fileSystemObj.deleteCommonDir(directoryPath:String) directoryPath:String path including a name of directory to delete Boolean None var fileSystemObj = new FileSystem(); var bResult = fileSystemObj.deleteCommonDir(curWidget.id); None
91
isValidCommonPath
Checks if there is a directory Syntax Parameter fileSystemObj.isValidCommonPath(directoryPath:String) directoryPath:String path including a name of directory to confirm its existence Int Return Value 0 : JS function failed 1 : valid 2 : invalid Remarks None var fileSystemObj = new FileSystem(); var bValid = fileSystemObj.isValidCommonPath(curWidget.id); Example if (!bValid) { fileSystemObj.createCommonDir(curWidget.id); } Enumeration None
8.2.8. readLine()
readLine
Reads a line in an opened file Syntax Parameter fileObj.readLine() None String Return Value Returns a line ranging to line feed character as a result. If there is nothing to read, return null. Remarks None var fileSystemObj = new FileSystem(); Example var fileObj = fileSystemObj.openCommonFile(curWidget.id + '/testFile.data', 'r'); var strLine = ''; var arrResult = new Array();
92
8.2.9. writeLine()
writeLine
Writes a line in an opened file Syntax Parameter Return Value Remarks fileObj.writeLine(text:String) text:String text to write in a file Boolean None var fileSystemObj = new FileSystem(); Example var fileObj = fileSystemObj.openCommonFile(curWidget.id + '/testFile.data', 'w'); fileObj.writeLine('something to write.'); fileSystemObj.closeCommonFile(fileObj); Enumeration None
8.2.10.
readlAll()
readAll
Reads whole of the opened file Syntax Parameter Return Value Remarks fileObj.readAll() None String Whole contents of the file None var fileSystemObj = new FileSystem(); Example var fileObj = fileSystemObj.openCommonFile(curWidget.id + '/testFile.data', 'r'); var strResult = fileObj.readAll(); alert(strResult); Enumeration None
93
8.2.11.
writeAll()
writeAll
Writes several lines in the opened file Syntax Parameter Return Value Remarks fileObj.writeAll(text:String) text:String test to write in a file Boolean None var fileSystemObj = new FileSystem(); Example var fileObj = fileSystemObj.openCommonFile(curWidget.id + '/testFile.data', 'w'); fileObj.writeAll('something to write.'); fileSystemObj.closeCommonFile(fileObj); Enumeration None
8.2.12.
readDir()
readDir
Able to see file information in USB Syntax Parameter fileSystemObj.readDir(directoryPath:String) directoryPath:String Path of a directory that you want to see. Wors only for USB directory Array The Array containing file information. Each element has file information in a directory. Able to get information by referring to variables below. name : file name Return Value isDir : If a file is a directory, true, if not, false size : File Size (byte) atime : The time when to open a file or access time to a directory with cd command mtime : The time when file contents are changed ctime : The time when file information is changed If there is no directoryPath, return false.
94
Remarks
8.2.13.
openFile()
openFile
Opens files in an application Syntax fileSystemObj.openFile(filePath:String, mode:String) filePath:String path including a file name Parameter mode:String r : Open a file for reading. The file must exist. *only r mode is available. App Engine file object Return Value Returns file object defined in App Engine. Character strings are read By calling readLine(), readAll() methods that file object has. openCommonFile() enablies files to input and output in common area of all Remarks applications, on the other hand, openFile() is only able to read files in directory where an application is installed. var fileSystemObj = new FileSystem(); Example var fileObj = fileSystemObj.openFile('index.html', 'r'); alert(fileObj.readAll()); fileSystemObj.closeFile(fileObj); Enumeration None
95
9. Appendix
9.1. Country Code
You can get this code from Application Manager. Refer ch. 6.7, for more details.
Nations
ALBANIA ANDORRA AUSTRIA BELGIUM BOSNIA BULGARIA CIS CROATIA CYPRUS CZECH DENMARK FINLAND FRANCE GERMANY GREECE HUNGRARY ICELAND IRELAND ITALY LUXEMBOURG MACEDONIA MONTENEGRO NETHERLAND NORWAY POLAND
Code
AL AD AT BE BA BG RU HR CY CZ DK FI FR DE GR HU IS IE IT LU MK ME NL NO PL PORTUGAL ROMANIA SERBIA SLOVAKIA SLOVENIA SPAIN SWEDEN SWITZERLAND UK AMERICA CANADA MEXICO ARGENTINA CHILE PERU THAILAND VIETNAM MALAYSIA INDONESIA PHILIPPINES BRAZIL ALGERIA MOROCCO TUNISIA
Nations
Code
PT RO RS SK SI ES SE CH GB US CA MX AR CL PE TH VN MY ID PH BR DZ MA TN
96
Nations
Afrikaans Amharic Arabic Bulgarian Chinese Croatian Czech Danish Dutch English English(GB) Estonian Finnish French French(America) German Greek, Modern Hausa Hebrew Hindi (Not provided) Hongkong Hungarian Igbo Indonesian Italian Korean
Code
af am ar bg zh-CN hr cs da nl en en-GB et fi fr fr-US de el ha he en-GB zh-HK hu ig id it ko Latvian Lithuanian Lithuanian Norwegian Persian Polish Portuguese
Nations
Code
lv lt lt no fa pl pt pt-US ro ru sr sk es es-US sw sv zh-TW en-GB th tr ur vi xh yo zu
Portuguese(America) Romany Russian Serbian Slovak Spanish Spanish(America) Swahili Swedish Taiwan Tamil (Not provided) Thai Turkish Urdu Vietnamese Xhosa Yoruba Zulu
97
Language
Korean English Spanish(America) French(America) Portuguese(America) Bulgarian Croatian Czech Danish Dutch Finnish French German Modern Greek Hungarian Italian Norwegian English(GB) Polish Portuguese Romany Russian Serbian Slovak
Code
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 Spanish Swedish Turkish Chinese Hongkong Taiwan Japanese Maori CMN YUE Hindi Estonian Latvian Lithuanian Arabic Persian QAA AD Catalan VAL Hebrew OTHER Thai
Language
Code
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46
98
Code
KOR USA BRA PANEURO CHI HKG ARB PANNORDIG SOUTHEASTASIA Korea USA/Canada/Mexico
Region
Brazil, Paraguay, Uruguay, Argentine Europe China Hong Kong Arab Nordic South-East Asia (Vietnam, Thailand, India, China, Iran, Israel, Central Asia, East Asia, Africa)
ASIA_ATV
South-East Asia (Vietnam, Thailand, India, China, Iran, Israel, Central Asia, East Asia, Africa)
Australia , New Zealand, Singapore Taiwan, Columbia TURKEY, MOROCCO, TUNISIA Indonesia, Malaysia, Republic of South Africa, Vietnam CIS Philippine South Africa DTV
99
Code
0 1 2 TV Monitor Blue-ray Disk
Region
100