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