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

Table of Contents


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)
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
VideoResolutionChangeCallback
void onchanged (VideoResolution resolution, WindowType type)
AvailableWindowListCallback
void onsuccess (WindowType[] type)
WindowRectangleSuccessCallback
void onsuccess (DOMString[] windowRect, WindowType type)
SourceChangedSuccessCallback

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 the video source.
  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

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. The result SystemInfoVideoSourceInfo object will have the signal property filled only when the window was shown using show() function.
  • 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 type: " + source.type +
              ", source port number: " + source.number + ", signal provided: " + source.signal);
}

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")
    {
      /* Sets HDMI as input source of the TV window. */
      tizen.tvwindow.setSource(connectedVideoSources[i], successCB, errorCB);
      break;
    }
  }
}

function systemInfoErrorCB(error)
{
  console.log("getPropertyValue(VIDEOSOURCE) 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);
}

Output example:

--------------- Source 0 ---------------
type: TV
number: 1
--------------- Source 1 ---------------
type: HDMI
number: 4
setSource() is successfully done, source type: HDMI, source port number: 4, signal provided: null
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. Returned object will have the signal property, stating whether there is signal provided or not on the source, this property value will be filled only when the window was shown using show() function.

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);
  console.log("signal: " + source.signal);
}
catch (error)
{
  console.log("Error name: " + error.name + ", error message: " + error.message);
}

Output example:

type: HDMI
number: 4
signal: null
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 name: " + error.name + ", error message: " + error.message);
}

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 name: " + error.name + ", error message: " + error.message);
}
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 name: " + error.name + ", error message: " + error.message);
}
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: 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: 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

Calling this function has no effect if there is no listener with given id.

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

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

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", "ASPECT_RATIO_UNKNOWN" };
      enum ZPosition { "FRONT", "BEHIND" };
      Tizen implements TVWindowManagerObject;
      [NoInterfaceObject] interface TVWindowManagerObject {
        readonly attribute TVWindowManager tvwindow;
      };
      [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);
      };
    };