ImageViewer Object

JavaScript

function Leadtools.Controls.ImageViewer()

Usage

To use the ImageViewer class in your HTML 5 application:

Add a DIV element with a unique ID to your HTML page. This element will act as the parent container for the viewer
In your JavaScript code, create a new instance of ImageViewer, passing the DIV element ID into the ImageViewerCreateOptions.ParentDivElementId property.
Start using the control. For example, set the URL to an image file into the ImageUrl property.

Features

ImageViewer supports the following functionality:

View an image using an URL through the ImageUrl property.
Customize the view for any canvas or image element. For an example, refer to the BackCanvas and OwnerDraw properties.
Use a rich interactive user interface to zoom, pan, scroll and use a magnify glass; all with support for mouse and touch. For more information, refer to DefaultInteractiveMode.
Perform automatic horizontal and vertical scrolling and panning through the ScrollMode property.
Determine how the control displays the image and automatically adjust the view when the control size changes. For more information, refer to the SizeMode, ImageHorizontalAlignment and ImageVerticalAlignment properties.
Change the zoom value used to display the image using the Zoom method.
Manually adjust extra horizontal and vertical stretching values using the AspectRatioCorrection property.
View an image using its actual resolution through the UseDpi property.
Perform image view transformations using the Flip, Reverse and RotateAngle properties and the Invert method.
Convert a point or a rectangle between image (logical) and control (display or physical) coordinates using the ConvertPoint and ConvertRect methods.

Components

ImageViewer requires that your browser supports the HTML 5 canvas element.

To understand the various elements of the ImageViewer, consider the example where you have the following HTML:


            <div id="myContainerDiv"></div>

In your JavaScript, use the following code to create the viewer:


            // Create the viewer
            var createOptions = new lt.Controls.ImageViewerCreateOptions('myContainerDiv', 'myViewer');
            var viewer = new lt.Controls.ImageViewer(createOptions);

This will result in the following HTML:


            <div id="myContainerDiv">
              <!-- This is DIV -->
              <div id="myViewer_div">
                 <!-- The viewer auto scroll DIV, this will not be created for mobile or tablet devices -->
                 <div id="myViewer_autoScrollDiv"></div>
              </div>
              <!-- The viewer canvas (foreground) -->
              <canvas id="myViewer_canvas"></canvas>
            </div>

From the above, you can deduce that creating an image viewer inside a DIV will add the following elements to your HTML page:

Element	ID (as string)	ImageViewer property ID	Description
Main viewer DIV	ImageViewerCreateOptions.ControlId_div	DivId	The main viewer DIV. You can customize this DIV element by providing the name of the CSS class to use in the ImageViewerCreateOptions.DivClassName property.
Auto scroll DIV	ImageViewerCreateOptions.ControlId_autoScrollDiv	AutoScrollDivId	The auto scroll DIV is used in desktop browsers only to show and control the size of the scroll bars. Mobile and tablet browsers do not support scrollbars and this DIV will not be created. Panning is supported in either case. Customize this DIV element by providing the name of the CSS class to use in the ImageViewerCreateOptions.AutoScrollDivClassName property.
Foreground Canvas	ImageViewerCreateOptions.ControlId_canvas	CanvasId	The foreground canvas. The current image will be drawn into the surface of this canvas. Ccustomize this Canvas element by providing the name of the CSS class to use in the ImageViewerCreateOptions.CanvasClassName property.

In addition to these elements, the image viewer will create the following elements that are not added to the HTML page but are required for the viewer operation. Since these elements are not added to the page, they do not use an ID. However, Use these elements through the corresponding property directly:

Element	ImageViewer Property	Description
Background Image	BackImage	The background image. The current image will be drawn onto the surface of this image and then applied to the foreground canvas when needed. This property will be populated when an image is set in an ImageUrl while the value of UseBackCanvas is false.
Background Canvas	BackCanvas	The background canvas. The current image will be drawn onto the surface of this canvas and then applied to the foreground canvas when needed. Owner draw can also be used to manually draw an image or any other shape on the back canvas. This property will be populated when an image is set in ImageUrl while value of UseBackCanvas is true or on owner draw mode when the value of ImageSize is set manually.

Viewing an Image

Use one of the following methods to view an image with the ImageViewer:

Enter the URL of the image into the ImageUrl property. This is easiest and most convenient way. The viewer will create an internal HTML image element and try to load the image data. If successful, the ImageSize is set accordingly, the transformation matrix in Transform is re-calculated, the ImageChanged event will fire and finally a render will be requested. At any time, query the BackImage or BackCanvas properties to get the source image or background canvas elements. Refer to ImageUrl for an example.
View a custom image by drawing on the background canvas directly. Using this method, set the ImageSize to the required pixel size; this causes the background canvas to be created with the requested size and empty data. At any time, query the BackCanvas property to get the canvas element, obtain a context drawing to it and draw your custom image. Refer to BackCanvas for an example.

Rendering

As described in the Components section, the image viewer contains the foreground canvas (its ID is stored in the CanvasId) that is created when the viewer initializes and is added to the HTML page inside the main DIV element. This canvas will always be the same size as the current viewable area of the viewer (not the entire image size) to optimize rendering and allow the viewer to display images that are much greater in size than the maximum allowed by the browser. This canvas displays the current image view with any transformations and effects.

The other element is the optional background image element (BackImage). This image element is created when the user sets an image in the viewer using the ImageUrl property while the value of UseBackCanvas is false and is never added to the HTML page.

The final element is the optional background canvas element (BackCanvas). This canvas element is created when the user sets an image in the viewer using the ImageUrl property while the value of UseBackCanvas is true or when owner drawing is performed by setting the ImageSize property manually (it is never added to the HTML page). The size of this canvas is the same size as the image. Since this canvas is never added to the page, it has no restriction on size.

Setting a new image, zooming in, and applying an effect are all actions that will cause the viewer to re-calculate the transformation matrix (Transform) and call the OnTransformChanged method. This method will call the Invalidate method and cause the viewer to be in an invalid state that requires rendering. TheInvalidate method can also be called manually to trigger a render.

When the viewer is invalidated, the following occur:

First, the viewer will determine whether the BeginUpdate method has been called without a matching EndUpdate method.
If so, the EraseBackground event is fired and the background of the fore canvas is cleared.
Then the PreRenderImage event is fired.
The content of the background image or canvas is drawn onto the foreground canvas using the current transformation matrix. (Transform)
Then the PostRenderImage event is fired.

If you set the value of OwnerDraw to true, then the viewer will not draw the background image or canvas onto the foreground canvas (step 5 above). Use this to implement custom painting on the foreground canvas directly.

Use the PostRenderImage method to add extra drawing on top of the image, such as annotations or labels.

Notes

The ImageViewer will add HTML elements to the page and subscribe to multiple JavaScript events. If your application involves adding and removing ImageViewer objects from the page, then you must call the Dispose method to remove the object from the page and clean up any resources being used.

The viewer hooks up to the standard HTML Window "sizechanged" or "orientationchange" events, depending on which browser being used. This allows the viewer to recalculate the transformation matrix and cause rendering if the size of the control (container DIV) changes. If however, the size of the control is changed programmatically or due to CSS rules that do not fire a "sizechanged" or "orientationchange" event, then the control will not be updated. You must call the OnSizeChanged method to trigger the control to update its transformation.

This example will create an ImageViewer, set the interactive mode to Pan/Zoom and then add an image to it.

To run this example take the following steps:

Copy and paste this example into your favorite text editor and save it as an HTML file with any name, such as Default.htm, to a folder on your disk.
Inside that folder containing the new HTML file, create a directory with the name "Scripts".
Copy the required .js files in the example from "LEADTOOLS Installation Folder\Bin\JS" to "Scripts".
Finally, open the HTML file in any browser that supports HTML 5.

JavaScript

<!DOCTYPE html>
<html>
<head>
   <title>Leadtools Examples</title>
   <meta http-equiv="X-UA-Compatible" content="IE=9" />
   <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=0, minimum-scale=1.0, maximum-scale=1.0" />
   <meta name="apple-mobile-web-app-capable" content="yes" />
   <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
   <style>
      #imageViewerDiv
      {
         border: 1px solid #000000;
         width: 400px;
         height: 400px;
         background-color: #7F7F7F;
      }
   </style>
   <script type="text/javascript" src="Scripts/Leadtools.js"></script>
   <script type="text/javascript" src="Scripts/Leadtools.Controls.js"></script>
   <script type="text/javascript">
      (function () {
         DefaultPage = function DefaultPage() {
         }

         DefaultPage.prototype = {

            example: function SiteLibrary_DefaultPage$example(viewer) {
               // TODO: add example code here
               alert("example code goes here");
            },

            run: function SiteLibrary_DefaultPage$run() {
               // Create the viewer
               var createOptions = new lt.Controls.ImageViewerCreateOptions("imageViewerDiv", "myViewer");
               var viewer = new lt.Controls.ImageViewer(createOptions);

               // Set the interactive mode to PanZoom
               var interactiveMode = new lt.Controls.ImageViewerPanZoomInteractiveMode();
               viewer.set_defaultInteractiveMode(interactiveMode);

               // Set the image URL
               viewer.set_imageUrl("http://www.leadtools.com/images/boxshots/leadtools-200x250.jpg");

               var exampleButton = document.getElementById("exampleButton");
               var _this = this;
               exampleButton.addEventListener("click", function(e) {
                  _this.example(viewer);
               }, false);
            },

            dispose: function SiteLibrary_DefaultPage$dispose() {
            },
         }

         DefaultPage.registerClass("DefaultPage", null, ss.IDisposable);
         var page = null;
         var windowLoad = null;
         var windowUnload = null;
         windowLoad = function (e) {
            window.removeEventListener("load", windowLoad, false);
            page = new DefaultPage();
            page.run();
            window.addEventListener("unload", windowUnload, false);
         };
         windowUnload = function (e) {
            window.removeEventListener("unload", windowUnload, false);
            page.dispose();
         };
         window.addEventListener("load", windowLoad, false);
      })();
   </script>
</head>
<body>
   <p>Press and drag on the image to pan</p>
   <p>Hold down the control key and press and drag on the image or pinch with two fingers to zoom in and out</p>
   <div>
      <input type="button" id="exampleButton" value="Example" />
      <label id="exampleLabel" />
   </div>
   <div id="imageViewerDiv" />
</body>
</html>