TVWindow API

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

Summary of Interfaces and Methods

Interface	Method
TVWindowManagerObject
TVWindowManager	void getAvailableWindows (AvailableWindowListCallback successCallback, optional ErrorCallback? errorCallback) void setSource (SystemInfoVideoSourceInfo videoSource, SourceChangedSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional WindowType? type) SystemInfoVideoSourceInfo getSource (optional WindowType? type) void show (WindowRectangleSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional DOMString[]? rectangle, optional WindowType? type, optional ZPosition? zPosition) void hide (SuccessCallback successCallback, optional ErrorCallback? errorCallback, optional WindowType? type) void getRect (WindowRectangleSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional MeasurementUnit? unit, optional WindowType? type) VideoResolution getVideoResolution (optional WindowType? type) long addVideoResolutionChangeListener (VideoResolutionChangeCallback callback, optional WindowType? type) void removeVideoResolutionChangeListener (long listenerId)
VideoResolution
VideoResolutionChangeCallback	void onchanged (VideoResolution resolution, WindowType type)
AvailableWindowListCallback	void onsuccess (WindowType[] type)
WindowRectangleSuccessCallback	void onsuccess (DOMString[] windowRect, WindowType type)
SourceChangedSuccessCallback	void onsuccess (SystemInfoVideoSourceInfo source, WindowType type)

Code example:

          -         -
             -    -
               -
    ------------------------
    |                      |
    |         +---------+  |
    |         |TV window|  |
    |         +---------+  |
    |                      |
    |   YOUR APPLICATION   |
    |                      |
    |                      |
    ------------------------

1. Type Definitions

1.1. WindowType

An enumerator to indicate the window type.

enum WindowType {
    "MAIN",
};

Since: 2.3

• MAIN - The main video window, which can be show anywhere

1.2. MeasurementUnit

An enumerator to indicate the units of measurement for specifying the measurement unit when calling getRect().

enum MeasurementUnit {
    "px",
    "%"
};

Since: 2.3

• px - pixel unit
• % - percentage unit for specifying relative size

1.3. AspectRatio

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

• ASPECT_RATIO_1x1 - 1:1
• ASPECT_RATIO_4x3 - 4:3
• ASPECT_RATIO_16x9 - 16:9
• ASPECT_RATIO_221x100 - 2.21:1

1.4. ZPosition

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"
};

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

This interface defines what is instantiated by the tizen object.

[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

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);
};

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);
}

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

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;
};

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

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);
};

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

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);
};

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

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);
};

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

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);
};

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

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:

• http://tizen.org/feature/tv.pip

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"
  };

  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);
  };

};