Samsung Web API: ViewController

Introduction

This API allows developers to control the view available on a Samsung Smart TV in detail. This feature provides expanded control of Digital Media Renderer (DMR) for images.

It can control Samsung Smart TVs manufactured since 2012.

Summary of Interfaces and Methods

Interface	Method
ViewControllerSuccessCallback	void onsuccess(DeviceId imageViewerId)
ViewControllerErrorCallback	void onerror(WebAPIError error, DeviceId imageViewerId)
ViewControllerEventCallback	void ondisconnected(DeviceId imageViewerId)
ViewController	void connect(ViewControllerSuccessCallback successCallback, ViewControllerErrorCallback? errorCallback) void disconnect(ViewControllerSuccessCallback successCallback, ViewControllerErrorCallback? errorCallback) void move(unsigned long cx, unsigned long cy, boolean isReleased, ViewControllerSuccessCallback successCallback, ViewControllerErrorCallback? errorCallback) void setViewAngle(ViewAngle angle, ViewControllerSuccessCallback successCallback, ViewControllerErrorCallback? errorCallback) void zoom(unsigned long cx, unsigned long cy, unsigned long zoomPercent, ViewAngle angle, unsigned long sourceWidth, unsigned long sourceHeight) long addViewControllerEventListener(ViewControllerEventCallback eventCallback) void removeViewControllerEventListener(long eventListenerId)

1. Type Definitions

1.1. ViewAngle

Specifies the value for the angle of the view.

    enum ViewAngle { 
        "0", 
        "90",
        "180", 
        "270"
    };

0: The same angle with the original source
90: The 90 degree angle with the original source
180: The 180 degree angle with the original source
270: The 270 degree angle with the original source

2. Interfaces

2.1. ViewControllerSuccessCallback

Generic success callback for viewcontroller related operations.

    [Callback=FunctionOnly, NoInterfaceObject] interface ViewControllerSuccessCallback {
        
        void onsuccess(DeviceId imageViewerId);
    };

METHODS

onsuccess

Callback function invoked when operation is completed successfully.

Signature

void onsuccess(DeviceId imageViewerId);

Parameters

imageViewerId
- Optional: No.
- Nullable: No.
- Type: DeviceId.
- Description: The ID of the image viewer which made the request. As the sub feature of image viewer, The view controller object can be retrieved using device finder's getDevice('IMAGEVIEWER', imageViewerId, 'VIEWCONTROLLER').

2.2. ViewControllerErrorCallback

Generic success callback for viewcontroller related operations.

    [Callback=FunctionOnly, NoInterfaceObject] interface ViewControllerErrorCallback {
        
        void onerror(WebAPIError error,
                     DeviceId imageViewerId);
    };

METHODS

onerror

Callback function invoked when error occurs.

Signature

void onerror(WebAPIError error, DeviceId imageViewerId);

Parameters

error
- Optional: No.
- Nullable: No.
- Type: WebAPIError.
- Description: WebAPIError object which indicates error type and message.
imageViewerId
- Optional: No.
- Nullable: No.
- Type: DeviceId.
- Description: The ID of the image viewer which made the request. As the sub feature of image viewer, The view controller object can be retrieved using device finder's getDevice('IMAGEVIEWER', imageViewerId, 'VIEWCONTROLLER').

2.3. ViewControllerEventCallback

Callback interface that notifies the application when the ViewController event is received.

    [Callback, NoInterfaceObject] interface ViewControllerEventCallback {

        void ondisconnected(DeviceId imageViewerId);
    };

METHODS

ondisconnected

Callback function invoked when the device is disconnected.

Signature

void ondisconnected(DeviceId imageViewerId);

Parameters

imageViewerId
- Optional: No.
- Nullable: No.
- Type: DeviceId.
- Description: The ID of the image viewer which has disconnected. As the sub feature of image viewer, The view controller object can be retrieved using device finder's getDevice('IMAGEVIEWER', imageViewerId, 'VIEWCONTROLLER').

2.4. ViewController

This interface provides a means of controlling the view.

    [NoInterfaceObject] interface ViewController {
        
        readonly attribute DeviceId id;

        readonly attribute boolean isConnected;
        
        readonly attribute unsigned long viewHeight;
        
        readonly attribute unsigned long viewWidth;
        
        void connect(ViewControllerSuccessCallback successCallback,
                     optional ViewControllerErrorCallback? errorCallback);
        
        void disconnect(ViewControllerSuccessCallback successCallback,
                        optional ViewControllerErrorCallback? errorCallback);
        
        void move(unsigned long cx,
                  unsigned long cy,
                  boolean isReleased,
                  ViewControllerSuccessCallback successCallback,
                  optional ViewControllerErrorCallback? errorCallback);
        
        void setViewAngle(ViewAngle angle,
                          ViewControllerSuccessCallback successCallback,
                          optional ViewControllerErrorCallback? errorCallback);
        
        void zoom(unsigned long cx,
                  unsigned long cy,
                  unsigned long zoomPercent,
                  ViewAngle angle,
                  unsigned long sourceWidth,
                  unsigned long sourceHeight);
        
        long addViewControllerEventListener(ViewControllerEventCallback eventCallback);
        
        void removeViewControllerEventListener(long eventListenerId);
    };

After getting the object of ImageViewer, the developer can request the object of ViewController.

Code example

 
 var serviceProvider; // it is assumed that you obtained serviceProvider. For further details, see the creatServiceProvider(..).
 var deviceId;           // it is assumed that an ImageViewer's device ID has already been determined
 
 try {
     var imageViewer = serviceProvider.getDeviceFinder().getDevice("IMAGEVIEWER", deviceId);
     var viewController = imageViewer.getViewController();

     if (viewController != null) {
         // Developer can control view controller
     }
 } catch (e) {
      console.log(e.name);
 }

ATTRIBUTES

readonly DeviceId id: Specifies the unique ID of the receiver.

It will be the same ID of an imageviewer device which provides this view controller.

This attribute is read-only.
readonly boolean isConnected: Flag indicates whether the connection is established or not.
This attribute is read-only.
readonly unsigned long viewHeight: Height of the view.
This attribute is read-only.
readonly unsigned long viewWidth: Width of the view.
This attribute is read-only.

METHODS

connect

Establish a connection to Smart TV.

Signature

void connect(ViewControllerSuccessCallback successCallback, optional ViewControllerErrorCallback? errorCallback);

The error callback is launched with these error types:

NotConnectedServiceError: if the application doesn't connect to AllShare framework.
InvalidStateError: if the device is invalid or unusable.
UnknownError: In the case of any other error

Parameters

successCallback
- Optional: No.
- Nullable: No.
- Type: ViewControllerSuccessCallback.
- Description: Success callback invoked when the operation is successful.
errorCallback
- Optional: Yes.
- Nullable: Yes.
- Type: ViewControllerErrorCallback.
- Description: Error callback invoked when error occurs.

Exceptions

WebAPIException:
with error type NotSupportedError, if this feature is not supported.

with error type SecurityError, if this functionality is not allowed.

with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example

 
 var viewController; // it is assumed that a proper view controller object is stored;

 //Define a success callback.
 function viewControllerSCB(controllerId) {
     console.log("connection has been made properly.");
 }
 
 //Define an error callback
 function viewControllerECB(error, controllerId){
         console.log(error.message);
 }
 
 try {
         viewController.connect(viewControllerSCB, viewControllerECB);
 } catch (e) {
         console.log(e.name);
 }

disconnect

Break off the connection to the Smart TV.

Signature

void disconnect(ViewControllerSuccessCallback successCallback, optional ViewControllerErrorCallback? errorCallback);

The error callback is launched with these error types:

NotConnectedServiceError: if the application doesn't connect to AllShare framework.
InvalidStateError: if the device is invalid or unusable.
UnknownError: In the case of any other error

Parameters

successCallback
- Optional: No.
- Nullable: No.
- Type: ViewControllerSuccessCallback.
- Description: Success callback invoked when the operation is successful.
errorCallback
- Optional: Yes.
- Nullable: Yes.
- Type: ViewControllerErrorCallback.
- Description: Error callback invoked when error occurs.

Exceptions

WebAPIException:
with error type NotSupportedError, if this feature is not supported.

with error type SecurityError, if this functionality is not allowed.

with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example

 
 var viewController; // it is assumed that a proper view controller object which has connected

 //Define a success callback.
 function viewControllerSCB(controllerId) {
     console.log("connection has been made properly.");
 }
 
 //Define an error callback
 function viewControllerECB(error, controllerId) {
         console.log(error.message);
 }
 
 try {
         viewController.disconnect(viewControllerSCB, viewControllerECB);
 } catch (e) {
         console.log(e.name);
 }

move

Move the center of the view

Signature

void move(unsigned long cx, unsigned long cy, boolean isReleased, ViewControllerSuccessCallback successCallback, optional ViewControllerErrorCallback? errorCallback);

The error callback is launched with these error types:

UnknownError: In the case of any other error

Parameters

cx
- Optional: No.
- Nullable: No.
- Type: unsigned long.
- Description: New horizontal coordinate of the view center.
cy
- Optional: No.
- Nullable: No.
- Type: unsigned long.
- Description: New vertical coordinate of the view center.
isReleased
- Optional: No.
- Nullable: No.
- Type: boolean.
- Description: Boolean value identifying the touch state.
successCallback
- Optional: No.
- Nullable: No.
- Type: ViewControllerSuccessCallback.
- Description: Success callback invoked when the operation is successful.
errorCallback
- Optional: Yes.
- Nullable: Yes.
- Type: ViewControllerErrorCallback.
- Description: Error callback invoked when error occurs.

Exceptions

WebAPIException:
with error type NotSupportedError, if this feature is not supported.

with error type SecurityError, if this functionality is not allowed.

with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example

 
 var viewController; // it is assumed that a proper view controller object which has connected

 //Define a success callback.
 function viewControllerSCB(controller) {
     console.log("connection has been made properly.");
 }
 
 //Define an error callback
 function viewControllerECB(error, controller) {
         console.log(error.message);
 }
 
 try {
        if (viewController.isConnected) {
            viewController.move(18, 18, true, viewControllerSCB, viewControllerECB);
        }
 } catch (e) {
         console.log(e.name);
 }

setViewAngle

Set the view angle.

Signature

void setViewAngle(ViewAngle angle, ViewControllerSuccessCallback successCallback, optional ViewControllerErrorCallback? errorCallback);

The error callback is launched with these error types:

UnknownError: In the case of any other error

Parameters

angle
- Optional: No.
- Nullable: No.
- Type: ViewAngle.
- Description: The angle of the view. This value is not relative to the current displayed view angle, but is an absolute view angle relative to the original source.
successCallback
- Optional: No.
- Nullable: No.
- Type: ViewControllerSuccessCallback.
- Description: Success callback invoked when the operation is successful.
errorCallback
- Optional: Yes.
- Nullable: Yes.
- Type: ViewControllerErrorCallback.
- Description: Error callback invoked when error occurs.

Exceptions

WebAPIException:
with error type NotSupportedError, if this feature is not supported.

with error type SecurityError, if this functionality is not allowed.

with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example

 
 var viewController; // it is assumed that a proper view controller object which has connected;

 //Define a success callback.
 function viewControllerSCB(controller) {
     console.log("connection has been made properly.");
 }
 
 //Define an error callback
 function viewControllerECB(error, controller) {
         console.log(error.message);
 }
 
 try {
        if (viewController.isConnected) {
            viewController.setViewAngle("90", viewControllerSCB, viewControllerECB);
        }
 } catch (e) {
         console.log(e.name);
 }

zoom

Zoom the view in or out.

Signature

void zoom(unsigned long cx, unsigned long cy, unsigned long zoomPercent, ViewAngle angle, unsigned long sourceWidth, unsigned long sourceHeight);

Although zoom rate of original image has been changed in TV, if the angle of the view of the mobile device is changed, the view of the TV is shown in 100 percent size.

Parameters

cx
- Optional: No.
- Nullable: No.
- Type: unsigned long.
- Description: The horizontal coordinate of the view center.
cy
- Optional: No.
- Nullable: No.
- Type: unsigned long.
- Description: The vertical coordinate of the view center.
zoomPercent
- Optional: No.
- Nullable: No.
- Type: unsigned long.
- Description: The zoom percentage.
angle
- Optional: No.
- Nullable: No.
- Type: ViewAngle.
- Description: The angle of the view. This value is not relative to the current displayed view angle, but is an absolute view angle relative to the original source.
sourceWidth
- Optional: No.
- Nullable: No.
- Type: unsigned long.
- Description: The width of original image. This value will affect relative zoom rate of width. If this value is not correct, zoom results will differ from those intended.
sourceHeight
- Optional: No.
- Nullable: No.
- Type: unsigned long.
- Description: The height of original image. This value will affect relative zoom rate of height. If this value is not correct, zoom results will differ from the intended.

Exceptions

WebAPIException:
with error type NotSupportedError, if this feature is not supported.

with error type SecurityError, if this functionality is not allowed.

with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example

 
 var viewController; // it is assumed that a proper view controller object which has connected.
 var zoomRatio = 100;
 var originalWidth, originalHeight; // assumed to be the original size of the stored image.

 //Define a success callback.
 function viewControllerSCB(controller) {
     console.log("connection has been made properly.");
 }
 
 //Define an error callback
 function viewControllerECB(error, controller) {
         console.log(error.message);
 }
 
 try {
        if (viewController.isConnected) {
            viewController.zoom(8, 8, zoomRatio * 1, "180", orginalWidth, orginalHeight);
        }
 } catch (e) {
         console.log(e.name);
 }

addViewControllerEventListener

Set the view controller event listener.

Signature

long addViewControllerEventListener(ViewControllerEventCallback eventCallback);

Parameters

eventCallback
- Optional: No.
- Nullable: No.
- Type: ViewControllerEventCallback.
- Description: Callback interface that will capture the event.

Return value

long Identifier for the event listener. It can be used to remove the listener.

Exceptions

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

with error type NotSupportedError, if this feature is not supported.

with error type SecurityError, if this functionality is not allowed.

with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example

 
 var eventListener = {
         ondisconnected(viewController) {console.log("disconnected.");  }
 };
 
 try {
        if (viewController.isConnected) {
            var handle = viewController.addViewControllerEventListener(eventListener);
        }
 } catch (e) {
         console.log(e.name);
 }

removeViewControllerEventListener

Remove the event listener.

Signature

void removeViewControllerEventListener(long eventListenerId);

Parameters

eventListenerId
- Optional: No.
- Nullable: No.
- Type: long.
- Description: ID of the event listener returned by addViewControllerEventListener.

Exceptions

WebAPIException:
with error type UnknownError, any other error case.

with error type NotSupportedError, if this feature is not supported.

with error type SecurityError, if this functionality is not allowed.

with error type InvalidValuesError, if any input parameter contains invalid values.

with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example

 
 var eventHandle; // it is assumed that an event handle which is registered.
 
 try {
        if (viewController.isConnected) {
            viewController.removeViewControllerEventListener(eventHandle);
        }
 } catch (e) {
         console.log(e.name);
 }

3. Full WebIDL

module ViewController {

    enum ViewAngle { 
        "0", 
        "90",
        "180", 
        "270"
    };
    
    [Callback=FunctionOnly, NoInterfaceObject] interface ViewControllerSuccessCallback {
        
        void onsuccess(DeviceId imageViewerId);
    };
    
    [Callback=FunctionOnly, NoInterfaceObject] interface ViewControllerErrorCallback {
        
        void onerror(WebAPIError error,
                     DeviceId imageViewerId);
    };
    
    [Callback, NoInterfaceObject] interface ViewControllerEventCallback {

        void ondisconnected(DeviceId imageViewerId);
    };
    
    [NoInterfaceObject] interface ViewController {
        
        readonly attribute DeviceId id;

        readonly attribute boolean isConnected;
        
        readonly attribute unsigned long viewHeight;
        
        readonly attribute unsigned long viewWidth;
        
        void connect(ViewControllerSuccessCallback successCallback,
                     optional ViewControllerErrorCallback? errorCallback);
        
        void disconnect(ViewControllerSuccessCallback successCallback,
                        optional ViewControllerErrorCallback? errorCallback);
        
        void move(unsigned long cx,
                  unsigned long cy,
                  boolean isReleased,
                  ViewControllerSuccessCallback successCallback,
                  optional ViewControllerErrorCallback? errorCallback);
        
        void setViewAngle(ViewAngle angle,
                          ViewControllerSuccessCallback successCallback,
                          optional ViewControllerErrorCallback? errorCallback);
        
        void zoom(unsigned long cx,
                  unsigned long cy,
                  unsigned long zoomPercent,
                  ViewAngle angle,
                  unsigned long sourceWidth,
                  unsigned long sourceHeight);
        
        long addViewControllerEventListener(ViewControllerEventCallback eventCallback);
        
        void removeViewControllerEventListener(long eventListenerId);
    };
};

Samsung Web API: ViewController

Introduction

Table of Contents

Summary of Interfaces and Methods

1. Type Definitions

1.1. ViewAngle

2. Interfaces

2.1. ViewControllerSuccessCallback

METHODS

Signature

Parameters

2.2. ViewControllerErrorCallback

METHODS

Signature

Parameters

2.3. ViewControllerEventCallback

METHODS

Signature

Parameters

2.4. ViewController

Code example

ATTRIBUTES

METHODS

Signature

Parameters

Exceptions

Code example

Signature

Parameters

Exceptions

Code example

Signature

Parameters

Exceptions

Code example

Signature

Parameters

Exceptions

Code example

Signature

Parameters

Exceptions

Code example

Signature

Parameters

Return value

Exceptions

Code example

Signature

Parameters

Exceptions

Code example

3. Full WebIDL