Skip to main content

Automatically Choosing Images Based on App Context

  • 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.

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.

ImageSelectionAppContext-SolutionExplorer-Images-QualifiersInNames

The following code assigns the Add.png image to a button in a toolbar using the QualifiedImage extension.

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.

ImageSelectionAppContext-SolutionExplorer-Images-QualifiersInFolders

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

...
    <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

See Also