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


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



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.



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.



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.



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;

}



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;



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.



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’)


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()



1.2.4. Get()

Syntax $.sfScene.get (‘SceneID’)


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.





// 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:




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.



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



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



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.



var test1= $.sfScene.get('Scene1');



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.



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





this.index = 1;

}






$('#Button1').sfButton({text:'Scene2', width:'200px'});

$('#Button2').sfButton({text:'Scene3', width:'200px'});

$('#Button3').sfButton({text:'Scene2 and 3', width:'200px'});

$('#Button1').sfButton('focus');

}



// 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');



}

else if (this.index ==2)

{

this.index = 1;




}


{



this.index = 2;




}

else{}

break;

case $.sfKey.RIGHT:

if (this.index ==1)

{

this.index = 2;




}

else if (this.index == 2)

{

this.index = 3;




}


{

this.index = 1;




}

else{}

break;

Step3:- When code for navigation is done, decide on which scene/component is assigned to which



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



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)

{








}


{




$('#svecButton_HHT7').sfButton('focus');


}


{






}

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






switch (keyCode) {

case $.sfKey.LEFT:

break;

case $.sfKey.RIGHT:

var inst = $.sfScene.get('Scene1');

var temp = inst.index;

if (temp ==3)

{



$('#svecButton_HHT7').sfButton('focus');


}

break;

case $.sfKey.UP:

break;

case $.sfKey.DOWN:

$('#svecImage_YPKM').sfImage({src:''});



if (temp ==3)

{







}

else{








}

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.




switch (keyCode) {

case $.sfKey.LEFT:



if (temp ==3)

{




$('#svecButton_HHT7').sfButton('blur');

}

break;

case $.sfKey.RIGHT:

break;

case $.sfKey.UP:



break;

case $.sfKey.DOWN:

$('#svecImage_YPKM').sfImage({src:''});



if (temp == 3)

{ $.sfScene.hide('Scene2');







}

else{






}

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;

}



Fig 10 Emulator Scene1, Scene2 and Scene3 with popup component in Scene3 and Image Component in Scene2

This ends the example of Scene Manager. You are now set to experiment it yourself.

apps framework scene manager api[v1.10]

Documents