---

ImageViewer supports any number of items with multiple view layouts. However, some applications simply want to use the viewer with a single image and do not want to deal with setting up the layouts or dealing with the item collection. For these types of applications, ImageViewer offers the single item mode.

As described in Image Viewer Items, if there are items in the viewer, one of them is donated as the active item and from Image Viewer Layouts, the viewer supports the ImageViewerSingleViewLayout that displays a single item at the item - the active item. Therefore it is easy to setup the viewer to display a single item all the time:

            // Create a single view layout
            var layout = new ImageViewerSingleViewLayout();
            // Create the viewer, passing this layout
            var imageViewer = new ImageViewer(layout);
            // Add an empty item
            var item = new ImageViewerItem();
            imageViewer.Items.Add(item);
            // Now, ImageViewer.ActiveItem is item
            

This is exactly what the default constructor of ImageViewer does:

            var imageViewer = new ImageViewer();
            

After the viewer is setup like this, it is easy to forget about the view layout and the items collection and just use the ActiveItem property to view images. Set an image into the viewer:

            imageViewer.ActiveItem.Image = myImage;
            

Or to remove the image:

            imageViewer.ActiveItem.Image = null;
            

To get its transform:

            var transform = imageViewer.GetItemImageTransform(imageViewer.ActiveItem);
            

Or to convert a point from image to control coordinate and back:

            controlPoint = imageViewer.ConvertPoint(imageViewer.ActiveItem, ImageViewerCoordinateType.Image, ImageViewerCoordinateType.Control, imagePoint);
            imagePoint = imageViewer.ConvertPoint(imageViewer.ActiveItem, ImageViewerCoordinateType.Control, ImageViewerCoordinateType.Image, controlPoint);
            

In addition to using the ActiveItem property, the viewer also contains shortcut methods and properties that can be used in single item mode. The following is the same code as above using these shortcuts. Set an image into the viewer:

            imageViewer.Image = myImage;
            

Or to remove the image:

            imageViewer.Image = null;
            

To get its transform:

            var transform = imageViewer.ImageTransform;
            

Or to convert a point from image to control coordinate and back:

            controlPoint = imageViewer.ConvertPoint(null, ImageViewerCoordinateType.Image, ImageViewerCoordinateType.Control, imagePoint);
            imagePoint = imageViewer.ConvertPoint(null, ImageViewerCoordinateType.Control, ImageViewerCoordinateType.Image, controlPoint);
            

With these properties/methods, you can use the ImageViewer control without touching any of the "view" or "item" property or methods. These shortcuts perform all the necessary check to make sure an active item is added to the viewer. For example, ImageViewer.Image get method is implemented like this:

            if (this.ActiveItem != null) // Do we have an active item?
               return this.ActiveItem.Image; // Yes, return its image
            else
               return null; // No, return null
            

And the set method:

            if (this.ActiveItem != null) // Do we have an active item?
               this.ActiveItem.Image = value; // Yes, set its image
            // Else, nothing to do
            

The following lists all the single item mode shortcuts and the equivalent internal code:

Shortcut	Equivalent
ImageViewer.Image	ImageViewer.ActiveItem.Image
ImageViewer.SvgDocument	ImageViewer.ActiveItem.SvgDocument
ImageViewer.ImageSize	ImageViewer.ActiveItem.Size
ImageViewer.ImageResolution	ImageViewer.ActiveItem.Resolution
ImageViewer.ImageUrl	ImageViewer.ActiveItem.Url
ImageViewer.HasImage	ImageViewer.ActiveItem.Image or ImageViewer.ActiveItem.SvgDocument is not null
ImageViewer.ImageTransform	ImageViewer.GetItemImageTransform(ImageViewer.ActiveItem)
ImageViewer.GetImageTransformWithDpi	ImageViewer.GetItemImageTransformWithDpi(ImageViewer.ActiveItem, useDpi)
ImageViewer.Floater	ImageViewer.ActiveItem.Floater
ImageViewer.FloaterTransform	ImageViewer.ActiveItem.FloaterTransform
ImageViewer.ImageBounds	ImageViewer.GetItemViewBounds(ImageViewer.ActiveItem, ImageViewerItemPart.View, false)
ConvertPoint, ConvertPoints and ConvertRect	Accept null as the item parameter to donate the active item

In addition to these shortcuts, the following are members used only when ImageViewer is used in single item mode:

Member	Description
ImageViewer.AutoResetOptions	Determines which transformation values to reset when a new image is set into the viewer.
ImageViewer.Reset	Reset the transformation values

Error processing SSI file