Skip to main content

DPIAwareImageCollection Class

Storage that serves as an external icon source for DevExpress controls. Automatically replaces default images with their larger counterparts at higher DPI settings.

Namespace: DevExpress.Utils

Assembly: DevExpress.Utils.v24.1.dll

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

Declaration

public class DPIAwareImageCollection :
    Component,
    ISupportInitialize,
    IImageCollection,
    IComponent,
    IDisposable,
    ISupportsListArrange,
    ISupportsHighDPI,
    IImageCollectionBase

Remarks

To start using a DPIAwareImageCollection, drag it onto the form from the Visual Studio Toolbox, or convert an existing ImageCollection using the smart tag action.

DPI Aware Image Collection - Convert

The DPIAwareImageCollection combines multiple look-alike icons of different sizes into a single logical unit. For example, four “Close” icons rendered at 24x24, 32x32, 48x48 and 64x64 dimensions can all be linked to the default 16x16 icon. Then, if a UI element (e.g., a button) displays a 16x16 “Close” icon at default 96 DPI, the DPIAwareImageCollection replaces this icon with a 32x32 one when the scale factor increases to 200% (192 DPI).

This eliminates blurry icons, which are inevitable when running a WinForms application at high DPI settings. The figure below illustrates the difference.

DPI-Aware Collection - DPIs

Set Up DPI Image Collection

The DPIAwareImageCollection.ImageSize property specifies the default image size, i.e., images of which size are used when Windows scale factor is set to 100% (96 DPI). The initial default size is 16x16, you can change this setting for larger images.

DPI-Aware Collection - Default size

To populate the DPI-Aware Image Collection with images, invoke the component smart tag and click “Edit ImageCollection”, then use the “Load Images” selector in the dialog that pops up.

DPI-Aware Collection - Add Images

You can load images from various sources. See the ImageCollection class description to learn about exporting images from assemblies.

When images are loaded, click “Categorize” to build the hierarchy: images with default sizes become root nodes that own images with similar names, but different sizes. The grid to the dialog’s right indicates at what DPI settings default images can be replaced with counterpart images.

DPI-Aware Collection - Dialog Structure

This happens fully automatically if file names are correct (e.g., “Close-32x32.png”, “Close_48x48.png”, etc.). Otherwise, you need to manually drag-and-drop images from the list into grid cells.

DPI-Aware Collection - Hierarchy Animation

After the image hierarchy is ready, assign default images to UI elements. The DPI-Aware Image Collection replaces them automatically when the system DPI changes.

Assign Images to DevExpress Controls

DevExpress controls that support image collections expose two properties:

  • Images (LargeImages, DisabledImages, etc) - assign your image collection to this property;
  • ImageIndex (LargeImageIndex, DisabledImageIndex, etc) - selects a collection image by its index.

DPI-Aware Collection - Image Index

ribbonControl1.LargeImages = dpiAwareImageCollection;
barButtonItem1.ImageOptions.LargeImageIndex = 2;

You can also retrieve default images directly from the collection’s Images property.

barButtonItem1.ImageOptions.LargeImage = dpiAwareImageCollection1.Images[1].ImageInfo.Image;

Inheritance

Object
MarshalByRefObject
Component
DPIAwareImageCollection
See Also