Resource Dictionary. Theme Dictionaries Property

Definition

Gets a collection of merged resource dictionaries that are specifically keyed and composed to address theme scenarios, for example supplying theme values for «HighContrast».

Property Value

A dictionary of ResourceDictionary theme dictionaries. Each must be keyed with x:Key.

Examples

This example shows a ThemeDictionaries dictionary that defines brush styles for a «Default» theme, two existing «HighContrast*» themes that map to user theme choices for high contrast, and a custom high contrast theme. The dictionary is used by a control template for a custom control. This is part of the High contrast sample.

The starting Microsoft Visual Studio templates for a UWP app using C++, C#, or Visual Basic include a ThemeDictionaries node in the XAML file that is the starting MergedDictionaries value for an app.xaml file. All the built-in Windows Runtime controls already have high-contrast themes defined elsewhere (the native equivalent of generic.xaml) or use system theme resources so they can respond to themes, so the starting content of an app-specific ThemeDictionaries resource set is minimal. It’s only once you start defining custom controls or app-specific theme styles that you’ll see more resource definitions here.

Remarks

Theme dictionaries have two primary scenarios: resources for your own app, and resources that the system provides for you on a per-theme basis. You’ll only need to set values for the ThemeDictionaries resource set if you’re defining your own app resources in app.xaml. Otherwise, the markup extension usages you’ll be using in XAML control templates and elsewhere are typically referring to the system ThemeDictionaries resources, which can be viewed for design purposes within the generic.xaml design file.

Brush resources are often theme-specific. Default Windows Runtime XAML control UI defines many brush resources that are used for the various default XAML controls. You can see these resource definitions as part of the generic.xaml design file. The system ThemeDictionaries definitions are located early in the file, so that they are lexically forward of the markup extensions that reference them from within the default control templates. Your own page definitions and custom control definitions can make markup extension references to the system-supplied theme resources. In fact that’s a recommended practice if you are writing controls that are intended to be in the same UI as the default controls. The default controls are using the theme resources extensively, and using the theme resources in your own controls can help prevent visual mismatches if the user changes the theme at runtime, or if the app is running under a theme that you hadn’t specifically designed for.

There are also non-brush resources in the system theme resources in generic.xaml, such as default measures and font properties.

Theme dictionaries that you specify for individual apps aren’t intended to supply the resource definition of an entire app theme. Instead, you should factor your page UI and custom control definitions to use system theme resources whenever possible, and to use app-specific theme resources for just a few cases where you want to override the system default values. For page-level app UI you typically only need new theme resources for certain non-brush resources used in composition such as glyphs or path-based graphics. The resources in ThemeDictionaries that you define yourself are intended for scenarios like accessibility. In particular, different resources might be needed for high contrast themes. For more info on the high contrast scenario, see High-contrast themes. For more info on system-supplied themes, see RequestedTheme or XAML requested theme sample.

The expected keys for the basic themes are «Light» and «Dark».

For custom controls, you should also have a «HighContrast» keyed theme dictionary whenever you have theme dictionaries for «Light» and «Dark». There are other named high contrast themes, but the «HighContrast» theme key is the fallback the system uses for finding the high contrast theme if no other theme resources for high contrast are available.

For custom controls, if you don’t support «Light» and «Dark» themes and only support one theme as well as at least one «HighContrast» theme, you can change your main dictionary’s x:Key attribute to «Default». «Default» is the ResourceDictionary that will be used if a ResourceDictionary in the specified theme (such as «Dark») cannot be found.

For high contrast themes and custom control scenarios, in addition to system brush resources, there are also system color resources such as «SystemColorButtonFaceColor» that you can assign to be the Color value of SolidColorBrush resources. You can use these as values for your «HighContrast» theme dictionary and also «Default». If the resource exists for each of the themes your control supports, the XAML templates will load the appropriate resource for the theme that’s active.

Application. Requested Theme Property

Definition

Gets or sets a value that determines the light-dark preference for the overall theme of an app.

Property Value

A value of the enumeration. The initial value is the default theme set by the user in Windows settings.

Examples

This example shows how to save the requested theme in local app settings, and then retrieve and apply it when the app is restarted.

App.xaml.cs

Remarks

There are two built in themes: «Light» and «Dark». By default your app runs using the theme set by the user in Windows settings (Settings > Personalization > Colors > Choose your default app mode). You can set the app’s RequestedTheme property to override the user default and specify which theme is used.

The theme can only be set when the app is started, not while it’s running. Attempting to set RequestedTheme while the app is running throws an exception (NotSupportedException for Microsoft .NET code). If you give the user an option to pick a theme that’s part of app UI, you must save the setting in the app data and apply it when the app is restarted. (For more info about app settings, see Store and retrieve settings and other app data).

You can change specific theme values at run-time after Application.RequestedTheme is applied, if you use the FrameworkElement.RequestedTheme property and sets values on specific elements in the UI.

There is also a «HighContrast» theme that uses system values, but apps and app code use a different technique for switching the app to high contrast. The RequestedTheme property is ignored if the user is running in high contrast mode. See High-contrast themes and XAML high contrast style sample.

Although the app can’t switch the themes at run-time, the user can (starting with WindowsВ 8.1). For example, a user might enable a high-contrast theme while your app is running, by using the Alt+Shift+PrtScn key shortcut. If this happens, the XAML resource system will recalculate the resource values for any markup extension usage. Theme-appropriate resources such as colors and brushes then use values appropriate for the current theme, even though it wasn’t the app that requested that theme originally.

The resources that are theme-specific are typically defined in a separate resource dictionary in XAML. This resource dictionary comes from the ThemeDictionaries property of the primary ResourceDictionary that is used for control templates. The default system resource dictionary for theme-specific resources is named ThemeResources.xaml. This file is available in the (Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP \Generic folder from a Windows Software Development Kit (SDK) installation.

Notes for Windows 8

(This section applies only to apps for Windows 8, not UWP apps for Windows 10.)

markup extension

Provides a value for any XAML attribute by evaluating a reference to a resource, with additional system logic that retrieves different resources depending on the currently active theme. Similar to markup extension, resources are defined in a ResourceDictionary, and a ThemeResource usage references the key of that resource in the ResourceDictionary.

XAML attribute usage

XAML values

Term	Description
key	The key for the requested resource. This key is initially assigned by the ResourceDictionary. A resource key can be any string defined in the XamlName Grammar.

Remarks

A ThemeResource is a technique for obtaining values for a XAML attribute that are defined elsewhere in a XAML resource dictionary. The markup extension serves the same basic purpose as the markup extension. The difference in behavior versus markup extension is that a ThemeResource reference can dynamically use different dictionaries as the primary lookup location, depending on which theme is currently being used by the system.

When the app first starts, any resource reference made by a ThemeResource reference is evaluated based on the theme in use at startup. But if the user subsequently changes the active theme at run-time, the system will re-evaluate every ThemeResource reference, retrieve a theme-specific resource that may be different, and redisplay the app with new resource values in all appropriate places in the visual tree. A StaticResource is determined at XAML load time / app startup and won’t be re-evaluated at run-time. (There are other techniques such as visual states that reload XAML dynamically, but those techniques operate at a higher level that the basic resource evaluation enabled by markup extension).

ThemeResource takes one argument, which specifies the key for the requested resource. A resource key is always a string in Windows Runtime XAML. For more info on how the resource key is initially specified, see x:Key attribute.

For more info on how to define resources and properly use a ResourceDictionary, including sample code, see ResourceDictionary and XAML resource references.

Important As with StaticResource, a ThemeResource must not attempt to make a forward reference to a resource that is defined lexically further within the XAML file. Attempting to do so is not supported. Even if the forward reference doesn’t fail, trying to make one carries a performance penalty. For best results, adjust the composition of your resource dictionaries so that forward references are avoided.

Attempting to specify a ThemeResource to a key that cannot resolve throws a XAML parse exception at run time. Design tools may also offer warnings or errors.

In the Windows Runtime XAML processor implementation, there is no backing class representation for ThemeResource. The closest equivalent in code is to use the collection API of a ResourceDictionary, for example calling Contains or TryGetValue.

ThemeResource is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in XAML use the «<" and ">» characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup extension must process the attribute.

When and how to use rather than

The rules by which a ThemeResource resolves to an item in a resource dictionary are generally the same as StaticResource. A ThemeResource lookup can extend into the ResourceDictionary files that are referenced in a ThemeDictionaries collection, but a StaticResource can do that also. The difference is that a ThemeResource can re-evaluate at run-time and a StaticResource can’t.

The set of keys in each theme dictionary should provide the same set of keyed resources no matter which theme is active. If a given keyed resource exists in the HighContrast theme dictionary, then another resource with that name should also exist in Light and Default. If that isn’t true, resource lookup might fail when the user switches themes and your app won’t look right. It is possible though that a theme dictionary can contain keyed resources that are only referenced from within the same scope to provide sub-values; these don’t need to be equivalent in all themes.

In general you should place resources in theme dictionaries and make references to those resources using ThemeResource only when those values can change between themes or are supported by values that change. This is appropriate for these kinds of resources:

• Brushes, in particular colors for SolidColorBrush. These make up about 80% of the ThemeResource usages in the default XAML control templates (generic.xaml).
• Pixel values for borders, offsets, margin and padding and so on.
• Font properties such as FontFamily or FontSize.
• Complete templates for a limited number of controls that are usually system-styled and used for dynamic presentation, like GridViewItem and ListViewItem.
• Text display styles (usually to change font color, background, and possibly size).

The Windows Runtime provides a set of resources that are specifically intended to be referenced by ThemeResource. These are all listed as part of the XAML file themeresources.xaml, which is available in the include/winrt/xaml/design folder as part of the Windows Software Development Kit (SDK). For documentation on the theme brushes and additional styles that are defined in themeresources.xaml, see XAML theme resources. The brushes are documented in a table that tells you what color value each brush has for each of the three possible active themes.

The XAML definitions of visual states in a control template should use ThemeResource references whenever there’s an underlying resource that might change because of a theme change. A system theme change won’t typically also cause a visual state change. The resources need to use ThemeResource references in this case so that values can be re-evaluated for the still-active visual state. For example, if you have a visual state that changes a brush color of a particular UI part and one of its properties, and that brush color is different per-theme, you should use a ThemeResource reference for providing that property’s value in the default template and also any visual state modification to that default template.

ThemeResource usages might be seen in a series of dependent values. For example, a Color value used by a SolidColorBrush that is also a keyed resource might use a ThemeResource reference. But any UI properties that use the keyed SolidColorBrush resource would also use a ThemeResource reference, so that it’s specifically each Brush-type property that’s enabling a dynamic value change when the theme changes.

NoteВ В and run-time resource evaluation on theme switching is supported in WindowsВ 8.1 XAML but not supported in XAML for apps targeting WindowsВ 8.

System resources

Some theme resources reference system resource values as an underlying sub-value. A system resource is a special resource value that isn’t found in any XAML resource dictionary. These values rely on behavior in Windows Runtime XAML support to forward values from the system itself, and represent them in a form that a XAML resource can reference. For example, there is a system resource named «SystemColorButtonFaceColor» that represents an RGB color. This color comes from the aspects of system colors and themes that aren’t just specific to Windows Runtime and Windows Runtime apps.

System resources are often the underlying values for a high-contrast theme. The user is in control of the color choices for their high-contrast theme, and the user makes these choices using system features that also aren’t specific to Windows Runtime apps. By referencing the system resources as ThemeResource references, the default behavior of the high-contrast themes for Windows Runtime apps can use these theme-specific values that are controlled by the user and exposed by the system. Also, the references are now marked for re-evaluation if the system detects a run-time theme change.

An example usage

Here’s some example XAML taken from the default generic.xaml and themeresources.xaml files to illustrate how to use ThemeResource. We’ll look at just one template (the default Button) and how two properties are declared (Background and Foreground) to be responsive to theme changes.

Here, the properties take a Brush value, and the reference to SolidColorBrush resources named ButtonBackgroundThemeBrush and ButtonForegroundThemeBrush are made using ThemeResource.

These same properties are also adjusted by some of the visual states for a Button. Notably, the background color changes when a button is clicked. Here too, the Background and Foreground animations in the visual state storyboard use DiscreteObjectKeyFrame objects and references to brushes with ThemeResource as the key frame value.

Each of these brushes is defined earlier in generic.xaml: they had to be defined prior to any templates using them to avoid XAML forward references. Here’s those definitions, for the «Default» theme dictionary.

Then each of the other theme dictionaries also has these brushes defined, for example:

Here the Color value is another ThemeResource reference to a system resource. If you reference a system resource, and you want it to change in response to a theme change, you should use ThemeResource to make the reference.

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.

Design-time tools support for the markup extension

Microsoft Visual StudioВ 2013 can include possible key values in the Microsoft IntelliSense dropdowns when you use the markup extension in a XAML page. For example, as soon as you type «