ImageCollection.IsDpiAware Property

Gets or sets the value that specifies that when requesting an image from the ImageCollection, another DPI-specific image corresponding to the requested image is returned instead.

Namespace: DevExpress.Utils

Assembly: DevExpress.Utils.v24.1.dll

NuGet Packages: DevExpress.Utils, DevExpress.Wpf.Core

Declaration

C#

[DefaultValue(DefaultBoolean.Default)]
[DXCategory("Appearance")]
public virtual DefaultBoolean IsDpiAware { get; set; }

VB.NET

<DXCategory("Appearance")>
<DefaultValue(DefaultBoolean.Default)>
Public Overridable Property IsDpiAware As DefaultBoolean

Property Value

Type	Default	Description
DefaultBoolean	Default	The DefaultBoolean.True value if a requested image is replaced with a DPI-specific image; DefaultBoolean.False or DefaultBoolean.Default if this feature is disabled.

Available values:

Name	Description	Return Value
True	The value is true.	0
False	The value is false.	1
Default	The value is specified by a global option or a higher-level object.	2

Remarks

The ImageCollection allows you to provide different images (DPI-specific images) on displays having different DPI settings. This feature is enabled by the IsDpiAware property. The following tutorial shows how to set up the ImageCollection to support multiple DPI settings.

1. Add the images that correspond to different DPI settings to the project resources or a referenced library (see the ImageCollection class description to learn more). The names of the images (except for the image for the 96DPI) must have suffixes that specify the DPI settings to which the images correspond. The syntax is as follows:

   <ImageName><DPISuffix>

   where <ImageName> must match the name of the normal image (corresponding to the 96DPI), and <DPISuffix> is any string containing “<dpi-value>DPI” sub-string. Here, <dpi-value> is a DPI value (120, 144, 192, etc.)

   For example, the following image shows project resources containing two images corresponding to the 96DPI and 120DPI settings:

   

   The following table shows which DPI values correspond to which DPI scaling factors:

   DPI value	DPI scaling factor
   96	100%
   120	125%
   144	150%
   192	200%

   Build the project after adding images to the project resources.

2. Add an ImageCollection to the form and set its IsDpiAware property to True.

3. Add the normal images (that correspond to the 96DPI setting) from the project resources to the ImageCollection. To do this, select Choose Images from the ImageCollection Tasks pane. In the ImageCollection editor that will open, select Add->Load From Project Resources.

   

   The Select Resources dialog will open. In this dialog, select the images that correspond to the 96 DPI setting:

   

4. Assign the ImageCollection to a target control and apply the added normal image to the control or its visual element.

   For instance, when using the RibbonControl, assign the ImageCollection to the RibbonControl.Images (or RibbonControl.LargeImages) object and then assign a target image to a ribbon item via the item’s BarItem.ImageIndex (or BarItem.LargeImageIndex) property.

   The specified image will be displayed when using the normal DPI scaling (100%). When using a larger DPI scaling, an enlarged DPI-specific version of the image will be obtained from the project resources and displayed in the control. If no image matching the current DPI setting is found, the ImageCollection.ResolveImage event is fired. It allows you to manually provide a DPI-specific image. If no image is provided, the normal image will be displayed.

   In 96DPI mode, the size of images is specified by the ImageCollection.ImageSize property. When the DPI is set to higher values, the images are scaled accordingly. For instance, the 120DPI setting corresponds to the scale factor of 1.25. If the ImageSize property is set to (16,16), the actual image size in 120DPI will be (20,20). The ImageCollection.GetImageSize event allows you to override the default image size by providing a custom image size for various DPI settings.