Image Viewer Items

ImageViewer supports one or more items with each containing its own image data, size and optional additional transformation.

Using Items

To access the items, use the ImageViewer.Items property. This is of type ImageViewerItems which implements standard ICollection and IList interfaces to easily add/remove/get/set and enumerate the items:

When an items list or the properties of an item has changed, the following events occur in the image viewer:

In addition to the above standard collection operations, ImageViewerItems supports the following:

In Elements Mode, the following methods are also available:

The items are arranged for viewing using the layout system. For more information, refer to Image Viewer Layouts.

A new item can be added to the viewer using any of the following:

• From raster or SVG image data in an HTML Image Element

• From raster image data in an HTML5 Canvas Element

• From a URL containing raster or SVG image data

• Empty item (without any image data, just size information)

For the code snippets below, replace the code used in Using Image Viewer with HTML5 and JavaScript with the snippet below then add the code described. Assume imageViewer is the ID of a div in the HTML page.

Generic Code

// Get the div item for the viewer 
var div = document.getElementById("imageViewer"); 
// Create a new image viewer instance with a vertical layout 
var createOptions = new lt.Controls.ImageViewerCreateOptions(div); 
createOptions.viewLayout = new lt.Controls.ImageViewerVerticalViewLayout(); 
var imageViewer = new lt.Controls.ImageViewer(createOptions); 
// Add a border (need some padding as well) 
imageViewer.imageBorderThickness = 1; 
// Add some padding 
imageViewer.itemPadding = lt.Controls.ControlPadding.createAll(80); 
// Use a border around the items so we can see them 
imageViewer.itemBackgroundColor = "yellow"; 
imageViewer.itemBorderThickness = 1; 
// Add pan/zoom interactive mode. Click and drag to pan the image and ctrl-click 
// and drag to zoom in/out 
imageViewer.interactiveModes.add(new lt.Controls.ImageViewerPanZoomInteractiveMode()); 

Adding and Removing Items

The following code will create a new item, load a PNG file as an HTML Image Element, set the image to the item, and add the item to the viewer:

// Load an image into it 
var img = new Image(); 
img.onload = function () { 
   // Create an item 
   var item = new lt.Controls.ImageViewerItem(); 
   // Set the image 
   item.image = img; 
   // Add it to the viewer 
   imageViewer.items.add(item); 
} 
img.src = "http://localhost/images/image1.png"; 

Or by letting the viewer load it by setting the URL:

// Create an item 
var item = new lt.Controls.ImageViewerItem(); 
// Set the URL 
item.url = "http://localhost/images/image1.png"; 
// Add it to the viewer 
imageViewer.items.add(item); 

You can also use the method of ImageViewerItems to add the items directly without creating an ImageViewerItem instance:

// Add an item directly 
// Load an image into it 
var img = new Image(); 
img.onload = function () { 
   imageViewer.items.addFromImage(img, lt.LeadSizeD.empty); 
} 
img.src = "http://localhost/images/image1.png"   /// 

Or from a url directly without creating an HTML Image Element:

// Add an item directly from a url 
imageViewer.items.addFromUrl("http://localhost/images/image1.png", lt.LeadSizeD.empty); 

Or from an HTML5 Canvas Element

var canvas = document.createElement("canvas"); 
canvas.width = 200; 
canvas.height = 200; 
var ctx = canvas.getContext("2d"); 
ctx.fillStyle = "red"; 
ctx.fillRect(0, 0, 200, 200); 
imageViewer.items.addFromCanvas(canvas, lt.LeadSizeD.empty); 

In the cases above, you can easily obtain the item added for further modification by using the return value from the methods or accessing the ImageViewer.Items collection.

ImageViewer also supports adding SVG images allowing smooth zooming with pixelazation. They can be SVG files directly or when using the LEADTOOLS Web Services, any document format that has LEAD support for loading as SVG such as PDF, DOCX/DOC and many others. This code sets an SVG item into the viewer:

// Add an item from an SVG image 
imageViewer.items.addFromUrl("http://localhost/images/image.svg", lt.LeadSizeD.empty); 

The following code adds four items to the viewer:

// Add items directly 
for (var i = 1; i <= 4; i++) { 
   var url = "http://localhost/images/image" + i + ".png"; 
   imageViewer.items.addFromUrl(url, lt.LeadSizeD.empty); 
} 
// pan and zoom to see all the images on top of each other 

In both cases, the viewer will load the image by creating an img HTML element and setting the src property to the URL. The file formats include standard formats supported by all browsers such as PNG, GIF and JPEG (and TIFF in Internet Explorer) as well as standalone SVG documents. Therefore, if you encounter an error while loading an image in the viewer directly then first make sure it can be loaded by the browser by loading it directly:

<img src="http://localhost/images/image.png" />

Or

<img src="http://localhost/images/image.svg" />

If this works, then the image viewer will be able to view the same image. Note that SVG files must standalone documents that contain <svg> element with a valid xmlns attribute as in:

<?xml version="1.0" encoding="utf-8"?> 
              
<svg xmlns="http://www.w3.org/2000/svg" ... > 

It is always recommended to disable the viewer from updating while multiple items are added (or removed, or updated). Doing so will ensure that the viewer does not waste resources updating its transformations and re-painting while it is in an intermediate state:

// Disable any updates until we are done 
imageViewer.beginUpdate(); 
// Add items directly 
for (var i = 1; i <= 4; i++) { 
   var url = "http://localhost/images/image" + i + ".png"; 
   imageViewer.items.addFromUrl(url, lt.LeadSizeD.empty); 
} 
// Update now 
imageViewer.endUpdate(); 
// pan and zoom to see all the images on top of each other 

With multiple items, it is sometimes desired to add items at a certain location. This can easily be accomplished using ImageViewerItems.Insert which accepts as a parameter the index of the new item. All the direct add methods (such as AddFromImage) also have an insert counterpart (Such as InsertFromImage)

Removing items from the viewer is performed as follows. Start from the example code above and add the following:

// Remove the first item 
imageViewer.items.removeAt(0); 

Run the demo again, note that the viewer is displaying three items instead of four starting from page 2. ImageViewerItems.Remove can be used to remove an item by its reference. ImageViewerItems.Clear will remove all the items from the viewer (and sets the ActiveItem property to null)

Relationship between Item and Image Size

Each ImageViewerItem has two properties to determine the size of the item and its image:

When using the control as an "image" or "document" viewer, then in most cases these two values are the same and the image will occupy the whole item area.

When using the control as an "image list" or "thumbnails" viewer, then it is desirable to have the item size larger than the image size to leave room for text description for example.

In both cases, each item can have its own item and image size different than any other item in the viewer.

Image Size

The viewer will calculate and set ImageViewerItem.ImageSize depending on the following conditions:

Item Size

The viewer will calculate and set ImageViewerItem.Size depending on following conditions:

Usually you set ImageViewer.ItemSize to a specified value when the viewer is used as an "image list" or "thumbnails browser". To accomplish this, set the value of ItemSize to the desired thumbnail size plus padding. For example, 200 by 200 pixels. Then add the items with their own ImageViewerItem.Size set to the default value of LeadSizeD.Empty. As described above, the viewer will update ImageViewerItem.Size to be equal to 200 by 200 pixels as well. One more thing to consider in this mode is how the image inside each item is displayed. In image list mode, it's probably desired to fit each image inside this size (200 by 200 pixels in the case above), so set the value of ImageViewer.ItemSizeMode to Fit or FitAlways.

Resolution

ImageViewerItem also has the Resolution property. This must be set to the resolution (in dots per inch) of the original image data if accounting for the logical size of the image when displayed is desired.

The resolution is only used when ImageViewer.UseDpi is set to true. The values of ImageViewerItem.Resolution along with ImageViewer.ScreenDpi are used when calculating how to display the image.

For example, a typical A4 document image is 8.5 by 11 inches. Which could be 2550 by 3300 pixels if the image has a resolution of 300 by 300. Most document viewer applications will try to display this image in its original size. In other words, the image will take 8.5 inches of screen horizontal space and 11 inches of screen vertical space. If you do not use the ImageViewer.UseDpi property for this control, you are required to do the calculations yourself as follows:

viewer.useDpi = false; 
viewer.zoom(screenResolution / imageResolution); 

In the case of the image above, this will be 96 (typical screen resolution) divided by 300. Or, you can set the ImageViewer.UseDpi value to true and the control will use the above formula internally keeping the ScaleFactor set to 1 as follows:

viewer.useDpi = true; 
viewer.zoom(1); 

This code will produce the same results as the first code snippet.

In platforms where the screen resolution can be obtained programmatically (such as Windows.Forms), the value of ImageViewer.ScreenDpi is set automatically by the image viewer upon creation.

In platforms where the screen resolution cannot be obtained programmatically (such as JavaScript), the value of ImageViewer.ScreenDpi is set to the default value of 96.

When adding a new item to the viewer, the value of ImageViewerItem.Resolution will be checked. If the value is empty (or 0,0), then the viewer will try to obtain this value from this image data in platforms where this information can be obtained programmatically (such as Windows.Forms).

In platforms where the resolution cannot be obtained automatically (such as JavaScript), then it's the user responsibility to set the value. For example, the LEADTOOLS HTML5 Viewer Demo uses the LEADTOOLS REST services to obtain this value and set it for the item.

In either case, the user can then manually modify this value is desired.

Active Item

ImageViewer will always have an item denoted as the "Active", this can be accessed through the ImageViewer.ActiveItem property. This property cannot be set to null unless there are no more items in the viewer.

When an item is removed, the viewer will automatically check if it was the active item and if so, will set the next closest item as the new active.

The ActiveItem is important when using the viewer in a single item mode as described below.

Single Item Mode

Some application such as the Main Demo shipped with LEADTOOLS does not require multiple items in the image viewer and will always have a single item that either has image data or not.

For these type of application, the image viewer provides shortcuts for all the properties and method that would normally require accessing the ImageViewer.Items collection or modifying ImageViewerItem.

To achieve this, the image viewer layout must be set to ImageViewerSingleViewLayout and an empty item must be set in ImageViewer.Items. This item will be the ActiveItem since the image viewer must have an active item at all times. This is precisely what happens when you create a new instance of ImageViewer using the default constructor, code:

// Get the div item for the viewer 
var div = document.getElementById("imageViewer"); 
// Create a new image viewer instance without setting the view layout 
var createOptions = new lt.Controls.ImageViewerCreateOptions(div); 
var imageViewer = new lt.Controls.ImageViewer(createOptions); 
// Verify that we have a view layout, and it is of type single 
if (imageViewer.viewLayout != null && imageViewer.viewLayout.name == "Single") { 
   alert("Single view"); 
} 
// Verify that we have an item 
if (imageViewer.items.count == 1) { 
   alert("We have an item"); 
} 
// Verify that we have an active item 
if (imageViewer.activeItem != null) { 
   alert("We have an active item"); 
} 
             
imageViewer.itemChanged.add(function () { 
   // Show the image size 
   alert("ImageSize: " + imageViewer.imageSize.width + "," + imageViewer.imageSize.height); 
}); 
             
// Set an image into it 
imageViewer.imageUrl = "http://localhost/images/image1.png"; 

The ImageViewer.Image property is a short cut to ImageViewer.ActiveItem.Image. For more information, refer to Image Viewer Single Item Mode.

Note that all the members will return null (or default value) if the viewer does not have any items.

Additional Item Operation and Properties

The ImageViewerItem class also supports the following members:

Reference

Using ImageViewer

Using Image Viewer with HTML5 and JavaScript

Image Viewer Components

Image Viewer Elements Mode

Image Viewer User Defined HTML Display

Using Multiple Image Viewers In Your Application

Image Viewer Appearance

Image Viewer Bounds and Transform

Image Viewer Transformation

Image Viewer Layouts

Image Viewer Rendering

Image Viewer Scrolling

Image Viewer Interactive Modes

Image Viewer Other Operations

Image Viewer Single Item Mode

Image Viewer Drag and Drop

Image Viewer Interpolation

Image Viewer Sync