Image Viewer Bounds and Transform

Summary

As described in Image Viewer Appearance, the various elements of the ImageViewer control participate in the view layout system, the view transform, and the item size and properties to position and render each item in its correct place.

ImageViewer contains many properties and methods to obtain the transformation matrix and bounding rectangle of an element.

Item

The most important task for an item is determining the transform matrix required to render the image. This can be easily obtained using GetItemImageTransform. This method returns a LeadMatrix that contains all the transformation values needed to place the image on the viewer surface relative to the top-left corner of the viewer (pixel 0,0 of the client area).

To custom render an image:

Subscribe to one of the render events of the viewer. Refer to Image Viewer Rendering for more information
Obtain the image size using ImageViewerItem.ImageSize or ImageViewer.GetItemImageSize. Set this value in an imageSize variable of type LeadSizeD
Normally, it is desired to render the whole image. So create the destination rectangle as a variable of type LeadRectD with values 0,0,imageSize.Width,imageSize.Height
Obtain the transformation matrix for this item image using GetItemImageTransform, set it in a variable imageTransform of type LeadMatrix
Set this matrix into the render context
Render the image using the destination rectangle

In addition to the image transformation, you can obtain the transform matrix for any other part of the item using:

Member	Description
GetItemTransform	Returns the transform of the item itself. Used to draw the item border for example after adding the item padding
GetItemContentTransform	Returns the transform for the content area
GetItemFloaterTransform	Returns the transform for the floater image (if any). Use with GetItemFloaterSize to custom render a floater in the same manner described above for custom rendering an image

The viewer contains many methods and properties to obtain the bounding rectangle of an item (or any part it) in both physical (control) and logical (inside the view) coordinates:

Member	Description
GetItemViewBounds	Gets the current physical (in control pixel coordinates) bounds of any part of the item including the image
GetItemBounds	Gets the current logical (excluding the current transformation) bounds of any part of the item including the image

GetItemViewBounds can be used to obtain the current physical (in control pixel coordinates) bounds of any part of the item including the image. This method can be useful for performing manual hit-testing or testing against a clipping rectangle. GetItemBounds return the same value in logical coordinates (excluding the current transformation).

The ImageViewerItemPart enumeration can be used in methods and properties to donate the part of the item we are interested in.

View

The view is rendered using the matrix obtained by ViewTransform. The view bounds can be obtained using GetViewBounds. Custom rendering the view can be performed in the same manner described in custom rendering an image above replacing the image transform and bounds with the view values.

Coordinate System and Conversion

A point obtained from an event such as mouse click is in physical (pixel) coordinates while a point in the image or the view is in logical coordinate. Converting a point from one coordinates to another requires applying the correct transformation matrix. This can be done manually by obtaining the matrices involved and transforming the point or automatically using any of the following ImageViewer helper methods:

Member	Description
ConvertPoint	Convert a point from any coordinate to another
ConvertPoints	Convert an array of points from any coordinate to another
ConvertRect	Convert a rectangle from any coordinate to another
ConvertTransform	Convert a transformation matrix relative to an item to make it relative to different item
ConvertBoundsToView	Converts a rectangle from logical to physical view coordinates