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 the 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
Code example:
- - - - - ------------------------ | | | +---------+ | | |TV window| | | +---------+ | | | | YOUR APPLICATION | | | | | ------------------------
An enumerator to indicate the window type.
enum WindowType { "MAIN", };
An enumerator to indicate the units of measurement for specifying the measurement unit when calling getRect().
enum MeasurementUnit { "px", "%" };
An enumerator to indicate the aspect ratio of video source.
enum AspectRatio{ "ASPECT_RATIO_1x1", "ASPECT_RATIO_4x3", "ASPECT_RATIO_16x9", "ASPECT_RATIO_221x100" };
Since: 2.4
An enumerator to indicate the z position of the TV window or the relative position of the TV window and the Web Application.
enum ZPosition{ "FRONT", "BEHIND" };
This interface defines what is instantiated by the tizen object.
[NoInterfaceObject] interface TVWindowManagerObject { readonly attribute TVWindowManager tvwindow; };
Tizen implements TVWindowManagerObject;
There will be a tizen.tvwindow object that allows access to the functionality of the TV Window API.
This interface provides access to the API funtionalities through the tizen.tvwindow interface.
[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); };
getAvailableWindows
Gets the list of available windows.
void getAvailableWindows(AvailableWindowListCallback successCallback, optional ErrorCallback? errorCallback);
Privilege level: public
Privilege: http://tizen.org/privilege/tv.window
Parameters:
Exceptions:
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);
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); }
getSource
Gets information about the current source of a specified TV window.
SystemInfoVideoSourceInfo getSource(optional WindowType? type);
Return value: SystemInfoVideoSourceInfo The information about the current video source
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);
The rectangle array requires exactly four elements which are described below:
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:
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); }
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); }
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);
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);
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 omit unit, the pixel("px") unit will be used as a default unit.
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);
Return value: VideoResolution current video resolution information
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);
Return value: long The identifier of the resolution change listener.
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);
The VideoResolution interface contains information about current video resolution.
[NoInterfaceObject] interface VideoResolution { readonly attribute long width; readonly attribute long height; readonly attribute long frequency; readonly attribute AspectRatio aspectRatio; };
This interface defines a video resolution change callback for getting notified about video resolution changes.
[Callback = FunctionOnly, NoInterfaceObject] interface VideoResolutionChangeCallback { void onchanged(VideoResolution resolution, WindowType type); };
onchanged
Method invoked when the video resolution has been changed.
void onchanged(VideoResolution resolution, WindowType type);
This interface defines a callback that is invoked when a list of available windows is retrieved successfully.
[Callback = FunctionOnly, NoInterfaceObject] interface AvailableWindowListCallback { void onsuccess(WindowType[] type); };
onsuccess
Method invoked when a list of available windows is retrieved.
void onsuccess(WindowType[] type);
This interface includes the success callback that is invoked when the position and size of a TV window has been changed or retrieved.
[Callback = FunctionOnly, NoInterfaceObject] interface WindowRectangleSuccessCallback { void onsuccess(DOMString[] windowRect, WindowType type); };
Method invoked when the position and size of the TV window has been changed or retrieved.
void onsuccess(DOMString[] windowRect, WindowType type);
This method returns information windowRect and type. For more detailed information about windowRect, see the description of show().
This interface includes the success callback that is invoked when the source has been set.
[Callback = FunctionOnly, NoInterfaceObject] interface SourceChangedSuccessCallback { void onsuccess(SystemInfoVideoSourceInfo source, WindowType type); };
Method invoked when the new source has been set.
void onsuccess(SystemInfoVideoSourceInfo source, WindowType type);
This method returns information source and type.
You can check if this API is supported with tizen.systeminfo.getCapability() and decide enable/disable codes that need this API.
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.
module TVWindow { enum WindowType { "MAIN", }; enum MeasurementUnit { "px", "%" }; enum AspectRatio{ "ASPECT_RATIO_1x1", "ASPECT_RATIO_4x3", "ASPECT_RATIO_16x9", "ASPECT_RATIO_221x100" }; 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); }; };