Samsung Electronics logo

Samsung Web API: ImageView


Introduction

This API provides access control to images which may be encrypted by digital rights management (DRM) on the device associated with the TV.

A webapis.imageview object provides access to the functionality of the imageview API.

For more information on the Image View features, see Image View Guide.


Table of Contents


Summary of Interfaces and Methods

Interface Method
WebAPIsImageViewManager
ImageViewManager void getImageView(AvailableImageViewSuccessCallback successCallback, ErrorCallback? errorCallback)
AvailableImageViewSuccessCallback void onsuccess(ImageView obj)
ImageViewInitialOption
ImageOption
ImageView boolean init(ImageViewInitialOption? option)
void prepare(DOMString url, SuccessCallback successCallback, ErrorCallback? errorCallback, ImageOption option)
boolean setSlideShow(boolean slideshowMode)
void draw(SuccessCallback successCallback, ErrorCallback? errorCallback)
boolean setDisplayRect(SRect rect)
boolean clear()
boolean show()
boolean hide()
EffectListArray getTransitionEffectList()

1. Type Definitions

1.1. EffectListArray

array of slide show effects

    typedef sequence<unsigned short> EffectListArray;

2. Interfaces

2.1. WebAPIsImageViewManager

The imageview manager which provides the controls of image viewer

    [NoInterfaceObject] interface WebAPIsImageViewManager { 
        readonly attribute ImageViewManager imageview; 
    };
    WebAPIs implements WebAPIsImageViewManager;

A webapis.image object provides access to the functionality of the image view module.

2.2. ImageViewManager

Defines what is instantiated in the webapis object.

    [NoInterfaceObject] interface ImageViewManager {

        const short EFFECT_INIT = -1;

        const short EFFECT_FADE_1 = 0;

        const short EFFECT_FADE_2 = 1;

        const short EFFECT_BLIND = 2;

        const short EFFECT_SPIRAL = 3;

        const short EFFECT_CHECKER = 4;

        const short EFFECT_LINEAR = 5;

        const short EFFECT_STAIRS = 6;

        const short EFFECT_WIPE = 7;

        const short EFFECT_RANDOM = 8;

        const short EFFECT_NORMAL = 9;

       const short IMAGEVIEW_STATE_IDLE = 0;        

       const short IMAGEVIEW_STATE_INITIALIZED = 1;
               
       const short IMAGEVIEW_STATE_PREPARED = 3;

       const short IMAGEVIEW_STATE_DRAWN = 4;

       const short IMAGEVIEW_STATE_STOPPED = 5;
       
        void getImageView(AvailableImageViewSuccessCallback successCallback,
                               optional ErrorCallback? errorCallback)
                              ;
    };

A webapis.imageview object provides access to the functionality of the imageview module.

CONSTANTS

short EFFECT_INIT

This identifier indicates an initial image transition effect.

short EFFECT_FADE_1

This identifier indicates a fade 1 image transition effect.

short EFFECT_FADE_2

This identifier indicates a fade 2 image transition effect.

short EFFECT_BLIND

This identifier indicates a blind image transition effect.

short EFFECT_SPIRAL

This identifier indicates a spiral image transition effect.

short EFFECT_CHECKER

This identifier indicates a checker image transition effect.

short EFFECT_LINEAR

This identifier indicates a linear image transition effect.

short EFFECT_STAIRS

This identifier indicates a stairs image transition effect.

short EFFECT_WIPE

This identifier indicates a wipe image transition effect.

short EFFECT_RANDOM

This identifier indicates a random image transition effect.

short EFFECT_NORMAL

This identifier indicates a normal image transition effect.

short IMAGEVIEW_STATE_IDLE

This identifier indicates imageview is in idle state.

short IMAGEVIEW_STATE_INITIALIZED

This identifier indicates imageview has been initialized.

short IMAGEVIEW_STATE_PREPARED

This identifier indicates imageview is prepared to draw.

short IMAGEVIEW_STATE_DRAWN

This identifier indicates that drawing of an image is complete.

short IMAGEVIEW_STATE_STOPPED

This identifier indicates imageview is stopped.

METHODS

getImageView

Gets the imageview object which renders an image file

Signature
void getImageView(AvailableImageViewSuccessCallback successCallback, optional ErrorCallback? errorCallback);

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If any of the input parameters contains an invalid value
  • UnknownError: In the case of any other error

If the errorCallback does not contain a valid function (e.g. it contains 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 (i.e. the developer is not notified of the error).

Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: AvailableImageViewSuccessCallback.
    • Description: method will be invoked when this operation has completed successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: method will be invoked in error condition.
Exceptions
  • WebAPIException:

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 function successCB(imageViewObj) {
    console.log("getting image view object successfully");
  }

 function errorCB(error) {
     console.log("Cannot get image view object : " + error.name);
 }

 try {
     webapis.imageview.getImageView(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

2.3. AvailableImageViewSuccessCallback

Callback which will be invoked after retrieving a imageview successfully.

    [Callback=FuntionOnly, NoInterfaceObject] interface AvailableImageViewSuccessCallback {
        void onsuccess(ImageView obj);
    };

METHODS

onsuccess

method invoked when the available imageview is retrieved successfully.

Signature
void onsuccess(ImageView obj);
Parameters
  • obj
    • Optional: No.
    • Nullable: No.
    • Type: ImageView.
    • Description: available imageview object

2.4. ImageViewInitialOption

Specifies the options for initializing ImageView.

    dictionary ImageViewInitialOption
    {
        SRect? displayRect;

        DOMString? containerID;            

        unsigned short? zIndex;
    };

Dictionary members

SRect? displayRect

the position of the displayed screen area.

DOMString? containerID

The container identifier.

unsigned short? zIndex

Z-index.

2.5. ImageOption

Specifies the options for preparing the image.

    dictionary ImageOption
    {
        short effect;
    };

Dictionary members

short effect

slide-show effect

2.6. ImageView

The image viewer manager interface which provides access to the image view API.

    [NoInterfaceObject] interface ImageView {
        readonly attribute DOMString id;

        readonly attribute DOMString url;

        readonly attribute unsigned short imageWidth;

        readonly attribute unsigned short imageHeight;

        readonly attribute SRect displayRect;

        readonly attribute DOMString containerID;            

        readonly attribute unsigned short zIndex;

        readonly attribute short effect;

        readonly attribute short status;

        boolean init(optional ImageViewInitialOption? option);
        
        void prepare(DOMString url, 
                        SuccessCallback successCallback, 
                        ErrorCallback? errorCallback, 
                        optional ImageOption option) 
                       ;
                
        boolean setSlideShow(boolean slideshowMode);        
                                         
        void draw(SuccessCallback successCallback, 
                     ErrorCallback? errorCallback)
                    ;

        boolean setDisplayRect(SRect rect);
                
        boolean clear();
      
        boolean show();
        
        boolean hide();
        
        EffectListArray getTransitionEffectList();    
    };

This exposes the image viewing API to provide functionalities for showing images on the display.

ATTRIBUTES

readonly DOMString id

Imageview identification

This attribute is read-only.

readonly DOMString url

The URL of the image that is currently being displayed.

This attribute is read-only.

readonly unsigned short imageWidth

The width of the image that is currently being displayed.

This attribute is read-only.

readonly unsigned short imageHeight

This string stores the width of the video that is currently being displayed.

This attribute is read-only.

readonly SRect displayRect

Stores the display area of the image that is currently being displayed.

The displayRect stores four values. The first two values represent the X and Y coordinates of the upper-left corner of the video and the next two parameters represent the width and height of the image.

This attribute is read-only.

readonly DOMString containerID

container This identifier of

This attribute is read-only.

readonly unsigned short zIndex

z-index

This attribute is read-only.

readonly short effect

image effect mode

This attribute is read-only.

readonly short status

Stores the current status of the imageView.

This attribute is read-only.

METHODS

init

This method initializes the imageview with the proper option.

Signature
boolean init(optional ImageViewInitialOption? option);
Parameters
  • option
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ImageViewInitialOption.
    • Description: the option for ImageView initialization
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 TypeMismatchError if any of the input attributes are of the wrong type

Code example
 function successCB(imageviewObj) {
     imageviewObj.init({
         containerID : "0",
         zIndex : 1,
         displayRect : {
             width : 480,
             height : 240,
             top : 0, 
             left : 0
             }
       });  
  }

 function errorCB(error) {
     console.log("Cannot get imageview object : " + error.name);
 }

 try {
     webapis.imageview.getImageView(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
     

prepare

Opens the image with the url of the image file that is supposed to be displayed and the ImageOption.

Signature
void prepare(DOMString url, SuccessCallback successCallback, ErrorCallback? errorCallback, optional ImageOption option);

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If any of the input parameters contains an invalid value
  • UnknownError: In the case of any other error

If the errorCallback does not contain a valid function (e.g. it contains 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 (i.e. the developer is not notified of the error).

Parameters
  • url
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: the URL of an image file
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: SuccessCallback.
    • Description: To be invoked if the operation is completed successfully.
  • errorCallback
    • Optional: No.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: To be invoked when an error occurs.
  • option
    • Optional: Yes.
    • Nullable: No.
    • Type: ImageOption.
    • Description: a option for opening the specific image contents.
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 prepareCB() {
     console.log("preparation is done");
 }

 function successCB(imageviewObj) {
     imageviewObj.init({
         containerID : "0",
         zIndex : 1,
         displayRect : {
             width : 480,
              height : 240,
                top : 0, 
               left : 0
               }
     });
     imageviewObj.prepare("image.gif", prepareCB, errorCB, { effect: webapis.imageview.EFFECT_INIT });
 }

 function errorCB(error) {
     console.log(error.name);
 }

 try {
     webapis.imageview.getImageView(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
     

setSlideShow

Sets the slide show mode

Signature
boolean setSlideShow(boolean slideshowMode);
Parameters
  • slideshowMode
    • Optional: No.
    • Nullable: No.
    • Type: boolean.
    • Description: true if setting the slide show mode, otherwise false. an option for the ImageView initialization.
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.

Code example
 function successCB(imageviewObj) {
     imageviewObj.init({
         containerID : "0",
         zIndex : 1,
         displayRect : {
             width : 480,
             height : 240,
             top : 0, 
             left : 0
         });
     imageviewObj.setSlideShow(true);
  }

 function errorCB(error) {
     console.log(error.name);
 }

 try {
     webapis.imageview.getImageView(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
     

draw

Starts drawing image stored in the URL, passed as a parameter to the prepare function.

Signature
void draw(SuccessCallback successCallback, ErrorCallback? errorCallback);

The ErrorCallback is launched with these error types:

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

If the errorCallback does not contain a valid function (e.g. it contains 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 (i.e. the developer is not notified of the error).

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

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

    with error type SecurityError if this functionality is not allowed.

Code example
 
 var gImageViewObj;
 function drawCB() {
    console.log("image is drawn properly");
 }

 function prepareCB() {
     console.log("preparation is done");
     gImageViewObj.draw(drawCB, errorCB);
 }

 function successCB(imageviewObj) {
     gImageViewObj = imageviewObj;
     gImageViewObj.init({
         containerID : "0",
         zIndex : 1,
         displayRect : {
             width : 480,
              height : 240,
                top : 0, 
               left : 0
               }
       });
    gImageViewObj.prepare("image.gif", prepareCB, errorCB, { effect: webapis.imageview.EFFECT_INIT });
  }

 function errorCB(error) {
     console.log(error.name);
 }

 try {
     webapis.imageview.getImageView(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
     

setDisplayRect

This method sets the display area to the values in the srect. There are four values. The first two values specify the X and Y coordinates of the upper-left corner of the area, and the next two values specify the width and height of the image.

Signature
boolean setDisplayRect(SRect rect);
Parameters
  • rect
    • Optional: No.
    • Nullable: No.
    • Type: SRect.
    • Description: the position of the display area
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 TypeMismatchError if any of the input attributes are of the wrong type

Code example
 var gImageViewObj;

 function onChangeScreenSize(rect) {
     gImageViewObj.setDisplayRect(rect);
 }

 function drawCB() {
    console.log("image is drawn properly");
 }

 function prepareCB() {
     console.log("preparation is done");
 }

 function successCB(imageviewObj) {
    gImageViewObj = imageviewObj;
     gImageViewObj.init({
         containerID : "0",
         zIndex : 1,
         displayRect : {
             width : 480,
              height : 240,
                top : 0, 
               left : 0
         }
     });
    gImageViewObj.prepare("image.gif", prepareCB, errorCB, { effect: webapis.imageview.EFFECT_INIT });
    gImageViewObj.draw(drawCB, errorCB);
  }

 function errorCB(error) {
     console.log(error.name);
 }

 try {
     webapis.imageview.getImageView(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

clear

Clears the TV screen (sets it to black).

Signature
boolean clear();
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.

Code example
 var gImageViewObj;

 function onClear() {
     gImageViewObj.clear();
 }
 function drawCB() {
     console.log("image is drawn properly");
 }

 function prepareCB() {
     console.log("preparation is done");
     gImageViewObj.draw(drawCB, errorCB);
 }

 function successCB(imageviewObj) {
     gImageViewObj = imageviewObj;
     gImageViewObj.init({
          containerID : "0",
          zIndex : 1,
          displayRect : {
              width : 480,
              height : 240,
              top : 0, 
              left : 0
          }
     });
     gImageViewObj.prepare("image.gif", prepareCB, errorCB, { effect: webapis.imageview.EFFECT_INIT });
 }

 function errorCB(error) {
     console.log(error.name);
 }

 try {
     webapis.imageview.getImageView(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

show

Shows the display area on the tv screen.

Signature
boolean show();
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.

Code example
 var gImageViewObj;

 function onClickShow() {
     gImageViewObj.show();
 }
 function drawCB() {
     console.log("image is drawn properly");
     gImageViewObj.hide();
 }

 function prepareCB() {
     console.log("preparation is done");
     gImageViewObj.draw(drawCB, errorCB);
 }

 function successCB(imageviewObj) {
    gImageViewObj = imageviewObj;
    gImageViewObj.init({
         containerID : "0",
         zIndex : 1,
         displayRect : {
             width : 480,
             height : 240,
             top : 0, 
             left : 0
         }
    });
    gImageViewObj.prepare("image.gif", prepareCB, errorCB, { effect: webapis.imageview.EFFECT_INIT });
  }

 function errorCB(error) {
     console.log(error.name);
 }

 try {
     webapis.imageview.getImageView(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

hide

Hides the display area on the tv screen.

Signature
boolean hide();
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.

Code example
 var gImageViewObj;

 function onClickHide() {
     gImageViewObj.hide();
 }
 function drawCB() {
     console.log("image is drawn properly");
 }

 function prepareCB() {
     console.log("preparation is done");
     gImageViewObj.draw(drawCB, errorCB);
 }

 function successCB(imageviewObj) {
     gImageViewObj = imageviewObj;
     gImageViewObj.init({
          containerID : "0",
          zIndex : 1,
          displayRect : {
              width : 480,
              height : 240,
              top : 0, 
              left : 0
          }
     });
     gImageViewObj.prepare("image.gif", prepareCB, errorCB, { effect: webapis.imageview.EFFECT_INIT });
  }

 function errorCB(error) {
     console.log(error.name);
 }

 try {
     webapis.imageview.getImageView(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

getTransitionEffectList

Gets the list of the supported effect modes.

Signature
EffectListArray getTransitionEffectList();
Return value
short the transition effect mode
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.

Code example
 var gImageViewObj;
 
 function drawCB() {
     console.log("image is drawn properly");
     var effects = gImageViewObj.getTransitionEffectList();
     for (i = 0; i  effects.length; i++) {
         switch (effects[i]) {
             case webapis.imageview.EFFECT_FADE_1:
                 console.log("fade mode 1 is supported");
                 break;
             case webapis.imageview.EFFECT_FADE_2:
                 console.log("fade mode 2 is supported");
                 break;
         }
     }
 }

 function prepareCB() {
     console.log("preparation is done");
     gImageViewObj.draw(drawCB, errorCB);
 }

 function successCB(imageviewObj) {
     gImageViewObj = imageviewObj;
     gImageViewObj.init({
          containerID : "0",
          zIndex : 1,
          displayRect : {
              width : 480,
              height : 240,
              top : 0, 
              left : 0
          }
     });
     gImageViewObj.prepare("image.gif", prepareCB, errorCB, { effect: webapis.imageview.EFFECT_INIT });
  }

 function errorCB(error) {
     console.log(error.name);
 }

 try {
     webapis.imageview.getImageView(successCB, errorCB);
 } catch (error) {
     console.log(error.name);
 }
 

3. Full WebIDL

module ImageView {
    typedef sequence<unsigned short> EffectListArray;

    [NoInterfaceObject] interface WebAPIsImageViewManager { 
        readonly attribute ImageViewManager imageview; 
    };    
    WebAPIs implements WebAPIsImageViewManager;

    [NoInterfaceObject] interface ImageViewManager {

        const short EFFECT_INIT = -1;

        const short EFFECT_FADE_1 = 0;

        const short EFFECT_FADE_2 = 1;

        const short EFFECT_BLIND = 2;

        const short EFFECT_SPIRAL = 3;

        const short EFFECT_CHECKER = 4;

        const short EFFECT_LINEAR = 5;

        const short EFFECT_STAIRS = 6;

        const short EFFECT_WIPE = 7;

        const short EFFECT_RANDOM = 8;

        const short EFFECT_NORMAL = 9;

       const short IMAGEVIEW_STATE_IDLE = 0;        

       const short IMAGEVIEW_STATE_INITIALIZED = 1;
               
       const short IMAGEVIEW_STATE_PREPARED = 3;

       const short IMAGEVIEW_STATE_DRAWN = 4;

       const short IMAGEVIEW_STATE_STOPPED = 5;
       
        void getImageView(AvailableImageViewSuccessCallback successCallback,
                               optional ErrorCallback? errorCallback)
                              ;
    };            

    [Callback=FuntionOnly, NoInterfaceObject] interface AvailableImageViewSuccessCallback {
        void onsuccess(ImageView obj);
    };
 
    dictionary ImageViewInitialOption
    {
        SRect? displayRect;

        DOMString? containerID;            

        unsigned short? zIndex;
    };
    
    dictionary ImageOption
    {
        short effect;
    }; 

    [NoInterfaceObject] interface ImageView {
        readonly attribute DOMString id;

        readonly attribute DOMString url;

        readonly attribute unsigned short imageWidth;

        readonly attribute unsigned short imageHeight;

        readonly attribute SRect displayRect;

        readonly attribute DOMString containerID;            

        readonly attribute unsigned short zIndex;

        readonly attribute short effect;

        readonly attribute short status;

        boolean init(optional ImageViewInitialOption? option);
        
        void prepare(DOMString url, 
                        SuccessCallback successCallback, 
                        ErrorCallback? errorCallback, 
                        optional ImageOption option) 
                       ;
                
        boolean setSlideShow(boolean slideshowMode);        
                                         
        void draw(SuccessCallback successCallback, 
                     ErrorCallback? errorCallback)
                    ;

        boolean setDisplayRect(SRect rect);
                
        boolean clear();
      
        boolean show();
        
        boolean hide();
        
        EffectListArray getTransitionEffectList();    
    };  
};