Samsung Electronics logo

Samsung Web API: Window

© 2013 Samsung Electronics Co., Ltd. All rights reserved.

Introduction

This API provides screen control functionality such as showing/hiding and selecting an input source for the device associated with the TV.

A webapis.tv.window object that provides access to the functionality of the window API.

For more information on the TV Window features, see TV Window Guide.

Table of Contents

Summary of Interfaces and Methods

Interface Method
WebAPIsTVWindowManager
TVWindowManager void getAvailableWindow(AvailableWindowListCallback successCallback, ErrorCallback errorCallback)
void setSource(SourceInfo sourceInfo, SourceChangedSuccessCallback sourceChangedSuccessCallback, ErrorCallback? errorCallback, unsigned short windowID)
SourceInfo getSource(unsigned short windowID)
boolean setRect(SRect rect, unsigned short windowID)
boolean show(unsigned short windowID)
boolean hide(unsigned short windowID)
SourceInfo
AvailableWindowListCallback void onsuccess(UnsignedShortArray windowArray)
SourceChangedSuccessCallback void onsuccess(SourceInfo info, unsigned short windowID)

1. Interfaces

1.1. WebAPIsTVWindowManager

The TV Window module supports control of source relative functions of the Smart TV platform. 

    [NoInterfaceObject] interface WebAPIsTVWindowManager {
        readonly attribute TVWindowManager window;
    };
    TV implements WebAPIsTVWindowManager;

There is a webapis.tv.window object that allows access to TV Window API functionality.

1.2. TVWindowManager

Defines what is instantiated in the tv object. 

    [NoInterfaceObject] interface TVWindowManager {  

        const unsigned long SOURCE_MODE_TV = 0;

        const unsigned long SOURCE_MODE_AV = 1;

        const unsigned long SOURCE_MODE_SVIDEO  = 2;

        const unsigned long SOURCE_MODE_COMP = 3;

        const unsigned long SOURCE_MODE_PC = 4;

        const unsigned long SOURCE_MODE_HDMI = 5;

        const unsigned long SOURCE_MODE_SCART= 6;

        const unsigned long SOURCE_MODE_DVI = 7;

        const unsigned long SOURCE_MODE_MEDIA = 8;

        const unsigned long SOURCE_MODE_IPTV = 9;
               
        void getAvailableWindow(AvailableWindowListCallback successCallback,  
                                       optional ErrorCallback errorCallback);
                
        void setSource(SourceInfo sourceInfo, 
                          SourceChangedSuccessCallback sourceChangedSuccessCallback,  
                          optional ErrorCallback? errorCallback,  
                          optional unsigned short windowID);
 
        SourceInfo getSource(optional unsigned short windowID);      
                              
        boolean setRect(SRect rect, optional unsigned short windowID);
                        
        boolean show(optional unsigned short windowID);
        
        boolean hide(optional unsigned short windowID);       

    };

A webapis.tv.window object that provides access to the functionality of the window module.

CONSTANTS

unsigned long SOURCE_MODE_TV

This identifier indicates the source is from TV.

unsigned long SOURCE_MODE_AV

This identifier indicates the source is from component.

unsigned long SOURCE_MODE_SVIDEO

This identifier indicates the source is from S-Video.

unsigned long SOURCE_MODE_COMP

This identifier indicates the source is from composite.

unsigned long SOURCE_MODE_PC

This identifier indicates the source is from PC.

unsigned long SOURCE_MODE_HDMI

This identifier indicates the source is from HDMI.

unsigned long SOURCE_MODE_SCART

This identifier indicates the source is from SCART.

unsigned long SOURCE_MODE_DVI

This identifier indicates the source is from DVI.

unsigned long SOURCE_MODE_MEDIA

This identifier indicates the source is from media.

unsigned long SOURCE_MODE_IPTV

This identifier indicates the source is from IPTV.

METHODS

getAvailableWindow

Gets the number of available sub-window.

Signature
void getAvailableWindow(AvailableWindowListCallback successCallback, optional ErrorCallback errorCallback);

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If the input attributes do not contain valid values
  • UnknownError: In the case of any other error

If the errorCallback does not contain a valid function (such as null) or in the case of any other error that should be returned in the errorCallback (see above), the implementation MUST silently fail and no further action is required (that is the developer is not notified of the error).

Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: AvailableWindowListCallback.
    • Description: To be invoked if the operation is completed successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: No.
    • Type: ErrorCallback.
    • Description: To be invoked when an error occurs.
Exceptions
  • WebAPIException:

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type TypeMismatchError if any of the input attributes are of the wrong type

Code example
 function successCB(windows) {
     for (var i = 0; i  windows.length; i++) {
         console.log("available window's ID is " + windows[i]);
     }
 }

 function errorCB(error) {
     console.log(error.name);
 }
 try {
     webapis.tv.window.getAvailableWindow(successCB, errorCB);
 catch (error) {
     console.log(error.name);
 }

setSource

Changes the tv source. (TV or PC or DVI ...)

Signature
void setSource(SourceInfo sourceInfo, SourceChangedSuccessCallback sourceChangedSuccessCallback, optional ErrorCallback? errorCallback, optional unsigned short windowID);

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If the input attributes do not contain valid values
  • UnknownError: In the case of any other error

If the errorCallback does not contain a valid function (such as null) or in the case of any other error that should be returned in the errorCallback (see above), the implementation MUST silently fail and no further action is required (that is the developer is not notified of the error).

Parameters
  • sourceInfo
    • Optional: No.
    • Nullable: No.
    • Type: SourceInfo.
    • Description: source information
  • sourceChangedSuccessCallback
    • Optional: No.
    • Nullable: No.
    • Type: SourceChangedSuccessCallback.
    • Description: To be invoked if the operation is completed successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: To be invoked when an error occurs.
  • windowID
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned short.
    • Description: window This identifier
Exceptions
  • WebAPIException:

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type TypeMismatchError if any of the input attributes are of the wrong type

Code example
 function successCB() {
     console.log("setting source is successful");
     }
 }

 function errorCB(error) {
     console.log(error.name);
 }
 
 try {
     webapis.tv.window.setSource( {
         type : webapis.tv.window.SOURCE_MODE_TV, 
         number : 0 }, 
         successCB,
         errorCB);
 } catch (error) {
     console.log(error.name);
 }

getSource

Returns a current source. (TV, PC, DVI, etc.)

Signature
SourceInfo getSource(optional unsigned short windowID);
Parameters
  • windowID
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned short.
    • Description: window This identifier
Return value
SourceInfo current source type which is one of Window Source Type Constants
Exceptions
  • WebAPIException:

    with error type UnknownError, In the case of any other error

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type InvalidValuesError If the input attributes do not contain valid values

    with error type TypeMismatchError if any of the input attributes are of the wrong type

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

setRect

Sets the display area for video content on TV screen.

Signature
boolean setRect(SRect rect, optional unsigned short windowID);
Parameters
  • rect
    • Optional: No.
    • Nullable: No.
    • Type: SRect.
    • Description: window's size and position.
  • windowID
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned short.
    • Description: This identifier of the window which will be resized.
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type InvalidValuesError If the input attributes do not contain valid values.

    with error type TypeMismatchError if any of the input attributes are of the wrong type.

Code example
 webapis.tv.window.setRect({
     width : 320,
     height : 240,
     top : 0,
     left : 0
 });

show

Shows the specific window for the display area on the TV screen.

Signature
boolean show(optional unsigned short windowID);
Parameters
  • windowID
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned short.
    • Description: the window identifier which will be shown; if it is undefined, the current window ID will be assigned.
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type InvalidValuesError If the input attributes do not contain valid values

    with error type TypeMismatchError if any of the input attributes are of the wrong type

Code example
 function successCB(windows) {
     for (var i = 0; i  windows.length; i++) {
         if (i == 0) {
            if (webapis.tv.window.show(windows[i])) { 
                console.log("window #0 is shown"); 
            }
     }
 }

 function errorCB(error) {
     console.log(error.name);
 }
 
 try {
     webapis.tv.window.getAvailableWindow(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }

hide

Hides the specific window for the display area on the TV screen.

Signature
boolean hide(optional unsigned short windowID);
Parameters
  • windowID
    • Optional: Yes.
    • Nullable: No.
    • Type: unsigned short.
    • Description: the window identifier which will be hidden. The default value is the current window's ID.
Return value
true if the operation is successful, otherwise false
Exceptions
  • WebAPIException:

    with error type UnknownError, In the case of any other error

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type InvalidValuesError If the input attributes do not contain valid values

    with error type TypeMismatchError if any of the input attributes are of the wrong type

Code example
 function successCB(windows) {
     for (var i = 0; i  windows.length; i++) {
         if (i == 0) {
            if (webapis.tv.window.hide(windows[i])) { console.log("window #0 is hidden"); }
     }
 }

 function errorCB(error) {
     console.log(error.name);
 }
 
 webapis.tv.window.getAvailableWindow(successCB, errorCB);

1.3. SourceInfo

Specifies the options for source information 

    dictionary SourceInfo {
        unsigned short type;

        unsigned long number;
    };

Dictionary members

unsigned short type

a source type

unsigned long number

a source number

1.4. AvailableWindowListCallback

The callback after retrieving a list of windows successfully. This function is used to get a number of available sub windows. 

    [Callback=FuntionOnly, NoInterfaceObject] interface AvailableWindowListCallback {
        void onsuccess(UnsignedShortArray windowArray);
    };

METHODS

onsuccess

Success callback for retrieving a list of windows.

Signature
void onsuccess(UnsignedShortArray windowArray);

This function is used to get the number of available subwindows.

Parameters
  • windowArray
    • Optional: No.
    • Nullable: No.
    • Type: UnsignedShortArray.
    • Description: array of available window IDs.

1.5. SourceChangedSuccessCallback

The callback after window source has been changed successfully. 

    [Callback=FuntionOnly, NoInterfaceObject] interface SourceChangedSuccessCallback {

        void onsuccess(SourceInfo info, unsigned short windowID);
    };

This function is used to get the changed sourceInfo and the associated windowID.

METHODS

onsuccess

The method which will be invoked after changing the window source successfully.

Signature
void onsuccess(SourceInfo info, unsigned short windowID);
Parameters
  • info
    • Optional: No.
    • Nullable: No.
    • Type: SourceInfo.
    • Description: source information which has been changed successfully.
  • windowID
    • Optional: No.
    • Nullable: No.
    • Type: unsigned short.
    • Description: window ID for which source has been changed.

2. Full WebIDL 

module Window {    
    [NoInterfaceObject] interface WebAPIsTVWindowManager {
        readonly attribute TVWindowManager window;
    };
    TV implements WebAPIsTVWindowManager;
    
    [NoInterfaceObject] interface TVWindowManager {  

        const unsigned long SOURCE_MODE_TV = 0;

        const unsigned long SOURCE_MODE_AV = 1;

        const unsigned long SOURCE_MODE_SVIDEO  = 2;

        const unsigned long SOURCE_MODE_COMP = 3;

        const unsigned long SOURCE_MODE_PC = 4;

        const unsigned long SOURCE_MODE_HDMI = 5;

        const unsigned long SOURCE_MODE_SCART= 6;

        const unsigned long SOURCE_MODE_DVI = 7;

        const unsigned long SOURCE_MODE_MEDIA = 8;

        const unsigned long SOURCE_MODE_IPTV = 9;
               
        void getAvailableWindow(AvailableWindowListCallback successCallback,  
                                       optional ErrorCallback errorCallback);
                
        void setSource(SourceInfo sourceInfo, 
                          SourceChangedSuccessCallback sourceChangedSuccessCallback,  
                          optional ErrorCallback? errorCallback,  
                          optional unsigned short windowID);
 
        SourceInfo getSource(optional unsigned short windowID);      
                              
        boolean setRect(SRect rect, optional unsigned short windowID);
                        
        boolean show(optional unsigned short windowID);
        
        boolean hide(optional unsigned short windowID);       

    };
    
    dictionary SourceInfo {
        unsigned short type;

        unsigned long number;
    };
    
    [Callback=FuntionOnly, NoInterfaceObject] interface AvailableWindowListCallback {
        void onsuccess(UnsignedShortArray windowArray);
    };
    
    [Callback=FuntionOnly, NoInterfaceObject] interface SourceChangedSuccessCallback {

        void onsuccess(SourceInfo info, unsigned short windowID);
    };
};