Samsung Electronics logo

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.


Table of Contents


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