SAMSUNG DEVELOPERS

Smart TV

top

CImageViewer Module

Published 2014-10-28 | (Compatible with SDK 2.5,3.5,4.5,5.0,5.1 and 2011,2012,2013,2014 models)

Enables JPEG files to be played in SAMSUNG DTV.

Contents

CImageViewer is a common module that enables JPEG files to be displayed on Samsung DTV. With this module, images can be displayed on the DTV screen with a high resolution of 1920x1080 pixels. In addition, the size, location and transition effects of the images are also displayed.

To use CImageViewer, ensure that the TV source is designated as the media source. Source transition can be made by setting <srcctl> item to y or through SetMediaSource() method of TVMW Plugin.

For more information about CImageViewer module, see Basic Instructions, Events, Playing Local Files, and Reference.

Specifications

Features Description
Resolution

1920x1080 pixels

Images are displayed in Media source. The display pixel of the application is marked as 960x540 pixels, but that of the displaying image in media source is marked as 1920x1080 pixels.
Supported file format JPEG only
Scaling range Designate the area where an image should be displayed. The image is scaled according to the area you set. Ensure that the resolution is set over 300 pixels. If it is lesser than 300 pixels, images can appear distorted.
Transition Effects

Total 10 modes are provided:

NONE, FADE1, FADE2, BLIND, SPIRAL, CHECKER, LINEAR, STAIRS, WIPE, RANDOM

Basic Instructions

The basic instructions depict setting the location of the images, and scaled display of the images:

Include the common module

The common module is included by putting the code shown below in the <head> of index.html file.

<script type="text/javascript" language="javascript" src="$MANAGER_WIDGET/Common/API/CImageViewer.js"></script>
Create instance

Create ImageViewer instance

var ImageViewer = new CImageViewer('Common ImageViewer');
Initialize ImageViewer

Set the area where images are displayed and functions which will execute each event. The show() method shows the area managed by ImageViewer on screen.

Area designation via setFrameArea() method is executed based on basic resolution (960x540 pixel). The appointed area operates at 1920x1080 pixel resolution.

ImageViewer.setFrameArea(100, 100, 300, 300);
ImageViewer.setOnNetworkError(function() {
    alert('Network error occurs!');
});

ImageViewer.show();
Play images

Play images to ensure that they retain original proportion at the designated areas and they are indicated by scaling.

ImageViewer.play('$WIDGET/picture.jpg', 640, 480);
Close the application

When the application is closed, ImageViewer should be initialized by calling destroy() method.

Note

In case the application is closed without initialization while playing images in ImageViewer, fatal problems such as TV system pause might occur, and it could result in issues for using ImageViewer in other applications.

// Run ImageViewer.destroy() method on <body>'s onunload function
ImageViewer.destroy();
Events
ImageViewer loads various events for precise controlling of image display. You can operate events after registering a function to the corresponding event.

EVENTS

Event Description Function
Buffering start This event occurs during the initiation of image loading (after successful connection with server), if the image you intend to play exists on the Internet. setOnBufferingStart()
Buffering complete This event occurs when the image is ready for display after loading. setOnBufferingComplete()
Rendering complete This occurs when the image is completely displayed on the screen. In case of using a transition effect, this happens when the effect animation has been completed. setOnRenderingComplete()
Network error This event occurs if the image URL cannot be accessed. setOnNetworkError()
Render error This event occurs when image decoding and rendering fails. setOnRenderError()

Playing Local Files

ImageViewer displays images in application or USB as well as on the Internet. A special path starting with $ is necessary to display images from application (files included in application) or USB.

Playing Images in an Application

The $WIDGET string indicates a directory containing an application. Images in the application can be played by sending strings as shown below to ImageViewer.play().

ImageViewer.play('$WIDGET/picture_2.jpg', 640, 480);

Playing Images from USB

The $USB_DIR string indicates USB. The mounting path of USB refers to the USB port at which the USB is mounted in the TV. You need the USB mounting path to display images in USB, because the TV has plural USB ports, and mounting path varies for each USB connection. The location can be found through Storage plugin.

Figuring out the mount route

The Storage plugin finds out the path to mount USB. Complete the root directory path of USB by adding the path to the $USB_DIR string which indicates USB.

// Plugin object Designated
var eStoragePlugin = document.getElementById('pluginObjectStorage');

// Provided that one USB is connected
var deviceId = eStoragePlugin.GetUSBDeviceID(0);

// Provided that USB has one partition
var mountPath = eStoragePlugin.GetUSBMountPath(deviceId, 0);
var USBRootPath = '$USB_DIR/' + mountPath;   // USB root directory path

Your TV has more than two USB ports. You need other functions in the Storage plugin to control more than two USBs or use USB with divided partitions.

Creating file routes

The readDir() API of the browser gives the file information in USB. The readDir() API puts file information on the path in an array and returns it. An example is shown below to refer whether the readDir() returns information of a directory or of a file. For more information about File API, see File API.

var fileSystemObj = new FileSystem();           // Browser API
var dirs = new Array();
var files = new Array();
var data = fileSystemObj.readDir(USBRootPath);  // readDir() returns the array of file information

for (var i = 0; i < data.length; i++) {
    if (data[i].isDir) {
        dirs.push(data[i].name);
    } else {
        files.push(data[i].name);
    }
}

The whole path of image files in USB is created by the file information given above.

var USBImageFile = USBRootPath +'/'+ directory +'/'+ file;

The actual variable of USBImageFile could be the same as below.

var USBImageFile = '$USB_DIR/sda1/myphotos/picture_2.jpg'

Displaying image files in USB

ImageViewer.play(USBImageFile);

Reference

CImageViewer Class

The CImageViewer is a class to play images.

CImageViewer  
Library path $MANAGER_WIDGET/Common/API/CImageViewer.js
Syntax new CImageViewer(objectName:String)
Methods

clearScreen()

destroy()

endSlideshow()

getStopFlag()

hide()

isEffectAvailable()

play()

prepareNext()

setFrameArea()

setOnBufferingComplete()

setOnBufferingStart()

setOnNetworkError()

setOnRenderError()

setOnRenderingComplete()

show()

showNow()

startSlideshow()

stop()
Parameter

objectName:String

Includes names to distinguish generated objects. The debug message from ImageViewer has the name on it.
Return Value CImageViewer object
Remarks

In reality, the TV provides only one ImageViewer. Therefore, it is necessary to create one object of CImageViewer.

If an image is played via ImageViewer, call destroy() while closing the application.

Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
Members Effect

Methods

clearScreen
The clearScreen() method deletes images being displayed on the page.
Syntax ImageViewer.clearScreen();
Parameter None
Return Value None
Enumeration None
Remarks

stop() does not remove the playing image. To delete the image, call clearScreen().

Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.clearScreen();
destroy
The destroy() method pauses the playing image and initializes the ImageViewer.
Syntax ImageViewer.destroy();
Parameter None
Return Value None
Enumeration None
Remarks

If you have used ImageViewer, this function should be called while closing the application. It is recommended that the function registered onunload function of <body> element call this method. The function is called when the application ends.

Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.destroy();
endSlideshow
The endSlideshow() method ends the slideshow mode.
Syntax ImageViewer.endSlideshow();
Parameter None
Return Value None
Enumeration None
Remarks

Call the startSlideshow() method to enter slideshow mode which includes transition effect. The prepareNext() and showNow() methods work only in slideshow mode.

Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.startSlideshow();
    // Use transition effect
    ImageViewer.endSlideshow();
getStopFlag
The getStopFlag() method checks whether the ImageViewer is stopped or not.
Syntax ImageViewer.getStopFlag();
Parameter None
Return Value Boolean If the ImageViewer is stopped, return value is true, if it is operating, return value is false.
Enumeration None
Remarks Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.getStopFlag();
hide
The hide() method hides areas managed by the ImageViewer.
Syntax ImageViewer.hide();
Parameter None
Return Value None
Enumeration None
Remarks Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.show();
    // Play images
    ImageViewer.stop();
    ImageViewer.hide();
isEffectAvailable
The isEffectAvailable() method checks whether a transition effect is available.
Syntax ImageViewer.isEffectAvailable();
Parameter None
Return Value

Boolean

If user settings are feasible for the transition effect, return value is true`, if it is operating, return value is ``false.

Since Application Manager 2.269
Enumeration None
Remarks Some models do not support transition effects due to hardware restrictions. In these models, effect animation is not possible even in the slideshow mode.
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.isEffectAvailable();
play
The play() method plays images.
Syntax ImageViewer.play(url:String, width:Number, height:Number);
Parameter

url:String

Available to display image URL, images in Application and USB.

width:Number

Width unit of an image is pixel. The image is scaled based on the pixels, and displayed in the designated area by setFrameArea(). Slideshow mode does not need this parameter.

height:Number

Height unit of an image is pixel. The image is scaled based on the pixels and displayed in the designated area by setFrameArea(). Slideshow mode does not need this parameter.
Return Value Since Application Manager 2.269
Enumeration None
Remarks Playable image type is JPEG only.
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.setFrameArea(50,50,480,320);
    ImageViewer.play(image_url, image_width, image_height);
prepareNext
The prepareNext() method loads the next image to execute a transition effect in slideshow mode.
Syntax ImageViewer.prepareNext(url:String, effect:ImageViewer.Effect);
Parameter

url:String

Available to display image URL, images in Application and USB.

effect:ImageViewer.Effect

Refer to the transition effect you intend to apply and effect variables in the instance of CImageViewer.
Return Value None
Enumeration None
Remarks

When this method is called, an image starts to load. Effect animation is shown by calling showNow() after the Buffering Complete event.

Some models do not support transition effects due to hardware restrictions. Use isEffectAvailable() to find out if the transition effect is available in your TV.

Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.setFrameArea(0, 0, 960, 540);
    ImageViewer.startSlideshow();
    ImageViewer.play(firstImage, 300, 400);
    // after Rendering complete event
    ImageViewer.prepareNext(NextImage, ImageViewer.Effect.FADE1);
    // after Buffering complete event
    ImageViewer.shwoNow();
    // ...
    // after finishing slideshow
    ImageViewer.endSlideshow();
setFrameArea
The setFrameArea() method sets the area within which images are displayed.
Syntax ImageViewer.setFrameArea(left:Number, top:Number, width:Number, height:Number);
Parameter

left:Number - left coordinate of the area

top:Number - top coordinate of the area

width:Number - width of the area

height:Number - height of the area

The unit is pixel.
Return Value None
Enumeration None
Remarks

For example, if the image is set as setFrameArea(0, 0, 225, 200) and the upper left area of the TV screen is transferred to Media source, images at 450x400 pixels are displayed intact. If an image you intend to display is larger than the standard, it is scaled in accordance with the aspect ratio and displayed in the area.

Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.setFrameArea(0, 0, 480, 320);
    ImageViewer.play(image_url, image_width, image_height);
setOnBufferingComplete
The setOnBufferingComplete() method registers a function executed in case of Buffering complete event while loading an image.
Syntax ImageViewer.setOnBufferingComplete(callback:function);
Parameter

callback:function

The function executed in the event of Buffering complete event.
Return Value None
Enumeration None
Remarks

Buffering complete event occurs after image loading. If this event takes places after calling prepareNext(), it means that the image is ready for the transition effect. At this stage, calling showNow() begins effect animation.

Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.setOnBufferingComplete(function() {
       // Add your code here
    });
setOnBufferingStart
The setOnBufferingStart() method registers a function executed in case of Buffering start event.
Syntax ImageViewer.setOnBufferingStart(callback:function);
Parameter

callback:function

The function executed in the event of Buffering start event.
Return Value None
Enumeration None
Remarks

If the image you intend to play is on the Internet, this event happens when starting to load actual image data after connecting to the server successfully.

Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.setOnBufferingStart(function() {
        // Add your code here
    });
setOnNetworkError
The setOnNetworkError() method registers a function executed in case of Network error event.
Syntax ImageViewer.setOnNetworkError(callback:function);
Parameter

callback:function

The function executed in the event of Network error event.
Return Value None
Enumeration None
Remarks

This event occurs in case of network errors while loading images.

Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.setOnNetworkError(function() {
        // Add your code here
    });
setOnRenderError
The setOnRenderError() method registers a function executed in case of Decoding or Rendering error.
Syntax ImageViewer.setOnRenderError(callback:function);
Parameter

callback:function

The function executed in case of Decoding or Rendering error.
Return Value None
Enumeration None
Remarks

This event takes place when an error occurs while decoding and rendering after buffering and while trying to play a format which is not basically supported (image files except for JPEG).

Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.setOnRenderError(function() {
        // Add your code here
    });
setOnRenderingComplete
The setOnRenderingComplete() method registers a function executed in case of Rendering complete event.
Syntax ImageViewer.setOnRenderingComplete(callback:function);
Parameter

callback:function

The function executed in the event of Rendering complete event.
Return Value None
Enumeration None
Remarks

This event occurs when the image is displayed completely on the screen. If a transition effect is used, the event occurs when effect animation has ended.

Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.setOnRenderingComplete(function() {
        // Add your code here
    });
show
The show() method shows the area managed by ImageViewer on screen.
Syntax ImageViewer.show();
Parameter None
Return Value None
Enumeration None
Remarks Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.show();
    // Play images
    ImageViewer.stop();
    ImageViewer.hide();
showNow
The showNow() method begins to play the transition effect. Loading the image should be ended with the prepareNext() method.
Syntax ImageViewer.showNow();
Parameter None
Return Value None
Enumeration None
Remarks

Some models do not support transition effects due to hardware restrictions. See isEffectAvailable().

Calling prepareNext() starts loading of an image. Effect animation is shown by calling showNow() after Buffering complete event.

Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.setFrameArea(0,0,960,540);
    ImageViewer.startSlideshow();
    ImageViewer.play(firstImage, 300, 400);
    // after Rendering complete event
    ImageViewer.prepareNext(NextImage, ImageViewer.Effect.FADE1);
    // after Buffering complete event
    ImageViewer.shwoNow();
    // ...
    // after finishing slideshow
    ImageViewer.endSlideshow();
startSlideshow
The startSlideshow() method starts the slideshow mode.
Syntax ImageViewer.startSlideshow();
Parameter None
Return Value None
Enumeration None
Remarks

If you want to close slideshow mode, call endSlideshow(). Methods such as prepareNext() and showNow() are available only in slideshow mode.

Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.startSlideshow();
    // Use transition effect
    ImageViewer.endSlideshow();
stop
The stop() method stops image processing.
Syntax ImageViewer.stop();
Parameter None
Return Value None
Enumeration None
Remarks

Stops image processing such as image loading and transition effect animation. To remove playing images from the screen, see clearScreen().

Since Application Manager 2.269
Example 
var ImageViewer = new CImageViewer('Common ImageViewer');
    ImageViewer.setFrameArea(50, 50, 480, 320);
    ImageViewer.play(image_url, image_width, image_height);
    ImageViewer.stop();
 

SAMSUNG

Copyright © 2010 - 2018 SAMSUNG All rights reserved.

Portions of this page are reproduced from work created and shared by the Android Open Source Project
and used according to terms described in the Creative Commons 2.5 Attribution License.