This API provides a way to embed a video source in a Tizen Web Application running on a device associated with the TV. It allows an available video source to be selected and shown on or hidden from the display in a Tizen Web Application. There will be a tizen.tvwindow object that allows access to the functionality of the TV Window API. To show a TV signal, execute the show function. A TV source is controlled by the user or by you with Tizen Web Device APIs. You do not have to implement any routines if you do not want to interact with the TV image.
Since: 2.3
Table of Contents
- 1. Type Definitions
- 1.1. WindowType
- 1.2. MeasurementUnit
- 1.3. AspectRatio
- 1.4. ZPosition
- 2. Interfaces
- 3. Related Feature
- 4. Full WebIDL
Summary of Interfaces and Methods
Code example:
- - - - - ------------------------ | | | +---------+ | | |TV window| | | +---------+ | | | | YOUR APPLICATION | | | | | ------------------------
1 Type Definitions
1.1 WindowType
enum WindowType { "MAIN", };
Since: 2.3
- MAIN - The main video window, which can be show anywhere
1.2 MeasurementUnit
enum MeasurementUnit { "px", "%" };
Since: 2.3
- px - pixel unit
- % - percentage unit for specifying relative size
1.3 AspectRatio
enum AspectRatio{ "ASPECT_RATIO_1x1", "ASPECT_RATIO_4x3", "ASPECT_RATIO_16x9", "ASPECT_RATIO_221x100", "ASPECT_RATIO_UNKNOWN" };
Since: 2.4
- ASPECT_RATIO_1x1 - 1:1
- ASPECT_RATIO_4x3 - 4:3
- ASPECT_RATIO_16x9 - 16:9
- ASPECT_RATIO_221x100 - 2.21:1
- ASPECT_RATIO_UNKNOWN - Unknown aspect ratio
Remark : ASPECT_RATIO_UNKNOWN is supported since Tizen 3.0
1.4 ZPosition
enum ZPosition{ "FRONT", "BEHIND" };
Since: 2.4
- FRONT - Displays the TV window in front of the Web Application
- BEHIND - Displays the TV window behind the Web Application
2 Interfaces
2.1 TVWindowManagerObject
[NoInterfaceObject] interface TVWindowManagerObject { readonly attribute TVWindowManager tvwindow; };
Tizen implements TVWindowManagerObject;
Since: 2.3
There will be a tizen.tvwindow object that allows access to the functionality of the TV Window API.
2.2 TVWindowManager
[NoInterfaceObject] interface TVWindowManager { void getAvailableWindows(AvailableWindowListCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void setSource(SystemInfoVideoSourceInfo videoSource, SourceChangedSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional WindowType? type) raises (WebAPIException); SystemInfoVideoSourceInfo getSource(optional WindowType? type) raises(WebAPIException); void show(WindowRectangleSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional DOMString[]? rectangle, optional WindowType? type, optional ZPosition? zPosition) raises(WebAPIException); void hide(SuccessCallback successCallback, optional ErrorCallback? errorCallback, optional WindowType? type) raises(WebAPIException); void getRect(WindowRectangleSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional MeasurementUnit? unit, optional WindowType? type) raises(WebAPIException); VideoResolution getVideoResolution(optional WindowType? type) raises(WebAPIException); long addVideoResolutionChangeListener(VideoResolutionChangeCallback callback, optional WindowType? type) raises(WebAPIException); void removeVideoResolutionChangeListener(long listenerId) raises(WebAPIException); };
Since: 2.3
Methods
getAvailableWindows
-
Gets the list of available windows.
void getAvailableWindows(AvailableWindowListCallback successCallback, optional ErrorCallback? errorCallback);
Since: 2.3
Privilege level: public
Privilege: http://tizen.org/privilege/tv.window
Parameters:
- successCallback: The method to invoke when a list of the available windows is retrieved successfully
- errorCallback [optional] [nullable]: The method to invoke when an error occurs
Exceptions:
- WebAPIException
-
with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.
-
with error type SecurityError, if the application does not have the privilege to call this method.
-
Code example:
function successCB(availableWindows) { for (var i = 0; i < availableWindows.length; i++) { console.log("Window ["+ i + "] = " + availableWindows[i]); } } try { tizen.tvwindow.getAvailableWindows(successCB); } catch (error) { console.log("Error name = "+ error.name + ", Error message = " + error.message); }
setSource
-
Changes the source of a TV window.
void setSource(SystemInfoVideoSourceInfo videoSource, SourceChangedSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional WindowType? type);
Since: 2.3
Privilege level: public
Privilege: http://tizen.org/privilege/tv.window
Parameters:
- videoSource: The video source to set
The possible video sources can be obtained through tizen.systeminfo.getPropertyValue("VIDEOSOURCE"). - successCallback: The method to invoke when the intput source has been changed successfully
- errorCallback [optional] [nullable]: The method to invoke when an error occurs
- type [optional] [nullable]: The window type - by default, this attribute is set to MAIN
Exceptions:
- WebAPIException
-
with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.
-
with error type SecurityError, if the application does not have the privilege to call this method.
-
with error type UnknownError if any other error occurs.
-
Code example:
var connectedVideoSources; function successCB(source, type) { console.log("setSource() is successfully done. source name = " + source.name + ", source port number = " + source.number); } function errorCB(error) { console.log("setSource() is failed. Error name = "+ error.name + ", Error message = " + error.message); } function systemInfoSuccessCB(videoSource) { connectedVideoSources = videoSource.connected; for (var i = 0; i < connectedVideoSources.length; i++) { console.log("--------------- Source " + i + " ---------------"); console.log("type = " + connectedVideoSources[i].type); console.log("number = " + connectedVideoSources[i].number); if (connectedVideoSources[i].type === "HDMI") { // set HDMI as input source of the TV window tizen.tvwindow.setSource(connectedVideoSources[i], successCB, errorCB); break; } } } function systemInfoErrorCB(error) { console.log("getPropertyValue(VIDEOSOURCE) is failed. Error name = "+ error.name + ", Error message = " + error.message); } try { tizen.systeminfo.getPropertyValue("VIDEOSOURCE", systemInfoSuccessCB, systemInfoErrorCB); } catch (error) { console.log("Error name = "+ error.name + ", Error message = " + error.message); }
- videoSource: The video source to set
getSource
-
Gets information about the current source of a specified TV window.
SystemInfoVideoSourceInfo getSource(optional WindowType? type);
Since: 2.3
Privilege level: public
Privilege: http://tizen.org/privilege/tv.window
Parameters:
- type [optional] [nullable]: The window type - by default, this attribute is set to MAIN
Return value:
SystemInfoVideoSourceInfo The information about the current video source
Exceptions:
- WebAPIException
-
with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.
-
with error type SecurityError, if the application does not have the privilege to call this method.
-
with error type UnknownError if any other error occurs.
-
Code example:
try { var source = tizen.tvwindow.getSource(); console.log("type = " + source.type); console.log("number = " + source.number); } catch (error) { console.log("Error name = "+ error.name + ", Error message = " + error.message); }
show
-
Sets the display area of a TV window and shows it on the display.
void show(WindowRectangleSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional DOMString[]? rectangle, optional WindowType? type, optional ZPosition? zPosition);
Since: 2.3
The rectangle array requires exactly four elements which are described below:
- The first element indicates the x coordinate of the top left corner of the TV window (distance from the left edge of the screen).
- The second element indicates the y coordinate of the top left corner of the TV window (distance from the top edge of the screen).
- The third element indicates the width of the TV window.
- The fourth element indicates the height of the TV window.
Each element of rectangle can be described in either absolute value by using pixel units "px" or relative value by using percentage units "%". If you do not specify any unit after a value then it will be taken as an absolute value.
The errorCallback is invoked with these error types:
- InvalidValuesError will be thrown if rectangle has any element with invalid format (e.g. "10p") or it does not have 4 elements.
- NotSupportedError will be thrown if you set rectangle which is not within the boundary of the display area or when the TV window is not supported in the current screen orientation.
- TypeMismatchError will be thrown if rectangle is not an array.
Privilege level: public
Privilege: http://tizen.org/privilege/tv.window
Parameters:
- successCallback: The method which will be invoked when the position and size of the TV window has been changed successfully
- errorCallback [optional] [nullable]: The method which will be invoked when an error occurs
- rectangle [optional] [nullable]: An array that contains information about the position and size of a specified TV window as a string with units
Without this parameter, the TV window will have the same size and location as when this method last suceeded.
But, if a rectangle has never been specified, the TV window will be shown in full screen mode. - type [optional] [nullable]: The window type - by default, this attribute is set to MAIN
- zPosition [optional] [nullable]: Specifies whether the TV window should be in front of or behind the Web Application since Tizen 2.4
By default, this parameter is set to FRONT.
If this parameter is set to null or FRONT, this method behaves in the same way as it did before Tizen 2.4.
Exceptions:
- WebAPIException
-
with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.
-
with error type InvalidValuesError, if any of the input parameters contain an invalid value.
-
with error type SecurityError, if the application does not have the privilege to call this method.
-
with error type UnknownError if any other error occurs.
-
Code example:
function successCB(windowRect, type) { // You will get exactly what you put as rectangle argument of show() through windowRect. // expected result : ["0", "0px", "50%", "540px"] console.log("Rectangle : [" + windowRect[0] + ", " + windowRect[1] + ", " + windowRect[2] + ", " + windowRect[3] + "]"); } try { tizen.tvwindow.show(successCB, null, ["0", "0px", "50%", "540px"], "MAIN"); } catch(error) { console.log("error: " + error.name); }
Code example:
function successCB(windowRect, type) { // expected result : ["0", "0", "50%", "50%"] console.log("Rectangle : [" + windowRect[0] + ", " + windowRect[1] + ", " + windowRect[2] + ", " + windowRect[3] + "]"); } try { tizen.tvwindow.show(successCB, null, ["0", "0", "50%", "50%"], "MAIN"); } catch(error) { console.log("error: " + error.name); }
Code example:
function successCB(windowRect, type) { // expected result : ["10.5%", "10%", "900", "500px"] console.log("Rectangle : [" + windowRect[0] + ", " + windowRect[1] + ", " + windowRect[2] + ", " + windowRect[3] + "]"); } try { tizen.tvwindow.show(successCB, null, ["10.5%", "10%", "900", "500px"]); } catch(error) { console.log("error: " + error.name); }
hide
-
Hides a TV window which is shown.
void hide(SuccessCallback successCallback, optional ErrorCallback? errorCallback, optional WindowType? type);
Since: 2.3
Privilege level: public
Privilege: http://tizen.org/privilege/tv.window
Parameters:
- successCallback: The method to invoke when the window is hidden successfully
- errorCallback [optional] [nullable]: The method to invoke when an error occurs
- type [optional] [nullable]: The window type - by default, this attribute is set to MAIN
Exceptions:
- WebAPIException
-
with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.
-
with error type SecurityError, if the application does not have the privilege to call this method.
-
with error type UnknownError if any other error occurs.
-
getRect
-
Gets the area information of a TV window which is shown.
void getRect(WindowRectangleSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional MeasurementUnit? unit, optional WindowType? type);
Since: 2.3
According to the specified unit, information about the area will be passed to an array that contains 4 strings through WindowRectangleSuccessCallback as follows :
- If you set "px" as unit, ["0px", "0px", "1920px", "1080px"]
- If you set "%" as unit, ["0%", "0%", "100%", "100%"]
If you omit unit, the pixel("px") unit will be used as a default unit.
Privilege level: public
Privilege: http://tizen.org/privilege/tv.window
Parameters:
- successCallback: The method to invoke when the position and size of the TV window has been obtained successfully
- errorCallback [optional] [nullable]: The method to invoke when an error occurs
- unit [optional] [nullable]: The measurement unit for specifying the display area - by default, this attribute is set to "px"
- type [optional] [nullable]: The window type - by default, this attribute is set to MAIN
Exceptions:
- WebAPIException
-
with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.
-
with error type SecurityError, if the application does not have the privilege to call this method.
-
with error type UnknownError if any other error occurs.
-
Code example:
function rectangleCB(windowRect, type) { // You call getRect() without specifying a unit, it expresses the area information with pixel unit. // expected result : ["0px", "0px", "960px", "540px"] if the screen resolution of a device is 1920 x 1080. console.log("Rectangle : [" + windowRect[0] + ", " + windowRect[1] + ", " + windowRect[2] + ", " + windowRect[3] + "]"); } function successCB(windowRect, type) { // You will get exactly what you put as rectangle argument through windowRect. // expected result : ["0", "0", "50%", "50%"] console.log("Rectangle : [" + windowRect[0] + ", " + windowRect[1] + ", " + windowRect[2] + ", " + windowRect[3] + "]"); tizen.tvwindow.getRect(rectangleCB); } try { tizen.tvwindow.show(successCB, null, ["0", "0", "50%", "50%"]); } catch(error) { console.log("error: " + error.name); }
getVideoResolution
-
Gets video resolution information.
VideoResolution getVideoResolution(optional WindowType? type);
Since: 2.4
Privilege level: public
Privilege: http://tizen.org/privilege/tv.window
Parameters:
- type [optional] [nullable]: The window type - by default, this attribute is set to MAIN
Return value:
VideoResolution current video resolution information
Exceptions:
- WebAPIException
-
with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.
-
with error type SecurityError, if the application does not have the privilege to call this method.
-
with error type UnknownError if any other error occurs.
-
Code example:
var res = tizen.tvwindow.getVideoResolution(); console.log("Video resolution: " + res.width + "x" + res.height + " pixels"); console.log("Frequency: " + res.frequency +"Hz"); if (res.aspectRatio === "ASPECT_RATIO_16x9") { console.log("Widescreen on"); }
addVideoResolutionChangeListener
-
Adds a video resolution listener for getting notified about resolution changes.
long addVideoResolutionChangeListener(VideoResolutionChangeCallback callback, optional WindowType? type);
Since: 2.4
Privilege level: public
Privilege: http://tizen.org/privilege/tv.window
Parameters:
- callback: The method to invoke when the resolution has been changed
- type [optional] [nullable]: The window type. By default, this parameter is set to MAIN
Return value:
long The identifier of the resolution change listener.
Exceptions:
- WebAPIException
-
with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.
-
with error type SecurityError, if the application does not have the privilege to call this method.
-
with error type UnknownError, if it fails to register a listener.
-
Code example:
function change(res, type) { console.log("Switched to new resolution: " + res.width + "x" + res.height); console.log("New frequency: " + res.frequency); if (res.aspectRatio === "ASPECT_RATIO_16x9") { console.log("Widescreen is now turned on"); } } try { var watch = tizen.tvwindow.addVideoResolutionChangeListener(change); } catch (error) { console.log("Error name = "+ error.name + ", Error message = " + error.message); }
removeVideoResolutionChangeListener
-
Removes the listener to stop receiving notifications for the video resolution changes.
void removeVideoResolutionChangeListener(long listenerId);
Since: 2.4
Privilege level: public
Privilege: http://tizen.org/privilege/tv.window
Parameters:
- listenerId: The identifier of the listener for resolution changes
Exceptions:
- WebAPIException
-
with error type SecurityError, if the application does not have the privilege to call this method.
-
with error type UnknownError in any other error case.
-
2.3 VideoResolution
[NoInterfaceObject] interface VideoResolution { readonly attribute long width; readonly attribute long height; readonly attribute long frequency; readonly attribute AspectRatio aspectRatio; };
Since: 2.4
Attributes
- readonly long width
Video width in pixels.
Since: 2.4
- readonly long height
Video height in pixels.Since: 2.4
- readonly long frequency
Vertical frequency rate in Hz.Since: 2.4
- readonly AspectRatio aspectRatio
Video aspect ratio.Since: 2.4
2.4 VideoResolutionChangeCallback
[Callback = FunctionOnly, NoInterfaceObject] interface VideoResolutionChangeCallback { void onchanged(VideoResolution resolution, WindowType type); };
Since: 2.4
Methods
onchanged
-
Method invoked when the video resolution has been changed.
void onchanged(VideoResolution resolution, WindowType type);
Since: 2.4
Parameters:
- resolution: The resolution that the video has changed to
- type: The window type
2.5 AvailableWindowListCallback
[Callback = FunctionOnly, NoInterfaceObject] interface AvailableWindowListCallback { void onsuccess(WindowType[] type); };
Since: 2.3
Methods
onsuccess
-
Method invoked when a list of available windows is retrieved.
void onsuccess(WindowType[] type);
Since: 2.3
Parameters:
- type: The available window types
2.6 WindowRectangleSuccessCallback
[Callback = FunctionOnly, NoInterfaceObject] interface WindowRectangleSuccessCallback { void onsuccess(DOMString[] windowRect, WindowType type); };
Since: 2.3
Methods
onsuccess
-
Method invoked when the position and size of the TV window has been changed or retrieved.
void onsuccess(DOMString[] windowRect, WindowType type);
Since: 2.3
This method returns information windowRect and type. For more detailed information about windowRect, see the description of show().
Parameters:
- windowRect: An array that contains information about the position and size of a specified TV window as a string with units
- type: The window type
2.7 SourceChangedSuccessCallback
[Callback = FunctionOnly, NoInterfaceObject] interface SourceChangedSuccessCallback { void onsuccess(SystemInfoVideoSourceInfo source, WindowType type); };
Since: 2.3
Methods
onsuccess
-
Method invoked when the new source has been set.
void onsuccess(SystemInfoVideoSourceInfo source, WindowType type);
Since: 2.3
This method returns information source and type.
Parameters:
- source: A descriptor object SystemInfoVideoSourceInfo that contains information about the source used by TV
- type: The window type
3 Related Feature
To guarantee the running of this application on a device with a TV picture-in-picture support, define the following requirements in the config file:
For more information, see Application Filtering.
4 Full WebIDL
module TVWindow { enum WindowType { "MAIN", }; enum MeasurementUnit { "px", "%" }; enum AspectRatio{ "ASPECT_RATIO_1x1", "ASPECT_RATIO_4x3", "ASPECT_RATIO_16x9", "ASPECT_RATIO_221x100", "ASPECT_RATIO_UNKNOWN" }; enum ZPosition{ "FRONT", "BEHIND" }; [NoInterfaceObject] interface TVWindowManagerObject { readonly attribute TVWindowManager tvwindow; }; Tizen implements TVWindowManagerObject; [NoInterfaceObject] interface TVWindowManager { void getAvailableWindows(AvailableWindowListCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void setSource(SystemInfoVideoSourceInfo videoSource, SourceChangedSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional WindowType? type) raises (WebAPIException); SystemInfoVideoSourceInfo getSource(optional WindowType? type) raises(WebAPIException); void show(WindowRectangleSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional DOMString[]? rectangle, optional WindowType? type, optional ZPosition? zPosition) raises(WebAPIException); void hide(SuccessCallback successCallback, optional ErrorCallback? errorCallback, optional WindowType? type) raises(WebAPIException); void getRect(WindowRectangleSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional MeasurementUnit? unit, optional WindowType? type) raises(WebAPIException); VideoResolution getVideoResolution(optional WindowType? type) raises(WebAPIException); long addVideoResolutionChangeListener(VideoResolutionChangeCallback callback, optional WindowType? type) raises(WebAPIException); void removeVideoResolutionChangeListener(long listenerId) raises(WebAPIException); }; [NoInterfaceObject] interface VideoResolution { readonly attribute long width; readonly attribute long height; readonly attribute long frequency; readonly attribute AspectRatio aspectRatio; }; [Callback = FunctionOnly, NoInterfaceObject] interface VideoResolutionChangeCallback { void onchanged(VideoResolution resolution, WindowType type); }; [Callback = FunctionOnly, NoInterfaceObject] interface AvailableWindowListCallback { void onsuccess(WindowType[] type); }; [Callback = FunctionOnly, NoInterfaceObject] interface WindowRectangleSuccessCallback { void onsuccess(DOMString[] windowRect, WindowType type); }; [Callback = FunctionOnly, NoInterfaceObject] interface SourceChangedSuccessCallback { void onsuccess(SystemInfoVideoSourceInfo source, WindowType type); }; };