autoCreateCanvas Property (ImageViewerItem)

Summary

Indicates whether to automatically create an HTML5 Canvas Element when the image is updated.

Syntax

JavaScript Syntax

Object.defineProperty(ImageViewerItem.prototype, 'autoCreateCanvas', 
	get: function(), 
	set: function(value) 
)

TypeScript Syntax

autoCreateCanvas: boolean;

Property Value

true to automatically create the canvas when the image is updated; otherwise, false. Default value is false.

Remarks

ImageViewerItem supports using an HTML Image Element (in the Image property), an HTML5 Canvas Element (in the Canvas property), or other HTML Elements and SVG Elements (in the Element property). The automatic creation of an HTML5 Canvas Element is not supported when Element is being used.

Using an img generally consumes less system resources, supports larger sizes, takes advantage of browser caching, and is not affected by cross-origin security policy. However, the image data is read-only and cannot be changed directly.

Using a canvas might consume more system resources, have limited size in some platforms, does not use the browser caching and is affected by cross-origin browser security policy. However, the image data is read-write and can be changed directly using the HTML5 Canvas Element drawing context.

If using a canvas is always desired, the user can create the canvas outside of the ImageViewer and populate it with the image data. Or, the user can set the value of AutoCreateCanvas to true and set the image element (or URL) into the ImageViewerItem. In this mode, the viewer will create the HTML5 Canvas Element and populate with the image data, then set it in the Canvas property; the original img is discarded.

As mentioned above, an HTML5 Canvas Element might have size limitation depending on the current platform and number of current canvas elements in the page. ImageViewer can automatically adjust the size of a large canvas using the global CanvasOptions class as follows:

The canvas is created using the original size desired. If successful, no more action is taken.
If an error occurs, CanvasOptions.AutoScale is checked. If the value is set to true (the default), a smaller size is tried (usually dividing the original size by two) until the operation succeeds. When this is finished, the scale value used (0.5, 0.25, etc.) is stored in the CanvasScale. The viewer will then this value along with ImageSize to scale the rendering of the item up, showing it at its original size.
The user can control the maximum width or height of an auto-created canvas by setting the value of CanvasOptions.MaximumSize to a value greater than the default of 0. In this mode, the viewer will automatically re-scale a canvas that is larger than the size set, even if they can be created successfully. This is useful to minimize the resources used by the application when many canvas elements are created.
If all the above fails an ItemError will occur, and it is up to the user to handle this and perform the necessary action. One solution would be to revert to using an img and disabling the parts of the application that require a canvas, such as image processing.

Example

JavaScript Example

// move the following line to _imageViewer create section... 
this._imageViewer.autoCreateCanvas = true; 
 
// now, back to the example... 
var canvas = this._imageViewer.canvas; 
var context = canvas.getContext("2d"); 
context.fillStyle = "rgba(0, 0, 0, .5)"; 
context.fillRect(25, 25, 125, 125); 
 
this._imageViewer.invalidate(lt.LeadRectD.create(25, 25, 125, 125));