Class s7sdk.image.ZoomView

The ZoomView is an image viewing component that displays an image served by Adobe Scene7 Image Serving. A user can zoom in/out the displayed image by interacting with it in one of the predefined ways. The image can also change its zoomed state through available API calls like zoomIn() and zoomOut(). On mobile devices that support multi-touch, pinching in and out is the most common way to interact with the image. Other interaction options are single and/or double clicks/taps. The interpretation of these actions is controlled by the singleClick and doubleClick modifiers.

ZoomView supports three types of frame change animation: instant image swap, fade and horizontal slide transition; the type of animation is controlled with frametransition modifier. Frame change may occur because of setItem(), setAsset() API calls or due to horizontal swipe or flick gesture according to swipe modifier.

On desktop systems, ZoomView component supports custom mouse cursors. The type of the cursor depends on component state and user action, the following types are supported:

default - displayed when the image is not zoomable because of small image resolution and/or component settings;
zoomin - displayed when the image can be zoomed in;
reset - displayed when the image is at maximum zoom level and can be reset to initial state;
drag - displayed when user pans the image which is in zoomed in state;
slide - displayed when user performs image swap by doing horizontal swipe or flick.

The appearance of custom cursor is controlled with CSS by setting cursor property for .s7zoomview class with corresponding value for cursortype attribute selector. By default all cursors are set to default.

Customizing Behavior Using Modifiers

Modifiers change ZoomView default behavior. They are passed to the component by the ParameterManager instance specified in the constructor.

The following modifiers are supported:

Modifier	Syntax	Description	Default
serverurl	isRootPath	The Image Serving root path. If no domain is specified, the domain from which the page is served is applied instead. Standard URI path resolution applies.	/is/image/
asset	image	The Image Serving catalog/image ID of the image to display.
iscommand	value	The Image Serving command string that is applied to the image when requesting image data. If specified in the URL, all occurrences of '&' and '=' must be HTTP-encoded as `%26` and `%3D`, respectively.
zoomstep	step[,limit]	Configures how many zoom in and zoom out actions are required to increase or decrease the resolution by a factor of two. The resolution change for each zoom action is 2^1 per step. Set to 0 to zoom to full resolution with a single zoom action. Use `limit` to specify the maximum zoom resolution, relative to the full resolution image. The default is 1.0, which does not allow zooming beyond full resolution.	1,1
transition	[time][,easing]	Time specifies the time in seconds that the animation takes for a single zoom step action. Use easing to create an illusion of acceleration or deceleration which makes the transition appear more natural. You can set easing to one of the following: 0 (auto), 1 (linear), 2 (quadratic), 3 (cubic), 4 (quartic), 5 (quintic). Auto mode always uses linear transition when elastic zoom is disabled (default). Otherwise, it fits one of the other easing functions based on the transition time. That is, the shorter the transition time the higher the easing function is used to quicken the acceleration or deceleration effect.	0.5,0
frametransition	none\|fade\|slide[,duration[,spacing]]	Specifies the type and duration of the effect that is applied on frame change. Use `none` for no transition; that is, frame change occurs instantly. Use `fade` for a cross-fade transition between old and new frames, with transition duration in seconds controlled by duration. Use `slide` to activate the transition where the old frame slides out of the view and the new frame slides in. Slide animation duration is controlled in seconds by the duration element. The spacing between adjacent frames is controlled with spacing. The spacing has the range between `0` and `1` and is relative to the component's width.	none
rgn	x,y,w,h	The initial region of interest in pixel coordinates. If not specified, the entire image is fitted within the initial viewport unless you adjusted the `reset` modifier.
rgnN	x,y,w,h	The initial region of interest in normalized coordinates. If not specified, the entire image is fitted within the initial viewport unless you adjusted the `reset` modifier.
singleclick	none\|zoom\|reset\|zoomReset	Configures the mapping of single-click or tap-to-zoom actions. Set to `none` to disable single-click or tap zoom. If set to `zoom`, then clicking the image zooms in one zoom step; CTRL+Click zooms out one zoom step. Set to `reset` to cause a click on the image to reset the zoom to the initial zoom level. For `zoomReset`, reset is applied if the current zoom factor is at or beyond the specified limit. Otherwise, zoom is applied.	none
doubleclick	none\|zoom\|reset\|zoomReset	Configures the mapping of double-click or tap-to-zoom actions. Setting to `none` disables double-click or tap reset. If set to `zoom`, clicking the image zooms in one zoom step; CTRL+Click zooms out one zoom step. Use `reset` to cause a click on the image to reset the zoom to the initial zoom level. For `zoomReset`, reset is applied if the current zoom factor is at, or beyond, the specified limit. Otherwise, `zoom` is applied.	zoomReset
swipe	0\|1	Configures the component response to a horizontal swipe or a flick gesture. If set to `1` the component performs an image change in response to a horizontal swipe or flick. When set to `0`, swipe or flick gestures only affect image panning.	1
reset	0\|1	Resets the viewport when the frame (image) changes. If set to 0, it preserves the current viewport with the best possible fit while preserving the aspect ratio of the newly set image.	1
iconeffect	0\|1[,count][,fade][,autoHide]	Enables the IconEffect to display above the image when the image is in a reset state and is in a high enough resolution to allow zooming. Such functionality is suggestive of available action to interact with the image. The count specifies the maximum number of times the icon overlay appears and reappears. A value of -1 indicates that the overlay always reappears indefinitely. The fade specifies the duration of show and hide animation, in seconds. The autoHide sets number of seconds that IconEffect stays visible before it auto-hides. That is, the time after fade in animation is completed and before fade out animation starts); 0 disables auto-hide behavior.	1,1,0.3,3
enableHD	always\|never\|limit,number	Enable, limit, or disable optimization for devices where devicePixelRatio is greater than 1 such as devices with a high-density display like iPhone4 and similar devices. If activated, the component limits the size of the IS image request as if the device had a pixel ratio of one thereby reducing the bandwidth. If using the limit setting, the component enables high pixel density only up to the specified limit.	limit,1500
fmt	jpg\|jpeg\|png\|png-alpha\|gif\|gif-alpha	Specifies the image format used by the component for loading images from Image Server. If the specified format ends with "-alpha", the component renders images as transparent. For all other image formats, the component treats images as opaque. Note that the component has a white background by default. Therefore, to make it completely transparent set the `background-color` CSS property to `transparent`	jpeg

Defining the Appearance using CSS

You can define the appearance of the ZoomView component using CSS rules. All HTML5 Viewer SDK components use class selectors for styling. You can define the appearance of the ZoomView component using the .s7zoomview class selector. The styles associated with this class selector are applied to all instances of the ZoomView component. You can style particular instances by prefixing the class rule with the instance #id. For example, styling rules for #myComp.s7zoomview are applied only to the particular ZoomView instance.

The styling of the sub-elements using class selectors like .s7iconeffect for example, must be specified in the form of the descendant class selectors, that is, they must follow the main class selector separated by a space, such as .s7zoomview .s7iconeffect. For more information on component styling see the HTML5 Viewer SDK User Guide and the default styles section.

CSS Class	Attribute Selector	Description
`.s7zoomview`	`cursortype=[default\|zoomIn\|reset\|drag\|slide]`	Represents the main body of the `ZoomView` component. The `cursortype` allows setting different custom cursor types.
`.s7iconeffect`	`media-type=[standard\|multitouch]`	Defines the appearance of the IconEffect.

Localized Symbols

ZoomView also has text symbols that you can localize either in a preset or in the viewer page though the mechanisms provided by the ParameterManager. For more information on localization consult the ParameterManager API documentation and HTML5 Viewers SDK User Guide.

Symbol	Description
`ZoomView.ROLE_DESCRIPTION`	Define a localized "aria-roledescription" of `ZoomView`
`ZoomView.USAGE_HINT`	Define a localized text for "aria-describedby" of `ZoomView`

Class Summary
Constructor Attributes	Constructor Name and Description
	s7sdk.image.ZoomView(container, settings, compId)

Field Summary
Field Attributes	Field Name and Description
	getAsset read-only The asset that is currently displayed in the viewer.

Method Summary
Method Attributes	Method Name and Description
	addEventListener(type, handler, useCapture) Adds an event listener to the instance of the `ZoomView` component.
	dispose() Dispose is used to remove itself and all sub-elements from the DOM
	getCapabilityState() Gets current capability state of the image view.
	getHeight() Returns the current inner height of the component.
	getWidth() Returns the current inner width of the component.
	resize(width, height) Sets the ZoomView to the specified width and height.
	setAsset(assetName) Changes the currently active asset/set.
	setCSS(classname, property, value) Sets a particular CSS class and property on a component
	setItem(item) Sets the current item displayed by the component.
	setModifier(modObj) Sets 1-N # of modifiers for the component.
	zoomIn() Zooms in one level.
	zoomNPan(dx, dy) Move the displayed portion of the zoomed in image by a specified amount.
	zoomNRgn(rgn) Display the specified image region in the view area and adjust the zoom level accordingly.
	zoomOut() Zooms out one level.
	zoomReset() Reset the view to its initial zoom state.
	zoomRgn(rgn) Display the specified image region in the view area and adjust the zoom level accordingly.

Class Detail

s7sdk.image.ZoomView(container, settings, compId)

Example Code
This example demonstrates how to use the ZoomView component in a simple viewer. In this example a Container object,
a ZoomView object, a ZoomInButton object, and a ZoomOutButton object, and a ZoomResetButton object are created. When
a user interacts with the ZoomView object, causing it to zoom in or out on the image, the zoom buttons become enabled
or disabled as appropriate for the current zoom level of the image. When a user clicks any of the zoom buttons,
the ZoomView object zooms the image in or out as appropriate.

The code below does the following:

The Scene7 HTML5 SDK is linked to the page and the required s7sdk components are included in the document head.
CSS Styles are defined in the document head to control the appearance of the ZoomView and button components.
The s7sdk.Util.init() method is called to initialize the SDK.
A ParameterManager object is created to handle component modifiers for the viewer.
An initViewer() function is defined. This function initializes a couple of modifiers (hard coded for example purposes),
then creates the component objects required for this simple example. The initViewer() function also adds event listeners
that designate functions to handle relevant component events (which might be dispatched by the components as a result of
user interactions, changes in a component's state, etc.).
Handler functions are defined to respond to the component event listeners added in the initViewer() function.
An event listener is added to the ParameterManager object that designates the initViewer() function as the handler
to call when the Scene7 SDK is loaded and ready.
Finally, the init() method is called on the ParameterManager object to start the viewer.

<!DOCTYPE html>
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <meta name="viewport" content="width=device-width" />

        <title>ZoomView Component</title>

        <!-- To run this example locally you need to replace this with an absolute
        SDK path.  For more information check the HTML5 Viewers SDK User Guide or
        the examples included in the package.
        -->
        <script language="javascript" type="text/javascript"
                src="../js/s7sdk/utils/Utils.js"></script>
        <script language="javascript" type="text/javascript">
            s7sdk.Util.lib.include('s7sdk.image.ZoomView');
            s7sdk.Util.lib.include('s7sdk.common.Container');
            s7sdk.Util.lib.include('s7sdk.common.Button');
        </script>

        <style type="text/css" media="screen">
            html,body {
                width: 100%;
                height: 100%;
            }
            body {
                margin: 0px;
                padding: 0px;
            }	
            .s7zoomview {
                top: 0px;
                left: 0px;
                height: 400px;
                width: 280px;
            }
            .s7zoominbutton{
                position: absolute;
                top: 375px;
                left: 10px;
                width: 25px;
                height: 25px;
                z-index: 5000;
            }
            .s7zoomoutbutton {
                position: absolute;
                top: 375px;
                left: 250px;
                width: 25px;
                height: 25px;
                z-index: 5000;
            }
            .s7zoomresetbutton {
                position: absolute;
                top: 375px;
                left: 127px;
                width: 25px;
                height: 25px;
                z-index: 5000;
            }
        </style>
    </head>
    <body>
        <div id="s7container"></div>

        <script language="JavaScript" type="text/javascript">
            var params, container, zoomView, zoomInButton, zoomOutButton, zoomResetButton;

            // Initialize the SDK
            s7sdk.Util.init();

            // Create ParameterManager instance to handles modifiers		
            params = new s7sdk.ParameterManager();
                
            // Define the function that initializes the viewer
            function initViewer(){
                // Set hardcoded modifiers (not required when values are specified on the url)
                params.push("serverurl", "http://s7d1.scene7.com/is/image");
                params.push("asset", "demo/bedroom.tif");

                // Create the Container component object
                container = new s7sdk.Container(null, params, "s7container");

                // Create the ZoomView component object
                zoomView = new s7sdk.image.ZoomView( container, params, "zoomView");
                
                // Create the ZoomInButton component object
                zoomInButton = new s7sdk.common.ZoomInButton(container, params, "zoomInButton");

                // Create the ZoomOutButton component object
                zoomOutButton = new s7sdk.common.ZoomOutButton(container, params, "zoomOutButton");

                // Create the ZoomResetButton component object
                zoomResetButton = new s7sdk.common.ZoomResetButton(container, params, "zoomResetButton");

                // Add an event listener for zoom capability state changes
                zoomView.addEventListener(s7sdk.event.CapabilityStateEvent.NOTF_ZOOM_CAPABILITY_STATE, onZoomStateChange);

                // Add event listeners for all zoom button click events
                zoomInButton.addEventListener("click", onZoomIn);
                zoomOutButton.addEventListener("click", onZoomOut);
                zoomResetButton.addEventListener("click", onZoomReset);
            }

            // Define an event handler function to enable/disable the zoom buttons when the ZoomView state changes
            function onZoomStateChange(event){
                if(event.s7event.state.hasCapability(s7sdk.ZoomCapabilityState.ZOOM_IN)){
                    zoomInButton.activate();
                }else{
                    zoomInButton.deactivate();
                }
                if(event.s7event.state.hasCapability(s7sdk.ZoomCapabilityState.ZOOM_OUT)){
                    zoomOutButton.activate();
                }else{
                    zoomOutButton.deactivate();
                }
                if(event.s7event.state.hasCapability(s7sdk.ZoomCapabilityState.ZOOM_RESET)){
                    zoomResetButton.activate();
                }else{
                    zoomResetButton.deactivate();
                }
            }

            // Define an event handler function to update the ZoomView when zoomIn is clicked
            function onZoomIn(event){
                zoomView.zoomIn();
            }

            // Define an event handler function to update the ZoomView when zoomOut is clicked
            function onZoomOut(event){
                zoomView.zoomOut();
            }

            // Define an event handler function to reset the ZoomView zoom level
            function onZoomReset(event) {
                zoomView.zoomReset();
            }

            // The ParameterManager will dispatch SDK_READY when all modifiers have been processed
            // and it is safe to initialize the viewer		
            params.addEventListener(s7sdk.Event.SDK_READY, initViewer, false);

            // Now it is safe to process the modifiers, the callbacks have been defined
            // this will trigger the SDK_READY event
            params.init();
        </script>

    </body>
</html>

Default styles for ZoomView:

.s7zoomview {
	width: 400px;,
	height: 400px;
	position:absolute;
	background-color:#FFFFFF;
	user-select:none;
	-moz-user-select:-moz-none;
	-webkit-user-select:none;
	-webkit-tap-highlight-color:rgba(0,0,0,0);
	text-align: left;
 }
.s7zoomview img {
	max-width:none;
	max-height:none;
 }
.s7zoomview[cursortype='default'] {
	cursor:default;
 }
.s7zoomview[cursortype='zoomin'] {
	cursor:default;
 }
.s7zoomview[cursortype='reset'] {
	cursor:default;
 }
.s7zoomview[cursortype='drag'] {
	cursor:default;
 }
.s7zoomview[cursortype='slide'] {
	cursor:default;
 }
.s7zoomview .s7iconeffect {
	width:120px;
	height:120px;
	-webkit-transform:translateZ(0px);
	background-repeat:no-repeat;
	background-position:center;
 }
.s7zoomview .s7iconeffect[media-type='standard'] {
	background-image:url(images/sdk/doubletapicon.png);
 }
.s7zoomview .s7iconeffect[media-type='multitouch'] {
	background-image:url(images/sdk/zoomicon.png);
 }

Parameters:
{String|Container} container: The reference to Container instance or the ID of the parent DOM element to which the component is added as a child
{s7sdk.ParameterManager} settings: A parameter manager instance that represents the desired configuration.
{String} compId: An optional parameter that specifies the ID of the components DOM element

Field Detail

{String} getAsset

read-only The asset that is currently displayed in the viewer.

Method Detail

addEventListener(type, handler, useCapture)

Adds an event listener to the instance of the ZoomView component. The handler function receives a DOM event object of type Event. The object contains a property s7event, which references the associated custom event object, for example s7sdk.event.CapabilityStateEvent.

The events supported by the component are:

s7sdk.event.ZoomPanEvent.NOTF_ZOOM_PAN - Dispatched when the view is panned. s7sdk.event.ZoomPanEvent

s7sdk.event.ZoomPanEvent.NOTF_ZOOM_NPAN - Dispatched when the view is panned. s7sdk.event.ZoomPanEvent

s7sdk.event.ZoomRgnEvent.NOTF_ZOOM_RGN - Dispatched when the current view region changes. s7sdk.event.ZoomRgnEvent

s7sdk.event.ZoomRgnEvent.NOTF_ZOOM_NRGN - Dispatched when the current view region changes. s7sdk.event.ZoomRgnEvent

s7sdk.event.AssetEvent.ASSET_CHANGED - Dispatched when the currently displayed image changes. s7sdk.event.AssetEvent

s7sdk.event.CapabilityStateEvent.NOTF_ZOOM_CAPABILITY_STATE - Dispatched when image zoom state has changed due to zooming or resizing. s7sdk.event.CapabilityStateEvent

s7sdk.event.StatusEvent.NOTF_ASSET_METADATA_READY - Dispatched when component receives asset metadata. If the component is initialized with setItem() it dispatches instantly inside that API call. Otherwise if the component loads req=set on its own, this event is sent when component has received and parsed req=set. s7sdk.event.StatusEvent

s7sdk.event.StatusEvent.NOTF_VIEW_READY - Dispatched when component fills the view entirely with image data (either low-resolution tile or high-resolution overview image loads and displays - whatever comes first). It is sent only after asset swap and not during zoom/pan operations. s7sdk.event.StatusEvent

s7sdk.event.StatusEvent.NOTF_HIGHRES_VIEW_READY - Dispatched when component fills the view with high resolution image. The event is sent only once per asset swap, when the view is filled with high resolution image data for the first time after asset was set or changed. This event is not sent later, when user zooms or pans. s7sdk.event.StatusEvent

Parameters:
{String} type: Event name, for example s7sdk.event.CapabilityStateEvent.NOTF_ZOOM_CAPABILITY_STATE.
{Function} handler: Function to be called when the event gets dispatched.
{Boolean} useCapture: Register capture phase.

dispose()

Dispose is used to remove itself and all sub-elements from the DOM

{ZoomCapabilityState} getCapabilityState()

Gets current capability state of the image view. This state changes internally due to zooming or resizing. For example if the image is fully zoomed out, both s7sdk.ZoomCapabilityState.ZOOM_OUT and s7sdk.ZoomCapabilityState.ZOOM_RESET will not be present since the image cannot be reset into its initial zoom state or zoomed out. That is, the reset and zoom out operations will be no op, since the image is already in reset and fully zoomed out state.

Returns:: Current image zoom state.

See:: s7sdk.ZoomCapabilityState

{Number} getHeight()

Returns the current inner height of the component.

Returns:: {Number} the inner height of the component, in pixels.

{Number} getWidth()

Returns the current inner width of the component.

Returns:: {Number} the inner width of the component, in pixels.

resize(width, height)

Sets the ZoomView to the specified width and height.

Parameters:
{Number} width: - The width of the component, in pixels.
{Number} height: - The height of the component, in pixels.

setAsset(assetName)

Changes the currently active asset/set. The component invalidates and rebuilds using the existing serverurl and the new asset after retrieving the asset/set definition from Image Serving. Unless the asset has not been set already, this call generates a SWAP tracking event that is managed by the TrackingManager component. Preferred way of changing the displayed image though is by simply calling setItem() API.

Parameters:
{String} assetName: - The catalog ID of the asset/set.

See:: s7sdk.TrackingManager

setCSS(classname, property, value)

Sets a particular CSS class and property on a component

Parameters:
{String} classname: The CSS classname to use for this style. i.e. .s7zoomview
{String} property: The CSS property that is being set. i.e. background-color
{String} value: The CSS property value being set. i.e. #FF0000

setItem(item)

Sets the current item displayed by the component. The item must be a decedent of type ItemDesc. An exception is thrown if the item does not reference a parent set, or is not descendant of type ItemDesc. Calling this method will dispatch the AssetEvent.ASSET_CHANGED event.

Parameters:
item: {s7sdk.ItemDesc} The set item to select.

See:: s7sdk.ItemDesc; s7sdk.event.AssetEvent

setModifier(modObj)

Sets 1-N # of modifiers for the component.

Parameters:
{Object} modObj: A simple JSON object with name:value pairs of valid modifiers for a particular component

zoomIn()

Zooms in one level. This action is equivalent to clicking/tapping on the image. Use zoomstep modifier to set the resolution change for each zoom action.

zoomNPan(dx, dy)

Move the displayed portion of the zoomed in image by a specified amount. The image is displaced both horizontally and vertically as specified by dx and dy parameters which are in normalized image coordinates where 0,0 represents the upper left corner and 1,1 represents the lower right corner of the image.

Parameters:
{Object} dx: If dx > 0 the image is moved to the right, if dx < 0 the image is moved to the left.
{Object} dy: If dy > 0 the image is moved down, if dy < 0 the image is moved up.

zoomNRgn(rgn)

Display the specified image region in the view area and adjust the zoom level accordingly. This operation will fit the specified region into the ZoomView viewing area the best way possible without distorting the image. That is, the specified region will be modified if necessary in order to preserve the image aspect ratio.

Parameters:
{Rectangle} rgn: The image region in normalized image coordinates where 0,0 represents the top left corner and 1,1 represents the bottom right corner of the image.

zoomOut()

Zooms out one level. This action is equivalent to CTRL-clicking on the image. Use zoomstep modifier to set the resolution change for each zoom action.

zoomReset()

Reset the view to its initial zoom state.

zoomRgn(rgn)

Parameters:
{Rectangle} rgn: Image region to zoom into in image top resolution coordinates.

Namespaces

Classes in s7sdk.image

Class s7sdk.image.ZoomView