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:

Member Description
ImageViewerItems.Add

Adds a new item to the viewer

ImageViewerItems.Insert

Inserts at the specified index a new item to the viewer

ImageViewerItems.Remove

Removes an item from the viewer

ImageViewerItems.RemoveAt

Removes the item at the specified index from the viewer

ImageViewerItems.Clear

Delete all the items from the viewer

ImageViewerItems.Item

Gets or sets an item at the specified index

ImageViewerItems.Contains

Determines whether an item is in the viewer

ImageViewerItems.IndexOf

Gets the index of the specified item

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

Member Description
ItemChanged

Occurs when an item has changed

ItemError

Occurs when an error occurred while setting the item image data

SelectedItemsChanged

Occurs when the number of values of the selected items has changed

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

Member Description
GetSelected

Returns the current selected items in the viewer

Select

Selects items in the viewer

AddFromImage

Adds an item from a RasterImage object

InsertFromImage

Inserts an item at the specified index from a RasterImage object

AddFromImageUrl

Adds an item from a URL pointing to an image file

InsertFromImageUrl

Inserts an item at the specified index from a URL pointing to an image file

AddFromImageFile

Adds an item from an image file on disk

InsertFromImageFile

Inserts an item at the specified index from an image file on disk

UpdateImage

Replaces or sets the RasterImage object of an item

UpdateUrl

Replaces or sets the image data of an item from a URL pointing to an image file

AddFromSvgUrl

Adds an item from a URL pointing to an image or document file that supports being loaded as SVG

InsertFromSvgUrl

Inserts an item at the specified index from a URL pointing to an image or document file that supports being loaded as SVG

AddFromSvgFile

Adds an item from a disk file containing an image or document file that supports being loaded as SVG

InsertFromSvgFile

Inserts an item at the specified index from a disk file containing an image or document file that supports being loaded as SVG

UpdateSvgDocument

Replaces or sets the SvgDocument object of an item

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:

For code snippets below, replace the code used in Using Image Viewer with Windows.Forms with the snippet below, then add the code described.

Generic Code

// Create a new image viewer instance with a vertical layout 
ImageViewerViewLayout viewLayout = new ImageViewerVerticalViewLayout(); 
ImageViewer imageViewer = new ImageViewer(viewLayout); 
// Set some properties 
imageViewer.Dock = DockStyle.Fill; 
imageViewer.BackColor = Color.Bisque; 
// Add a border (need some padding as well) 
imageViewer.ImageBorderThickness = 1; 
imageViewer.ItemPadding = new Padding(imageViewer.ImageBorderThickness); 
// Add it to the form 
this.Controls.Add(imageViewer); 
imageViewer.BringToFront(); 
// 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 ImageViewerPanZoomInteractiveMode()); 

Adding and Removing Items

The following code will create a new item, load a TIF file as a RasterImage, set it as the image data of the item, and add the item to the viewer:

// Create an item 
ImageViewerItem item = new ImageViewerItem(); 
// Load an image into it 
using (RasterCodecs codecs = new RasterCodecs()) 
   item.Image = codecs.Load(@"C:\LEADTOOLS22\Resources\Images\Ocr1.tif", 1); 
// Add it to the viewer 
imageViewer.Items.Add(item); 

Alternatively, let the viewer load it (using the internal RasterCodecs instance) by setting the URL:

// Create an item 
ImageViewerItem item = new ImageViewerItem(); 
// Load an image into it 
item.Url = new Uri(@"C:\LEADTOOLS22\Resources\Images\Ocr1.tif"); 
// Add it to the viewer 
imageViewer.Items.Add(item); 

It is also possible to use the ImageViewerItems method to add the items directly without creating an ImageViewerItem instance:

// Add an item directly 
using (RasterCodecs codecs = new RasterCodecs()) 
{ 
   RasterImage rasterImage = codecs.Load(@"C:\LEADTOOLS22\Resources\Images\Ocr1.tif", 1); 
   imageViewer.Items.AddFromImage(rasterImage, 1); 
} 

Another way is to add an item from a file directly without creating a RasterImage object:

// Add an item directly from a disk file 
imageViewer.Items.AddFromImageFile(@"C:\LEADTOOLS22\Resources\Images\Ocr1.tif", 1); 

Or from a URL

// Add an item directly from a URL 
imageViewer.Items.AddFromImageUrl(new Uri(@"C:\LEADTOOLS22\Resources\Images\Ocr1.tif")); 

In the cases above, the item added can be easily obtained for further modification by using the return values from the methods or accessing the ImageViewer.Items collection.

ImageViewer also supports adding SVG items. They can be SVG files or any document format that supports being loaded as SVG. This code will load a page from a PDF file as SVG and add an item for it:

// Create an item 
ImageViewerItem item = new ImageViewerItem(); 
// Load a page from a PDF file as SVG and set it in the item 
using (RasterCodecs codecs = new RasterCodecs()) 
   item.SvgDocument = codecs.LoadSvg(@"C:\LEADTOOLS22\Resources\Images\Leadtools.pdf", 1, null) as SvgDocument; 
// Add it to the viewer 
imageViewer.Items.Add(item); 

Similarly to using RasterImage, the viewer can load the SVG document by setting the URL. An extra step is required:

// Create an item 
ImageViewerItem item = new ImageViewerItem(); 
// Tell the item to load the data in the URL as SVG, not a RasterImage 
item.LoadUrlAsSvg = true; 
// Load an image into it 
item.Url = new Uri(@"C:\LEADTOOLS22\Resources\Images\Leadtools.pdf"); 
// Add it to the viewer 
imageViewer.Items.Add(item); 

AddFromSvgDocument, AddFromSvgUrl or AddFromSvgFile work the same way as the RasterImage counterparts described above.

The following code adds four items to the viewer:

// Add an item directly 
using (RasterCodecs codecs = new RasterCodecs()) 
{ 
   for (int i = 1; i <= 4; i++) 
   { 
      string fileName = string.Format(@"C:\LEADTOOLS22\Resources\Images\Ocr{0}.tif", i); 
      RasterImage rasterImage = codecs.Load(fileName, 1); 
      imageViewer.Items.AddFromImage(rasterImage, 1); 
   } 
} 
// pan and zoom to see all the images on top of each other 

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

// Disable any updates till we are done 
imageViewer.BeginUpdate(); 
// Add an item directly 
using (RasterCodecs codecs = new RasterCodecs()) 
{ 
   for (int i = 1; i <= 4; i++) 
   { 
      string fileName = string.Format(@"C:\LEADTOOLS22\Resources\Images\Ocr{0}.tif", i); 
      RasterImage rasterImage = codecs.Load(fileName, 1); 
      imageViewer.Items.AddFromImage(rasterImage, 1); 
   } 
} 
// 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 set 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:

Member Description
ImageViewerItem.Size

The size of the whole item, including any margins, borders and padding

ImageViewerItem.ImageSize

The image size in pixels

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:

Value of ImageViewerItem.ImageSize ImageViewerItem.Image or ImageViewerItem.SvgDocument Description
LeadSize.Empty or 0,0 Available

The viewer will use automatically calculate the value from the image data (Image or SvgDocument) and set it in ImageViewerItem.ImageSize. The code snippets above rely on this auto-calculations.

LeadSize.Empty or 0,0 Not set

ImageViewerItem.ImageSize stays empty. This item will be invisible and will not participate in the layout calculation. The size can be set at a later time, if desired to make the item visible.

Not empty Available

The viewer will not calculate the value from the image data. Instead, the value is used as is. The viewer will automatically stretch or shrink the image data when calculating the transformation or rendering to match the size.

Not empty Not Available

The viewer will treat the item as if it has image data of the specified size. It will use this value in the transformation calculations, but will not render any image data. The ImageViewerVirtualizer uses this mode extensively to render a place holder of the actual image until the data is available. This mode can also be used to custom-render image data.

Item Size

The viewer calculates and sets ImageViewerItem.Size depending on following conditions:

Value of ImageViewer.ItemSize Value of ImageViewerItem.Size Description
LeadSize.Empty or 0,0 LeadSize.Empty or 0,0

This is the default mode. The viewer will use the value of ImageViewer.ItemSize, calculated above and set it in ImageViewerItem.Size. Hence, the item will have the same value for both and the image will occupy the full item area

Not empty LeadSize.Empty or 0,0

The viewer will set the value of ImageViewer.ItemSize into ImageViewerItem.Size. All the items will have the same size and each image will be placed and rendered inside the item, depending on their own ImageViewerItem.ImageSize values and alignment. This mode is useful when the viewer is used as an "image list" or "thumbnails browser".

LeadSize.Empty or 0,0 Not empty

The viewer will use the value of ImageViewerItem.Size as the size of the item. ImageViewerItem.ImageSize will not be used in this calculation and only to determine where to place and render the image inside the item.

Not empty Not empty

The viewer will ignore ImageViewer.ItemSize and use ImageViewerItem.Size.

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 LeadSize.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 is 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 US Letter document image is 8.5 by 11 inches, which at the typical print resolution of 300 by 300 dpi is equivalent to 2550 by 3300 pixels. Most document viewer applications will try to display this image at its original size (i.e., 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, 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 produces 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 is the user's responsibility to set the value. For example, the LEADTOOLS HTML 5 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 if desired.

Image Ownership

RasterImage and SvgDocument are both IDisposable objects. Eventually, some part of the code needs to dispose of these objects when they are no longer needed. This is controlled by using the ImageViewer.AutoDisposeImages property. In the examples above, the value of this property is to the default of true. Hence, the viewer disposes the image or SVG document when the item is removed. To prevent that, set the value of AutoDisposeImages to false.

Active Item

ImageViewer will always have an item denoted as the "Active" item. Access the item 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. If so, it will set the next closest item as the new active item.

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

Single Item Mode

Some applications, 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 does not have it.

For these type of applications, the image viewer provides shortcuts for all the properties and methods 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 creating a new instance of ImageViewer using the default constructor, with the following code:

// Create a new image viewer instance using the default constructor 
ImageViewer imageViewer = new ImageViewer(); 
// Set some properties 
imageViewer.Dock = DockStyle.Fill; 
// Add it to the form 
this.Controls.Add(imageViewer); 
// Verify that we have a view layout, and it is of type single 
Debug.Assert(imageViewer.ViewLayout != null && imageViewer.ViewLayout is ImageViewerSingleViewLayout); 
// Verify that we have a single item 
Debug.Assert(imageViewer.Items.Count == 1); 
// Verify that we have an active item 
Debug.Assert(imageViewer.ActiveItem != null); 
// Load an image into it 
using (RasterCodecs codecs = new RasterCodecs()) 
   imageViewer.Image = codecs.Load(@"C:\LEADTOOLS22\Resources\Images\Ocr1.tif", 1); 
// Show the image size 
MessageBox.Show("ImageSize: " + imageViewer.ImageSize.ToString()); 

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 Operations and Properties

The ImageViewerItem class also supports the following members:

Member Description
IsVisible

Controls the visibility of the item in the viewer. Invisible items will neither be rendered nor participate in layout calculations

IsEnabled

Determines whether the item is enabled. Inactive items are rendered and participate in layout calculations, but do not respond to interactive mode events

IsSelected

Determines whether the item is in a selected state. Selected items may be rendered differently than non-selected items

IsHovered

Determines whether the item is in a hovered state. Hovered items may be rendered differently

ClipImageToContent

Determines whether to restrict rendering of the image inside its item area if the image size or transformation results in display coordinates that lay outside the item boundary

ImageVerticalAlignment

Determines how the image is aligned vertically inside the item boundary

ImageHorizontalAlignment

Determines how the image is aligned horizontally inside the item boundary

Text

Text string associated with this item. Can be used to show a page number or file name, or any other text data

TextVerticalAlignment

Determines how the text is aligned vertically inside the item boundary

TextHorizontalAlignment

Determines how the text is aligned horizontally inside the item boundary

Floater

The floater image for this item

FloaterTransform

Position, scale, and rotation of the floater image relative to the image

FloaterOpacity

Controls the opacity of the floater. Can also be used to hide the floater completely

PageNumber

Item page number. Can be used to hold the original page number of the document being viewed

PageCount

Number of pages in the Image property

ImageRegionToFloater

Converts the region found in Image into a floater

CombineFloater

Merges the floater with the current image

Tag

User-defined data

See Also

Reference

Using ImageViewer

Using Image Viewer with Windows.Forms

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 Virtualizer

Image Viewer Drag and Drop

Image Viewer Sync

Help Version 22.0.2023.7.17
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS Imaging, Medical, and Document
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.