For example, you want to display the “Add.png” image in a control in a regular context, and the “Add.scale-150.png” in the same control when the 150% DPI setting is applied to the system. The correct image should be automatically chosen at runtime based on the current context.
The DevExpress WPF controls support automatic image selection based on the current context. To enable this feature, images in the project must have dedicated qualifiers in their names, or these images must be placed in folders whose names contain these qualifiers. Qualifiers identify a version of an image that should be used in the current context.
Consider the following screenshot demonstrating five images added to the Images folder:
The "Add.png" file is a regular image.
The "Add.theme-metropolis.png" name consists of the regular name ("Add"), a qualifier name ("theme") and a qualifier value ("metropolis"), thus it identifies the app context when this image is applied (i.e., when "theme" is "metropolis").
The "Add.theme-metropolis_scale-150.png" name includes another qualifier ("scale") and its value (150).
Other images use the same naming notation.
The following code assigns the Add.png image to a button in a toolbar using the QualifiedImage extension.
The use of the QualifiedImage extension guarantees automatic image substitution based on the current context.
Add.png - This image will be used in all cases, excluding the following four cases which narrow the application context.
Add.theme-metropolis.png - This image will be used when the "MetropolisLight", "MetropolisDark" or "TouchlineDark" theme is applied, with the exception of the following case.
Add.theme-metropolis_scale-150.png - This image will be used when the "MetropolisLight", "MetropolisDark" or "TouchlineDark" theme is applied, and the system DPI setting is 150%.
Add.theme-office.png - This image will be applied when any theme containing "Office" in its name is applied, with the exception of the following case.
Add.theme-office_input-touch.png - This image will be used when any touch-aware theme containing "Office" in its name is applied. These themes are: "Office2013;Touch", "Office2013LightGray;Touch" and "Office2013DarkGray;Touch".
Instead of using qualifiers in image names, you can place images in folders whose names contain these qualifiers. The images shown above can be placed in folders as follows.
The QualifiedImage extension must specify the full path to the image that corresponds to the regular context. For the screenshots above, this path must be "Images/Add.png":
You can combine the two approaches by using qualifiers in folder and image names simultaneously.
Available qualifiers and their values are described in the following sections.
Qualifiers of Themes
The following table covers theme qualifiers and supported qualifier values.
office - Identifies all themes containing "Office" in their names.
office2007 - Identifies all themes containing "Office2007" in their names.
office2010 - Identifies all themes containing "Office2010" in their names.
office2013 - Identifies all themes containing "Office2013" in their names.
office2016 - Identifies all themes containing "Office2016" in their names.
metropolis - Identifies the themes: "MetropolisDark", "TouchlineDark" and "MetropolisLight".
standard - Identifies the themes: "Seven" and "VS2010".
DevExpress - Identifies the themes: "DXStyle", "LightGray" and "DeepBlue".
themeName - A qualifier value can be a specific theme name (except touch-aware themes). This allows you to target a specific theme. See the List of DevExpress WPF Themes topic for a list of available themes.
black - Identifies dark themes: Office2016Black, Office2010Black, MetropolisDark and TouchlineDark.
white - Identifies all other themes.
touch - Identifies touch-aware themes. These theme names end with ";Touch". The theme list includes: "Office2013;Touch", "Office2013LightGray;Touch" and "Office2013DarkGray;Touch".
mouse - Identifies all other themes, which are not touch-aware.
Qualifiers of DPI Settings
The following table covers DPI setting qualifiers.
A value that specifies the target DPI setting, in percentage. Supported DPI values include, but are not limited to: 80, 100, 120, 125, 140, 150, 160, 175, 180, 200, 225, 250, etc.
Qualifiers of Application Language (Culture)
The following table covers application language (culture) qualifiers.
A unique name identifying a target culture, based on RFC 4646. Here is the description from the CultureInfo Class topic in MSDN.
"The name is a combination of an ISO 639 two-letter lowercase culture code associated with a language and an ISO 3166 two-letter uppercase subculture code associated with a country or region. In addition, for apps that target .NET Framework 4 or later and are running under Windows 10 or later, culture names that correspond to valid BCP-47 language tags are supported."