Indicates whether to automatically create an HTML5 Canvas Element when the image is updated.
true to automatically create the
canvas when the image is updated; otherwise, false. Default value is
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.
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.
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;
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:
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
canvas, such as image processing.
// 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));
Medical Web Viewer .NET