© 2013 Samsung Electronics Co., Ltd. All rightsreserved.
The TV Window API lets you control functionality such as showing, hiding, and selecting an input source on a TV-associated device. This API allows you to set the display area for the TV screen and provide other relevant functions for proper handling and control of the TV window in your application.
Also, the TV Window API helps developers manage an application's TV-window-related features conveniently and efficiently. For example, it controls the TV screen window so that developers can set the source for a TV window to values such as “TV”, “PC”, and “DVI”.
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>
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); }
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 |
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); }
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); }
The TV Window API provides methods that allow you to request hiding or 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); }
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); }
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); }
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); }