ImageViewer Object

Usage

To use the ImageViewer class in your HTML 5 application:

1. Add a DIV element with a unique ID to your HTML page. This element will act as the parent container for the viewer

2. In your JavaScript code, create a new instance of ImageViewer, passing the DIV element ID into the ImageViewerCreateOptions.ParentDivElementId property.

3. 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 a URL through the ImageUrl property.
• Custom viewing of any canvas or image element. For an example, refer to the BackCanvas and OwnerDraw properties.
• Rich interactive user interface for zooming, panning, scrolling, magnify glass with support for mouse and touch. For more information, refer to DefaultInteractiveMode.
• Automatic horizontal and vertical scroll and pan through the ScrollMode property.
• Determining how the control displays the image and automatic adjustment for viewing when the control size changes using the SizeMode, ImageHorizontalAlignment and ImageVerticalAlignment properties.
• Changing the zoom value used to display the image using the Zoom method.
• Manual adjustment of extra horizontal and vertical stretching values using the AspectRatioCorrection property.
• Support for viewing an image using its actual resolution through the UseDpi property.
• Image viewing transformation using the Flip, Reverse and RotateAngle properties and the Invert method.
• Converting 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 Leadtools.Controls.ImageViewerCreateOptions('myContainerDiv', 'myViewer');
            var viewer = new Leadtools.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:

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, you can use these elements through the corresponding property directly:

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 background canvas is created and populated with the image data, the ImageSize is set accordingly, the transformation matrix in Transform is re-calculated, the ImageChanged event will fire and finally a render is requested. 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 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 two canvas elements, a 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 transformation and effects.

The other element is the background canvas (BackCanvas). This canvas is created when the user sets an image in the viewer and 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:

1. First, the viewer will determine whether the BeginUpdate method has been called without a matching EndUpdate method.

2. If so, the EraseBackground event is fired and the background of the fore canvas is cleared.

3. Then the PreRenderImage event is fired.

4. The content of the background canvas is drawn onto the foreground canvas using the current transformation matrix (Transform)

5. Then the PostRenderImage event is fired.

If you set the value of OwnerDraw to true, then the viewer will not draw the background canvas onto the foreground canvas (step 5 above). This can be used 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.