Supporting high-contrast themes (XAML)

Applies to Windows and Windows Phone

Looking for the HTML/JavaScript version of this topic? See Supporting high contrast themes (HTML).

A Windows Runtime app using C++, C#, or Visual Basic supports high-contrast themes by default. If a user has chosen that they want the system to use a high-contrast theme from system settings or accessibility tools, the framework automatically uses colors and style settings that produce a high-contrast layout and rendering for controls and components in the UI.

This default support is based on using the default themes and templates. These themes and templates make references to system colors as resource definitions, and the resource sources change automatically when the system is using a high-contrast mode. However, if you use custom templates, themes, and styles for your control, be careful that you do not disable the built-in support for high contrast. If you use one of the XAML designers for Microsoft Visual Studio for styling, the designer generates a separate, high-contrast theme alongside the primary theme whenever you define a template that is significantly different from the default template. The separate theme dictionaries go into the ThemeDictionaries collection, a dedicated property of a ResourceDictionary element.

For more info on themes and control templates, see Quickstart: Control templates. It's often very informative to look at the XAML resource dictionaries and themes for specific controls and see how the themes are constructed and how they reference resources that are similar but different for each possible high-contrast setting.

Detecting when a high-contrast theme is enabled

A Windows Runtime app can use members of the AccessibilitySettings class to detect the current settings for high-contrast themes. The HighContrast property determines whether a high-contrast theme is currently selected. If HighContrast is set to true, then the next step is to check the value of the HighContrastScheme property to get the name of the high-contrast theme that is used. "High Contrast White" and "High Contrast Black" are typically values for HighContrastScheme that your code should respond to. XAML-defined ResourceDictionary keys can't have spaces, so the keys for these themes in a resource dictionary are typically "HighContrastWhite" and "HighContrastBlack" respectively. You should also have fallback logic for a default high-contrast theme in case the value is some other string. XAML high contrast sample shows the logic for this.

Note  Make sure you call the AccessibilitySettings constructor from a scope where the app is initialized and is already displaying content.

Starting with Windows 8.1, apps can switch to using high-contrast resource values while the app is running. This works so long as the resources are requested using the ThemeResource markup extension in the style or template XAML. The default themes (generic.xaml) all use this ThemeResource technique, so you'll get this behavior if you're using default control themes. Custom controls or custom control styling can do this if you've used this ThemeResource resource technique in your custom templates and styles also. However, apps that were built to target Windows 8 do not automatically reload resources while the app is running.

Windows 8 behavior

Windows 8 did not support the ThemeResource markup extension, it is available starting with Windows 8.1. Also, Windows 8 did not support dynamically switching the theme-related resources for a Windows Runtime app. The app had to be restarted in order to pick up the theme change for the XAML templates and styles. This isn't a good user experience, so apps are strongly encouraged to recompile and target Windows 8.1 so that they can use styles with ThemeResource usages and can dynamically switch themes when the user does. Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.

Related topics

UI contrast and settings sample
XAML accessibility sample
XAML high contrast sample
AccessibilitySettings

 

 

Show:
© 2014 Microsoft