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.v20.1.dll

Declaration

[DXCategory("Appearance")]
[DefaultValue(DefaultBoolean.Default)]
public virtual DefaultBoolean IsDpiAware { get; set; }
<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.

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:

    ImageCollection-DPI-01-ProjectResources

    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.

    ImageCollection-DPI-02-ImageCollection-AddFromResources

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

    ImageCollection-DPI-02-1-ImageCollection-SelectImagesInResources

  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.

See Also