Automatically Choosing Images Based on App Context

• Mar 13, 2021
• 5 minutes to read

This topic describes how to display different images in a control based on the app context. The app context is defined by one or multiple application and system settings:

• the system DPI setting;
• the application language (UI culture);
• the application’s paint theme;
• touch mode availability.

This topic contains the following sections:

• Overview
• Naming Convention
• Qualifiers of Themes
• Qualifiers of DPI Settings
• Qualifiers of Application Language (Culture)

Overview

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.

XAML

xmlns:dxb="http://schemas.devexpress.com/winfx/2008/xaml/bars"
xmlns:dx="http://schemas.devexpress.com/winfx/2008/xaml/core"

<dxb:ToolBarControl>
    <dxb:BarButtonItem Glyph="{dx:QualifiedImage Uri=Images/Add.png}" Content="Add"/>
</dxb:ToolBarControl>

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”:

XAML

...
    <dxb:BarButtonItem Glyph="{dx:QualifiedImage Uri=Images/Add.png}" Content="Add"/>

Naming Convention

To use qualifiers in image names, use the following naming conventions.

Naming Convention	Examples
filename.qualifiername-value.ext	remove.contrast-black.png clear.theme-office.png
filename.qualifiername-value_qualifiername-value.ext	next.theme-office_contrast-white.png prev.theme-office_contrast-black_scale-200.png

To use qualifiers in folder names, use the following naming conventions.

Naming Convention	Examples
foldername/qualifiername-value/filename.ext	folder/theme-metropolis/add.png
foldername/qualifiername-value_qualifiername-value/filename.ext	folder/theme-metropolis_contrast-black/add.png folder/theme-metropolis_contrast-black_lang-en-US/add.png
foldername/qualifiername-value/qualifiername-value/filename.ext	folder/theme-metropolis/contrast-black/add.png folder/theme-metropolis/contrast-black_lang-en-US/add.png folder/theme-metropolis/contrast-black/lang-en-US/add.png

You can combine the two approaches by using qualifiers in folder and image names simultaneously.

folder/lang-en-US/file.theme-office.png

Available qualifiers and their values are described in the following sections.

Qualifiers of Themes

The following table covers theme qualifiers and supported qualifier values.

Qualifier Name	Qualifier Values
theme	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. Examples: theme-Office theme-DevExpress theme-Metropolis theme-MetropolisDark theme-DXStyle theme-Office2013LightGray
contrast	black - Identifies dark themes: Office2016Black, Office2010Black, MetropolisDark and TouchlineDark. white - Identifies all other themes. Examples: contrast-black contrast-white
input	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. Examples: input-touch input-mouse

Qualifiers of DPI Settings

The following table covers DPI setting qualifiers.

Qualifier Name	Qualifier Values
scale	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. Examples: scale-150 scale-80

Qualifiers of Application Language (Culture)

The following table covers application language (culture) qualifiers.

Qualifier Name

Qualifier Values

lang

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.” See the following article for information on available culture identifiers: Language Identifier Constants and Strings. Examples: lang-en-US lang-tr-TR