Apps Framework Scene Manager API[V1.10]
-
Upload
levanlai00 -
Category
Documents
-
view
225 -
download
0
Transcript of Apps Framework Scene Manager API[V1.10]
@Samsung Electronics Copyright All Rights Reserved 1
Apps Framework Scene Manager API
Version 1.10
Samsung Smart TV
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 2
1. SCENE MANAGER ................................................................................................................................................. 4
1.1. INTRODUCTION TO SCENE MANAGER ............................................................................................................... 4
1.1.1. Getting Started with the Scene Manager ..................................................................................................... 4
1.1.2. Exporting .............................................................................. 오류! 책갈피가 정의되어 있지 않습니다.
1.1.3. Nesting Scenes ............................................................................................................................................ 5
1.2. EXAMPLES TO EXPLAIN THE BASIC FUNCTIONS ................................................................................................ 6
1.2.1. show() ......................................................................................................................................................... 8
1.2.2. Focus() ........................................................................................................................................................ 9
1.2.3. Hide() .......................................................................................................................................................... 9
1.2.4. Get() .......................................................................................................................................................... 10
1.3. ADVANCED SCENE MANAGER EXAMPLE ......................................................................................................... 15
1.3.1. Nesting Scenes Example ........................................................................................................................... 16
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 3
Preface
Purpose of Document
This document is written for the users of Samsung Smart TV SDK, who would like to use the
WYSIWYG Editor and its features for the first time. This document contains detailed examples to
better understand the process of creating scenes and exporting them, to make use of them in the
applications. It also explains the syntax, and working of the inbuilt functions in the scene manager.
After reading the document, the reader should be able to make full and effective use of the scene
manager and create basic applications.
Target Readers
This document targets the first time users of Samsung Smart TV SDK and its new inclusion, the
Samsung WYSIWYG Editor. However, the reader should have basic knowledge about Java
Scripting, CSS and HTML. The document explains only the use of Samsung Smart TV SDK and its
features. No explanations are provided about the programming syntax and conventions of the
scripting and the programming language used.
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 4
1. Scene Manager
1.1. Introduction to Scene Manager
The Scene manager is a new inclusion to the Samsung Smart TV SDK 1.5.0. Scene
manager is a part of the Samsung WYSIWYG Editor. It provides the developer with GUI and built-
in functions to build and navigate between different pages of the application. These are called as
scenes in the rest of the document. It helps the developer to build applications for Samsung Smart
TV with much ease. All the new features of the Samsung WYSIWYG Editor are explained in detail
in the Samsung Smart TV SDK Manual. Therefore this section focuses on how to make the best use
of Scene Manager. The basic inbuilt functions of Scene Manager are explained with examples.
1.1.1. Getting Started with the Scene Manager
Step 1: - Open the Samsung WYSIWYG Editor
Step 2: -The editing window shows a white space for visually adding and arranging various
components. This is the default scene “Scene1” of the Scene Manager.
Step 3: - You can add or remove scenes using the Scene List panel found on the left side of the
screen.
Step 4: - More on the Scene List panel can be found on the SDK manual. To add or remove a Scene
click -> right-click on the Scene List panel and add/remove scene. You can also change the
property of the scene using the Properties panel found on the right.
Step5: - Repeat the step as many ever times to get the required number of scenes for the application.
Now export the scenes to SDK and start using the basic functions to build an application.
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 5
Fig 1 WYSIWYG Editor
1.1.2. Nesting Scenes
The Scene Manager also provides the functionality of nesting or docking the scenes inside one
another. For instance, assume that the application has three scenes Scene1, Scene2, Scene3. By
default Scene1 cannot be resized. If the developer wants to place Scene2 and Scene3 inside Scene1,
he has to first add three Scenes, and resize Scene2 and Scene3 until they completely fit into Scene1.
However, Scene2 and Scene3 will not be seen on the emulator, unless the Visibility properties of
both the scenes are set to true. This is because, the Scene1 which has not visibility property always
hides the other scenes added above it. Therefore to see the others scenes on the emulator, set the
visibility property of other scenes to true. After exporting them to SDK, the output is seen as below,
in the emulator. Detailed explanation of nesting scenes will be given when an example of a
complete application is described. The following section explains the process of navigating between
scenes with an example program.
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 6
Fig 2 Nesting Scenes
1.2. Examples to explain the basic functions
As in Fig 2, the JavaScript files Scene1.js and Scene2.js correspond to the scenes that have
just been imported into the SDK. You can add all the code in these files to navigate between
different scenes, as explained shortly.
Open the Scene1.js and you see a basic set of functions that has been created already to be
used. All these functions are commented appropriately so that the developer can understand what
each function does at each place. For instance, if the developer wishes to place any statements that
has to executed every time when the scene is shown, it can be placed under the function name
handleshow(). This function will be called every time a scene is shown. Similarly, any function that
has to be executed on key events can be given under the handleKeyDown () function under specific
cases of keyCodes
function SceneScene1(options) {
this.options = options;
}
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 7
SceneScene1.prototype.initialize = function () {
alert("SceneScene1.initialize()");
// this function will be called only once when the scene manager show this scene first time
// initialize the scene controls and styles, and initialize your variables here
// scene HTML and CSS will be loaded before this function is called
}
SceneScene1.prototype.handleShow = function () {
alert("SceneScene1.handleShow()");
// this function will be called when the scene manager show this scene
}
SceneScene1.prototype.handleHide = function () {
alert("SceneScene1.handleHide()");
// this function will be called when the scene manager hide this scene
}
SceneScene1.prototype.handleFocus = function () {
alert("SceneScene1.handleFocus()");
// this function will be called when the scene manager focus this scene
}
SceneScene1.prototype.handleBlur = function () {
alert("SceneScene1.handleBlur()");
// this function will be called when the scene manager move focus to another scene from this scene
}
SceneScene1.prototype.handleKeyDown = function (keyCode) {
alert("SceneScene1.handleKeyDown(" + keyCode + ")");
// TODO : write an key event handler when this scene get focused
switch (keyCode) {
case $.sfKey.LEFT:
break;
case $.sfKey.RIGHT:
break;
case $.sfKey.UP:
break;
case $.sfKey.DOWN:
break;
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 8
case $.sfKey.ENTER:
break;
case $.sfKey.RETURN:
break;
case $.sfKey.EXIT:
break;
}
}.
The above code will appear in Scene1.js when exported using the export button in the Scene
Manager.
Functions
--show()
--hide()
--focus()
--get()
1.2.1. show()
Syntax $.sfScene.show (‘SceneID’)
SceneID: (String) id value of the current scene
Description The show function is used to show a scene. The show function just makes the scene
visible, however you wouldn‟t be able to see the scene on the screen until the focus
property of the scene is set.
Every time the show function is called; show() function makes an indirect call to
the handleshow() function. The flowchart of it is shown below.
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 9
Fig 3 Internal call of the Scene Manager to handleshow() and Initialize()
1.2.2. Focus()
Syntax $.sfScene.focus (‘SceneID’)
SceneID: (String) id value of the current scene.
Description The focus function sets the focus on the scene. Once the focus is set on a scene, the
scene is visible on the screen and the viewer can view them.
Similar to show(), Focus makes call to handleFocus() and handleBlur() functions,
based on whether a scene gets the focus or not
1.2.3. Hide()
Syntax $.sfScene.hide (‘SceneID’)
SceneID: (String) id value of the current scene.
Description The hide function hides the scene and hence the viewer will not be able see the scene
on the screen.
Likewise, hide() makes call to handleHide()
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 10
1.2.4. Get()
Syntax $.sfScene.get (‘SceneID’)
SceneID: (String) id value of the current scene.
Description The get function is used to get an instance of a scene. Using this function, an instance
of scene1 can be used in scene2 to call a function or a variable already declared in
scene1.
Example illustrating the use of show(), focus(), hide() functions
An example application is shown to navigate between different scenes.
Step1: - Create the two scenes (as showing in Figure 1) using the WYSIWYG Editor and add
different background images for both the scenes just to make sure that you can differentiate
them.
Step2: - Insert a label on both the scene and enter the text you would like to see. It would serve as
an instruction for the user. And click the export button to export it to the SDK.
Step2: -Now you have to add a few lines of code to navigate between scenes. It is left up to the
developer to decide on which event the scene should change. However, this example
changes the scene when the Up/Down arrow key of the remote control is pressed
Step3: -Unlike windows application development, Samsung Smart TV application development has
only one even called “handleKeyDown” event. This property will become true for various
buttons when they are clicked.
Step4: -Therefore the code for switching between scenes has to be added in the corresponding Cases
of the handleKeyDown events. In this example the source code is included in the
handleKeyDown event of UP/DOWN keys.
Step5: -The code for changing scenes has to be included in the corresponding JavaScript files of the
scenes.
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 11
SceneScene1.prototype.handleKeyDown = function (keyCode) {
alert("SceneScene1.handleKeyDown(" + keyCode + ")");
// TODO : write an key event handler when this scene get focused
switch (keyCode) {
case $.sfKey.LEFT:
break;
case $.sfKey.RIGHT:
break;
case $.sfKey.UP:
$.sfScene.hide('Scene1');
$.sfScene.show('Scene2');
$.sfScene.focus('Scene2');
break;
case $.sfKey.DOWN:
$.sfScene.hide('Scene1');
$.sfScene.show('Scene2');
$.sfScene.focus('Scene2');
break;
case $.sfKey.ENTER:
break;
default:
alert("Unhandled Key!");
break; }}
The above code should be added to the handleKeyDown() function found in the Scene1.js file.
Note that similar code has to be added in Scene2.js to switch to Scene1 while in Scene2. This is
very similar to that of the above code. Note that, a default case has been added to cover all the cases
that have not been specified. However, this default case does not hold good for the RETURN/EXIT
keys. This can however be handled using block() function which has been explained in the later
section of the document.
Now to execute the application, click -> right-click the application name and choose run emulator.
Alternatively, click Emulator -> Run current Document.
The screen shot of emulator has been provided below. This is the output that you always get on a TV.
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 12
Press RETURN to come out of the application (when running the application on the TV Screen).
While in emulator, press the close button or the power button on the emulator.
Fig 4 Output of show() focus() hide() function on the Emulator
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 13
Example explaining the usage of get() function
To make an effective example of the get() function the example is structured as follows. First
declare any string in Scene1. Get an instance of Scene1 in Scene2. Access the string using this
instance in Scene2, and display it in a popup box in Scene2.
For this first insert a new popup box in the WYSIWYG Editor, in the previous design. (Note that if
you are using the same design, you must now be having two scenes, two labels, one in each scene
and a newly inserted popup box component in scene2.). Now that if a popup box has been inserted,
it won‟t be visible in the Samsung WYSIWYG Editor. For viewing the pop up box, set the show()
property of the popup box to true during programming.
As explained above, add a popup box in Scene2 and export the new design. The source code to be
added to each file is explained as below. (Note: As mentioned before back up the code for the
previous design. As exporting the design again after adding a popup box will erase your previous
source code).
Step1: - Declare a string in the Scene1.js. This string should be a global variable and therefore be
declared in the function name sceneScene1 in the JavaScript. Add the following code in
script1.js
function SceneScene1(options) {
this.options = options;
this.str1 = "This string was declared in Scene1 and you are viewing it in Scene2!";
}
Step2: - If you happen to notice the initialize () function in the Scene2.js, the popup box you just
added would have already been initialized. Now in order to display the string in the pop up
box, modify the initialize function as follows. The test1 variable has an instance of Scene1.
It makes a call to the string declared in Scene1 and stores a copy in str2. Then the pop up
box is ready to display the text.
SceneScene2.prototype.initialize = function () {
alert("SceneScene2.initialize()");
var test1= $.sfScene.get('Scene1');
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 14
var str2 = test1.str1;
// this function will be called only once when the scene manager show this scene first time
// initialize the scene controls and styles, and initialize your variables here
// scene HTML and CSS will be loaded before this function is called
$('#svecLabel_9E94').sfLabel({text:'You are in Scene2. Please press Up/Down to goto Scene1', width:'386px'});
$('#svecPopup_5KT5').sfPopup({text: 'Hello' + " " + str2 , Num:'1', callback :
function(rlt){$.sfScene.get('Scene2').popupcallback(rlt)}});
}
Step3:- The final step is to decide on which button event is going to display the popup box. In this
case, it is on RIGHT onKeyDown event of the remote control. This will display the pop up
box. Therefore modify the RIGHT keyCode case of the handleKeyDown function as
follows.
case $.sfKey.RIGHT:
$('#svecPopup_5KT5').sfPopup('show');
break;
„#svecPopup_5KT5 is the id of the popup for which the property is set to true in order to display the
popup. Once it is done, the output of it can be seen in the emulator on pressing the RIGHT button of
the Remote while in Scene2.
The popupcallback() is a user defined function. It is the function that would be called when a
response for the popup has been selected. A user can capture the response of the popup(either true
or false) from this function and use it as an input for the application. The code for it is as follows.
SceneScene2.prototype.popupcallback = function (data) {
alert('SceneScene2.popupcallback() : '+data);
}
This function just prints the response of the popup on the log window. However, you could use it
for other purposes in the application based on your design.
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 15
Fig 5 Popup Output of get() on the Emulator
1.3. Advanced Scene Manager Example
The scene manager Advanced example comprises of an example application to show you the
advanced feature of nesting the scenes within a scene and navigating between them. If you are just a
beginner, you are advised to read the documentation for the Basic Components before you proceed
to the example.
The example is structured as follows. There are three scenes that are nested inside each
other(Scene2 and Scene3 within Scene1). You will be able to navigate or switch between them in
the click of a button. And moreover, every scene has its own components. Therefore when every
scene is shown, its components are also shown.
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 16
1.3.1. Nesting Scenes Example
Step1:- To create nested scenes, use the scene manager, and create three scenes nested inside each
other. The size of Scene1 cannot be adjusted, whereas the size of the other scenes can be
adjusted. This example has 3 scenes. Two scenes are nested inside Scene1.
In the figure below, note that the Scenes may look like separate components, independent
of each other, however, its left up to the programmer to handle them during the
programming.
Scene1 has 3 buttons, Scene2 has one button and one image component, and Scene3 has
one popup and a button. It is possible to vary the sizes of Scene2 and Scene3. Both the
scenes are resized to fit into Scene1 at the same time. For this purpose, the ruler on the
WYSIWYG Editor is used. Once this is done, it is exported to the Samsung Smart TV SDK
using the export button.
Step2:- The button has to be programmed to move the focus between them. This is done with the
following source code in Scene1.
Fig 6 WYSIWYG Editor with 3 Scenes
function SceneScene1(options) {
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 17
this.options = options;
this.index = 1;
}
SceneScene1.prototype.initialize = function () {
alert("SceneScene1.initialize()");
// this function will be called only once when the scene manager show this scene first time
// initialize the scene controls and styles, and initialize your variables here
// scene HTML and CSS will be loaded before this function is called
$('#Button1').sfButton({text:'Scene2', width:'200px'});
$('#Button2').sfButton({text:'Scene3', width:'200px'});
$('#Button3').sfButton({text:'Scene2 and 3', width:'200px'});
$('#Button1').sfButton('focus');
}
SceneScene1.prototype.handleKeyDown = function (keyCode) {
alert("SceneScene1.handleKeyDown(" + keyCode + ")");
// TODO : write an key event handler when this scene get focued
switch (keyCode) {
case $.sfKey.LEFT:
if (this.index ==1)
{
this.index = 3;
$('#Button1').sfButton('blur');
$('#Button2').sfButton('blur');
$('#Button3').sfButton('focus');
}
else if (this.index ==2)
{
this.index = 1;
$('#Button1').sfButton('focus');
$('#Button2').sfButton('blur');
$('#Button3').sfButton('blur');
}
else if (this.index ==3)
{
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 18
this.index = 2;
$('#Button1').sfButton('blur');
$('#Button2').sfButton('focus');
$('#Button3').sfButton('blur');
}
else{}
break;
case $.sfKey.RIGHT:
if (this.index ==1)
{
this.index = 2;
$('#Button1').sfButton('blur');
$('#Button2').sfButton('focus');
$('#Button3').sfButton('blur');
}
else if (this.index == 2)
{
this.index = 3;
$('#Button1').sfButton('blur');
$('#Button2').sfButton('blur');
$('#Button3').sfButton('focus');
}
else if (this.index ==3)
{
this.index = 1;
$('#Button1').sfButton('focus');
$('#Button2').sfButton('blur');
$('#Button3').sfButton('blur');
}
else{}
break;
Step3:- When code for navigation is done, decide on which scene/component is assigned to which
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 19
button. The assignment and navigation is as follows.
Scene1 Button1 -> Show Scene2
Button2 -> Show Scene3
Button3 -> Show Scene2and3
Scene2 Button 4 -> Show image component in scene 2
DOWN -> Go back to button1 with focus to scene1
Scene3 Button 5 -> Show popup component in Scene 3
DOWN -> Go back to button 2 with focus to Scene1
When showing both Scene2 and Scene 3 by clicking on button3, the navigation works as
follows
Scene2 Button 4 -> RIGHT -> Goto Scene3 with focus to Button 5
Scene3 Button 5 -> LEFT -> Goto Scene2 with focus to Button 4
Button 4 or Button 5 -> DOWN -> goto Scene1 with focus to button3
Fig 7 Emulator Scene1 with 3 buttons
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 20
Fig 8 Emulator Scene1 and Scene2 with image component in Scene2
Fig 9 Emulator Scene1 and Scene3 with popup component in Scene3
Step4: - Now add the source code for button press in Scene1
case $.sfKey.ENTER:
if (this.index == 1)
{
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 21
$.sfScene.hide('Scene3');
$.sfScene.show('Scene2');
$.sfScene.focus('Scene2');
$('#Button4').sfButton('focus');
$('#Button1').sfButton('blur');
}
else if (this.index == 2)
{
$.sfScene.hide('Scene2');
$.sfScene.show('Scene3');
$.sfScene.focus('Scene3');
$('#svecButton_HHT7').sfButton('focus');
$('#Button2').sfButton('blur');
}
else if (this.index == 3)
{
$.sfScene.show('Scene2');
$.sfScene.show('Scene3');
$.sfScene.focus('Scene2');
$('#Button4').sfButton('focus');
$('#Button3').sfButton('blur');
}
else {}
break;
}
}.
Step5: - Now add the source code for Button 4 and button5 in Scene 2 and Scene3 respectively. The
explanation is left up to the understanding purpose of the programmer to make the example
look simple. However, the source code has only basic functions calls which have been
already explained in the previous examples.
Button 4 key events in Scene2
SceneScene2.prototype.handleKeyDown = function (keyCode) {
alert("SceneScene2.handleKeyDown(" + keyCode + ")");
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 22
// TODO : write an key event handler when this scene get focued
switch (keyCode) {
case $.sfKey.LEFT:
break;
case $.sfKey.RIGHT:
var inst = $.sfScene.get('Scene1');
var temp = inst.index;
if (temp ==3)
{
$.sfScene.show('Scene3');
$.sfScene.focus('Scene3');
$('#svecButton_HHT7').sfButton('focus');
$('#Button4').sfButton('blur');
}
break;
case $.sfKey.UP:
break;
case $.sfKey.DOWN:
$('#svecImage_YPKM').sfImage({src:''});
var inst = $.sfScene.get('Scene1');
var temp = inst.index;
if (temp ==3)
{
$.sfScene.hide('Scene2');
$.sfScene.hide('Scene3');
$.sfScene.show('Scene1');
$.sfScene.focus('Scene1');
$('#Button3').sfButton('focus');
$('#Button4').sfButton('blur');
}
else{
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 23
$.sfScene.hide('Scene2');
$.sfScene.show('Scene1');
$.sfScene.focus('Scene1');
$('#Button1').sfButton('focus');
$('#Button4').sfButton('blur');
}
break;
case $.sfKey.ENTER:
$('#svecImage_YPKM').sfImage({src:'images/greeneye-whitetiger2.jpg'});
break;
}
}
The source code Button 5 key events of Scene3 are as follows.
SceneScene3.prototype.handleKeyDown = function (keyCode) {
alert("SceneScene3.handleKeyDown(" + keyCode + ")");
// TODO : write an key event handler when this scene get focued
switch (keyCode) {
case $.sfKey.LEFT:
var inst = $.sfScene.get('Scene1');
var temp = inst.index;
if (temp ==3)
{
$.sfScene.show('Scene2');
$.sfScene.focus('Scene2');
$('#Button4').sfButton('focus');
$('#svecButton_HHT7').sfButton('blur');
}
break;
case $.sfKey.RIGHT:
break;
case $.sfKey.UP:
Apps Framework API Scene Manager
@Samsung Electronics Copyright All Rights Reserved 24
break;
case $.sfKey.DOWN:
$('#svecImage_YPKM').sfImage({src:''});
var inst = $.sfScene.get('Scene1');
var temp = inst.index;
if (temp == 3)
{ $.sfScene.hide('Scene2');
$.sfScene.hide('Scene3');
$.sfScene.show('Scene1');
$.sfScene.focus('Scene1');
$('#Button3').sfButton('focus');
$('#Button4').sfButton('blur');
$('#svecButton_HHT7').sfButton('blur');
}
else{
$.sfScene.hide('Scene3');
$.sfScene.show('Scene1');
$.sfScene.focus('Scene1');
$('#Button2').sfButton('focus');
$('#svecButton_HHT7').sfButton('blur');
}
break;
case $.sfKey.ENTER:
$('#svecPopup_P3FA').sfPopup({text:'Hello, You have successfully completed Nested Scenes Tutorial', Num:'1',
callback:function(rlt){$.sfScene.get('Scene3').popupcallback(rlt)}});
$('#svecPopup_P3FA').sfPopup('show');
break;
}
}
SceneScene3.prototype.popupcallback = function (data) {
alert('SceneScene2.popupcallback() : '+data);
return;
}