useDpi Property


Indicates whether the control must account for the physical resolution of the images when calculating the display properties.


JavaScript Syntax
Object.defineProperty(ImageViewer.prototype, 'useDpi', 
	get: function(), 
	set: function(value) 
TypeScript Syntax
useDpi: boolean; 

Property Value

true to account for the physical resolution of the images when calculating the display properties; otherwise, false. Default value is false.


Changing the value of this property will fire the PropertyChanged and TransformChanged events.

The physical resolution of an image is measured in dots per inch (DPI). The values are stored in the ImageViewerItem.Resolution property (or ImageResolution when the control is used as a single image viewer). The screen resolution is also required and is stored in the ScreenDpi property. These are the values used in the calculations when the value of UseDpi is set to true.

For example, a typical A4 document image is 8.5 by 11 inches. Which could be 2550 by 3300 pixels if the image has a resolution of 300 by 300. Most document viewer applications will try to display this image in its original size. i.e. the image will take 8.5 inches of screen horizontal space and 11 inches of screen vertical space. If you do not use the UseDpi property for this control, you are required to do the calculations yourself as follows:

viewer.UseDpi = false; 
var scaleFactor = screenResolution / imageResolution; 
viewer.Zoom(ControlSizeMode.None, scaleFactor, viewer.DefaultZoomOrigin); 

In the case of the image above, this will be 96 (typical screen resolution) divided by 300. Or, you can set the UseDpi value to true and the control will use the above formula internally keeping the scale factor set to 1 as follows:

viewer.UseDpi = true; 
viewer.Zoom(ControlSizeMode.None, 1.0, viewer.DefaultZoomOrigin); 

This code will produce the same results as the first code snippet.

In platforms where the screen resolution can be obtained programmatically (such as Windows.Forms), the value of ScreenDpi is set automatically by the image viewer upon creation.

In platforms where the screen resolution cannot be obtained programmatically (such as JavaScript), the value of ScreenDpi is set to the default value of 96.

When adding a new item to the viewer, the value of ImageViewerItem.Resolution will be checked. If the value is empty (or 0,0), then the viewer will try to obtain this value from this image data in platforms where this information can be obtained programmatically (such as Windows.Forms).

In platforms where the resolution cannot be obtained automatically (such as JavaScript), then it's the user responsibility to set the value. For example, the LEADTOOLS HTML5 Viewer Demo uses the LEADTOOLS REST services to obtain this value and set it for the item.

In either case, the user can then manually modify this value is desired.

For more information, refer to Image Viewer Items.


Run the demo and click the Example button, the UseDpi value will be flipped and the image size and real image size values are shown.

Start with the ImageViewer example, remove all the code inside the example function (search for the "// TODO: add example code here" comment) and insert the following code:

JavaScript Example
this._imageViewer.useDpi = !this._imageViewer.useDpi; 
alert("_imageViewer.UseDpi " + this._imageViewer.useDpi); 


Target Platforms

Help Version 19.0.2017.10.18
Products | Support | Contact Us | Copyright Notices
© 1991-2017 LEAD Technologies, Inc. All Rights Reserved.

Leadtools.Controls Assembly