Samsung Electronics logo

Image Viewer Control

Table of Contents


When creating applications, you may need to play image content on a TV. Samsung Web APIs allow you to play image content on a TV and control image display with display area set, slideshow enable, and so on. Using ImageView API capabilities, your applications can:

Prerequisites

The ImageView API lets you play the image media content on a TV. When the application is launched, an ImageView object is automatically instantiated in the webapis object. The webapis.imageview object is an instance of the ImageViewManager interface, which gives the method to handle image content play on the TV. The following figure shows how the API objects are structured inside the application window. Adding the JavaScript file to your application is required. This is the script to add to the webapis file:

 
<html><head>
<!-- including the JavaScript file which supports Samsung Web API -->
<script type="text/javascript" language="javascript" src="$MANAGER_WIDGET/Common/webapi/1.0/webapis.js"></script>
</head></html>

Get the ImageView Object that Plays Image Files

To play image media content on a TV, an application needs the reference to the TV image viewer object. The ImageView API provides the ImageViewManager interface, which allows you to obtain reference to the TV image viewer. The method getImageView() gives you the ImageView object, which plays an image file. The ImageView instance can be created as follows:

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

Initialize, Load, and Draw Image Content

An application must first initialize the TV image viewer using the init method, then use the prepare method to load the image to execute the transition effect in slideshow mode and use the draw method to play image media content on a TV.

Initializing the image viewer

An application must pass the proper ImageViewInitialOption to initialize the image viewer. Detailed information on ImageViewInitialOption is described in the section “Option to set Image View options.” The following example illustrates how to initialize ImageView and set init options.

 
function successCB(imageviewObj) {
     /**
     * Specifies the options for the initialize imageviewer
     **/
     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);
 }	

Loading image content to ImageView

Once ImageView initialization is successful, an application must load the image content to execute image display with the ImageView option since this application must invoke the prepare() method of the ImageView instance and pass the URL of the image content and Image option for the effect to be set. If prepare method execution is successful, it returns successCallback; otherwise, it returns errorCallback. SuccessCallback occurs when the image displays completely on the screen. If a transition effect is used, the event occurs at the point when effect animation is ended. The following example illustrates how to load image content to ImageView with the image option set.

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

Drawing image in ImageView

Once ImageView is loaded and successCallback returned, an application must initiate drawing the image stored in the URL passed as a parameter to the prepare function since this application must invoke the draw() method under prepare successCallback of the ImageView instance. If draw method execution is successful, successCallback is returned; if drawing fails, errorCallback is returned. SuccessCallback occurs when the image is displayed completely on the screen. The following example illustrates how to initiate the draw method under the prepare successCallback function.

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

Set Attributes Such as Slideshow and Display Area

Image content plays on a TV with the ImageView object providing some APIs through which the image display property can be set. ImageView also provides an API that allows slideshow images to be set.

Setting display rectangle

If an application must set the display area where images are displayed based on application requirements, the application must use the setDisplayRect() method. This method sets the display area to the values in 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. The API returns true if the operation is successful; otherwise, it returns false. The following example illustrates how to set the display area for image content display.

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

Setting slideshow mode

An application can include features for image content playback, such as slideshow. To enable or disable the slideshow feature, the application must use the setSlideShow() method. This method sets the slideshow mode of image content playback. It has two values: true if setting the slideshow mode, and false, if otherwise. The API returns true if the operation is successful; otherwise, it returns false. The following example illustrates how to set slideshow mode for image content display.

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

Clear, Show, and Hide the Image Viewer

Image content plays on a TV, with the ImageView object providing APIs through which image display properties, such as show, hide, and clear, can be achieved.

Showing image content

An application must invoke the show() method in the ImageView instance. Show displays the area on the TV screen. The display area is identified with the setDisplayRect set value. show() returns true if the operation is successful; otherwise, it returns false. The following example illustrates how to set show mode for image content display.

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

Hiding image content

An application must invoke the hide() method in the ImageView instance to hide the display area on the TV screen. hide() returns true if the operation is successful; otherwise, it returns false. The following example illustrates how to set hide mode for image content display.

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

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

Clearing image content from the display area

Application can include a feature for clearing the image from the display area of the page. To clear the image content, an application must invoke the clear() method. This method erases the current displayed image from the display area. hide() returns true if the operation is successful; otherwise, it returns false. The following example illustrates how to clear the image from the content display area.

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

Identify the Supported Transition Effect

The ImageView APIs allow you to determine the details of the supported transition effect for a TV. It is important to find the supported transition so that the application can use any of the effects available for the TV. To use this, the application must invoke the getTransitionEffectList() method. getTransitionEffectList() returns the list of transition effects if the operation is successful; otherwise, it returns false. The following example illustrates how to use the getTransitionEffectList API.

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

Obtain Detailed Information on the ImageView Option and Properties

The ImageView APIs allow you to determine and enter settings into the ImageView Initial Option and Image Option properties supported by the device. It is important for the application to set the ImageView option in the init method and set the image option in the prepare method of the ImageView interface.

Set initial ImageView options

The ImageView API provides the ImageViewInitialOption interface, which allows you to set the initial ImageView option.

 
dictionary ImageViewInitialOption
{
	SRect displayRect;

	DOMString containerID;

    unsigned short zIndex;
};

The following table shows the properties available for ImageViewInitialOption

Interface Attributes Description
ImageViewInitialOption SRect displayRect The position of the displayed screen area.
DOMString containerID The container identifier
unsigned short zIndex Z-index value

Set image options

The ImageView API provides the ImageOption interface and specifies the options for preparing the image.

 
dictionary ImageOption
{
	short effect;
};