←Select platform

UseDpi Property


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

public virtual bool UseDpi {get; set;} 
Public Overridable Property UseDpi() As Boolean 
   virtual property bool UseDpi 
      bool get() 
      void set(bool value) 

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 fires 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 US Letter document image is 8.5 by 11 inches, which at the typical print resolution of 300 by 300 dpi is equivalent to 2550 by 3300 pixels. Most document viewer applications will try to display this image at 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. Alternatively, 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 is the user's 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 as 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:

using Leadtools; 
using Leadtools.Controls; 
using Leadtools.Codecs; 
using Leadtools.Drawing; 
using Leadtools.ImageProcessing; 
using Leadtools.ImageProcessing.Color; 
_imageViewer.UseDpi = !_imageViewer.UseDpi; 
MessageBox.Show("_imageViewer.UseDpi" + _imageViewer.UseDpi); 
Imports Leadtools 
Imports Leadtools.Controls 
Imports Leadtools.Codecs 
Imports Leadtools.Drawing 
Imports Leadtools.ImageProcessing 
Imports Leadtools.ImageProcessing.Color 
Imports LeadtoolsControlsExamples.LeadtoolsExamples.Common 
Public Sub ImageViewerUseDpi_Example() 
   _imageViewer.UseDpi = Not _imageViewer.UseDpi 
   MessageBox.Show("_imageViewer.UseDpi" & _imageViewer.UseDpi) 
End Sub 
Target Platforms
Help Version 21.0.2021.7.2
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2021 LEAD Technologies, Inc. All Rights Reserved.

Leadtools.Controls Assembly

Products | Support | Contact Us | Intellectual Property Notices
© 1991-2021 LEAD Technologies, Inc. All Rights Reserved.