In This Topic ▼

Image Viewer Rendering

The ImageViewer rendering cycle supports full customization. The various events and their data allow for any of the following:

Rendering Cycle

The rendering cycle occurs when ImageViewer.Invalidate or ImageViewer.RenderRedirect is called due to normal control painting or a response to ImageViewer.UpdateTransform. To customize the rendering cycle, you can either subscribe to the specific event or derive from the ImageViewer and override the specific virtual method. All these methods and event use the ImageViewerRenderEventArgs class to hold the information needed.

ImageViewerRenderEventArgs contains the following:

Member Description
Context

In Windows Forms, the System.Drawing.Graphics object of the viewer control during paint or that of the target device during RenderRedirect.

In JavaScript, the HTML CanvasContext2D object for the fore canvas or that of the target device during RenderRedirect.

PaintEventArgs

Original Windows.Forms paint arguments if this render event is in response to System.Windows.Forms.Control.Paint.

Item

The item being rendered or null of this part of the rendering cycle is view-specific.

Part

The item part being rendered or View if this part of the rendering cycle is is view-specific.

Error

An error that was caught during the rendering cycle. Used with the ImageViewer.RenderError event.

ImageViewerRenderEventArgs.ClipRectangle

Current clipping rectangle to be applied.

The image viewer will call the virtual methods and fires the events in the order described below. Note for members, ImageViewerRenderEventArgs.Contex will point to the System.Drawing.Graphics (in Windows.Forms) or (HTML CanvasContext2D object for the fore canvas in JavaScript) the viewer control or the redirect target.

Method - Event ImageViewerRenderEventArgs.Item, Part Default Operations
ImageViewer.OnEraseBackground - ImageViewer.EraseBackground JavaScript only

null - ImageViewerItem.View

Erases or clears the background
OnPreRender - PreRender

null - ImageViewerItem.View

Nothing. Can be used to set the context properties (for example, anti-aliasing or interpolation quality)
OnRenderShadow - RenderShadow

null - ImageViewerItem.View

Renders the drop shadow of the view
OnRenderBorder - RenderBorder

null - ImageViewerItem.View

Renders the border of the view
For each item

Loops through the items in the viewer. Only occur if the item is IsVisible, has none empty ImageSize and if it intersects with the current visible viewer surface and clipping rectangle.

OnPreRenderItem - PreRenderItem

The item - Item

Nothing
OnRenderItem - RenderItem

The item - Item

Nothing
OnRenderBackground - RenderBackground

The item - Item

Fills the content of the item with the background color based on the item state
OnRenderBorder - RenderBorder

The item - Content

Renders the content border using the border color based on the item state
OnRenderShadow - RenderShadow

The item - Image

Renders the drop shadow around the image of the item
OnRenderImage - RenderImage

The item - Image

Renders the item image
OnRenderBorder - RenderBorder

The item - Image

Renders the border of the image
OnRenderText - RenderText

The item - Text

Renders the text of the item
OnPostRenderItem - PostRenderItem

The item - Item

Nothing
Next item
OnPostRender - PostRender

null - ImageViewerItem.View

Renders the floaters and regions
OnRedirectRender - RedirectRender

null - ImageViewerItem.View

Nothing

The most common custom rendering is performed by subscribing to these events:

Refer to these events for an example.

To manually trigger a new rendering cycle, call ImageViewer.Invalidate to invalidate a portion of the whole surface of the viewer. This method accepts a rectangle that specifies the portion of the viewer to update for optimal speed. The InvalidateItem or InvalidateItemByIndex methods can be used to re-render a single item quickly.

Errors when Rendering

Rendering of the ImageViewer control normally occurs automatically and not through any code called by the user. If an error occur, the user does not have the ability to try/catch the exception and process the error. Therefore, ImageViewer contains the RenderError events. This will occur when an error happens in the internal rendering cycle. The event uses the same ImageViewerRenderEventArgs data class, so all the usual parameters of what item and part caused the error are passed to the user. In addition, it will catch the error and set it in the ImageViewerRenderEventArgs.Error property.

Other Rendering Operations

The ImageViewer also supports the following operations related to rendering:

Display

Member Description
Invert

Display all items with inverted colors

ScreenDpi

Update the value of the screen resolution in dots per inch

UseDpi

Account for the resolution of the image in the items when calculating the display size

AspectRatioCorrection

Manually change the aspect ratio used to compensate for non-square pixels

BeginRender

Temporally disable rendering

EndRender

Re-enable rendering

ImageViewer.Invalidate

Request that the viewer re-renders the whole or part of the view

PaintProperties

Controls the quality used when rendering RasterImage objects

RedirectRender

Render the current view to an external context

ClipImageToContent

Display only the part of the image inside its content if the item transformation result in a larger boundary

OwnerDraw

Turn off or on all automatic rendering of view and items

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.