Managing the TV Window

Prerequisites

There is a webapis.tv.window object that allows access to TV Window API functionality. The webapis.tv.window object is an instance of the WebAPIsTVWindowManager interface. This manager interface exposes the TV Window API to provide functionality such as setting and getting the source for a TV window.

Adding the webapis JavaScript file in your application is required to invoke this API properly. Please refer to the script code below to add the webapis file:

 
<html><head>
    <!-- including the JavaScript file which supports Samsung Web API -->
    <script type="text/javascript" language="javascript" src="$MANAGER_WIDGET/Common/webapi/1.0/webapis.js"></script> 
</head></html>

Get Available Window

The TV Window API provides methods that allow you to request getting the number of available subwindows.

To request getting the number of available subwindows, call the getAvailableWindow() method.
While calling this function, it is required to pass two callbacks: successCallback (called when the operation is executed successfully and list of available windows is returned), errorCallback (called when any error is encountered while getting a list of windows). ErrorCallback is optional but cannot be set as null. SuccessCallback is not optional and cannot be set as null. AvailableWindowListCallback() is the name of successCallback that handles the returned list of available windows on successful execution of the getAvailableWindow() method. This successCallback that retrieves a list of windows is used to get the number of available subwindows. The following example illustrates how to get the number of available subwindows.

 
var tvWindowObject = null;

function successCB(windows) {
     for (var i = 0; i > windows.length; i++) {
         alert("available window's ID is " + windows[i]);
     }
 }
 function errorCB(error) {
     alert(error.name);
 }
 try {
      tvWindowObject=webapis.tv.window;  
      tvWindowObject.getAvailableWindow(successCB, errorCB);
} catch (error) {
     alert(error.name);
 }

Get and Set the Source for the TV Window Screen

The TV Window API provides methods that allow you to request setting and getting the source of the TV window screen.
The following list details and describes the various types of source constants:

Interface	Constant	Description
TVWindowManager	const unsigned long SOURCE_MODE_TV = 0	Identifier that indicates the source is from TV
	const unsigned long SOURCE_MODE_AV = 1	Identifier the indicates the source is from component
	const unsigned long SOURCE_MODE_SVIDEO = 2	Identifier that indicates the source is from S-Video
	const unsigned long SOURCE_MODE_COMP = 3	Identifier that indicates the source is from composite
	const unsigned long SOURCE_MODE_PC = 4	Identifier that indicates the source is from PC
	const unsigned long SOURCE_MODE_HDMI = 5	Identifier that indicates the source is from HDMI
	const unsigned long SOURCE_MODE_SCART = 6	Identifier that indicates the source is from SCART
	const unsigned long SOURCE_MODE_DVI = 7	Identifier that indicates the source is from DVI
	const unsigned long SOURCE_MODE_MEDIA = 8	Identifier that indicates the source is from media
	const unsigned long SOURCE_MODE_IPTV = 9	Identifier that indicates the source is from IPTV

Set the source of TV window screen

The TV Window API provides methods that allow you to request setting the source of a TV window screen.

To request setting the source for a TV window screen, call the setSource() method. While calling this function, it is required to pass two callbacks, one as successCallback (called when the operation is executed with no error and the source is set to TV window successfully) and the other as errorCallback (called when the operation is not executed because of a valid error and due to which the source of the TV window is not set successfully); two other arguments, such as sourceInfo and windowID, is required to pass as an argument. The sourceInfo is an object and contains the necessary information for setting the source of the TV window in the form of source type or its respective numeric number representing the source; windowID is an optional argument but cannot be set to null. SourceChangedSuccessCallback() is a callback called after changing the window source successfully using the setSource() method. This function is used to get the changed sourceInfo and associated windowID.

The following example illustrates how to set the source of the TV window screen:

var tvWindowObject = null;
				
 function successCB() {
     alert("setting source is successful");
     }
 }

function errorCB(error) {
    alert(error.name);
 }
 
 try {
         tvWindowObject=webapis.tv.window;  

         tvWindowObject.setSource( {
             type : webapis.tv.window.SOURCE_MODE_TV, 
             number : 0 }, 
             successCB,
             errorCB);
 } catch (error) {
    alert(error.name);
 }

Getting the source of a TV window screen

The TV Window API provides methods that allow you to request getting the source of a TV window screen.

To request getting the source for the TV window screen, call the getSource() method.
While calling this function, it is optional to pass windowID as an argument, but its value cannot be set to null. On successful execution of this function, it returns the sourceInfo object describing the necessary information about the source of the TV window.

The following example illustrates how to get the source of a TV window screen:

var tvWindowObject = null;
				
function successCB(windows) {
     for (var i = 0; i < windows.length; i++) {
         var source =  tvWindowObject.getSource(windows[i]);
         switch (source.type) {
             case webapis.tv.window.SOURCE_MODE_TV : 
                 alert("window source is TV");
                 break;
                 
             case webapis.tv.window.SOURCE_MODE_AV : 
                 alert("window source is AV");
                 break;
         }
     }
 }
 
function errorCB(error) {
     alert(error.name);
 }
 
 try {
      tvWindowObject.getAvailableWindow(successCB, errorCB);
     catch (error) {
         alert(error.name);
}

Show or Hide the TV Window Screen

The TV Window API provides methods that allow you to request hiding or showing the TV window screen.

Showing the TV window screen

The TV Window API provides methods that allow you to request showing the TV window screen.

To request showing the TV window screen, call the Show() method. While calling this function, it is optional to pass windowID as an argument, but its value cannot be set to null if used as an argument. On successful execution of this function, it returns true when the TV window screen is shown; otherwise, it returns false if there is an error. In this case, the required action is not performed.

The following example illustrates how to show the TV window screen:

var tvWindowObject = null;

function successCB(windows) {
     for (var i = 0; i < windows.length; i++) {
         if (i == 0) {
            if ( tvWindowObject.show(windows[i])) { 
                alert("window #0 is shown"); 
            }
     }
 }

 function errorCB(error) {
     alert(error.name);
 }
 
 try {
      tvWindowObject=webapis.tv.window;
      tvWindowObject.getAvailableWindow(successCB, errorCB);
 } catch (error) {
     alert(error.name);
 }

Hiding the TV window screen

The TV Window API provides methods that allow you to request hiding the TV window screen.

To request hiding the TV window screen, call the hide() method. While calling this function, it is optional to pass windowID as an argument, but its value cannot be set to null if used as an argument. On successful execution of this function, it returns true when the TV window screen hides; otherwise, it returns false if there is an error, and the required action is not performed.

The following example illustrates how to hide the TV window screen:

var tvWindowObject = null;
			
function successCB(windows) {
     for (var i = 0; i < windows.length; i++) {
         if (i == 0) {
            if (tvWindowObject.hide(windows[i])) { 
                alert("window #0 is hidden"); 
            }
     }
}
 
function errorCB(error) {
     console.log(error.name);
} 

try {
    tvWindowObject=webapis.tv.window;
    tvWindowObject.getAvailableWindow(successCB, errorCB);
} cath (error) {
    alert(error.name);
}

Set the Display Area of the TV Window Screen

The TV window API provides methods that allow you to request setting the display area of the TV window screen.

To request setting the display area from video in the TV window screen, call the setRect() method. While calling this function, it is required to pass the object containing the dimension of the display area in terms of “width”, ”height”, ”top”, ”left”; it is optional to pass windowID as an argument, but it’s value cannot be set to null if used as an argument.
On successful execution of this function, it returns true when the TV window screen display area ID is set; otherwise, it returns false if there is an error, and the required action is not performed.

The following example illustrates how to set the display area of the TV window screen:

var tvWindowObject = null;
			
var displayArea = {
     width : 320,
     height : 240,
     top : 0,
     left : 0
 };
 
function successCB(windows) {
     for (var i = 0; i < windows.length; i++) {
         if (i == 0) {
            if (tvWindowObject.setRect(displayArea, windows[i])) {
                alert("window #0's display area is changed");
            }
         }
     }
 };
 
function errorCB(error) {
     console.log(error.name);
 } 

try {
    tvWindowObject=webapis.tv.window;
    tvWindowObject.getAvailableWindow(successCB, errorCB); 
       
} catch (error) {
    alert(error.name);
}

Obtain Source Information

On execution of the getSource() function, sourceInfo is returned.

This sourceInfo returned is an object containing information about the source of the TV window screen. It describes the source type of the TV window screen as well as its respective numeric value. It specifies the options for source information. Its structure is as follows:

dictionary SourceInfo {
        unsigned short type;

        unsigned long number;
    };

The following example illustrates how to get the sourceInfo object:

function successCB(windows) {
     for (var i = 0; i < windows.length; i++) {
         var source = webapis.tv.window.getSource(windows[i]);
         switch (source.type) {
             case webapis.tv.window.SOURCE_MODE_TV : 
                 console.log("window source is TV");
                 break;
             case webapis.tv.window.SOURCE_MODE_AV : 
                 console.log("window source is AV");
                 break;
         }
     }
 }

 function errorCB(error) {
     console.log(error.name);
 }
 
 try {
     webapis.tv.window.getAvailableWindow(successCB, errorCB);
     catch (error) {
         console.log(error.name);
 }