Windows Dev Center

ResourceDictionary.ThemeDictionaries property

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

Syntax


public IDictionary<Object, Object> ThemeDictionaries { get; }


<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    oneOrMoreThemeDictionaries
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

XAML Values

oneOrMoreThemeDictionaries

One or more ResourceDictionary object elements. Each such ResourceDictionary must have an x:Key attribute. The value of x:Key must be unique within the resource scope (within the ResourceDictionary and the page it exists in). Each key directly on a ResourceDictionary tag should reference a known theme name. Each resource dictionary and the contents thereof should supply theme-specific resources that are referenced by ThemeResource markup extensions.

Note   Inside each theme-specific resource dictionary, keys for individual resources are not unique, which is intentional so that the theme resources are defined in parallel for each theme.

Property value

Type: IMap<Object, Object> [C++] | System.Collections.Generic.IDictionary<Object, Object> [.NET]

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

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 ThemeResource 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 ThemeResource markup extensions that reference them from within the default control templates. Your own page definitions and custom control definitions can make ThemeResource 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 Supporting 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 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.

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.


<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries> 
    <ResourceDictionary x:Key="Default"> 
      <SolidColorBrush x:Key="TargetBackground" Color="Red"/> 
      <SolidColorBrush x:Key="TargetBorderBrush" Color="Black"/> 
      <SolidColorBrush x:Key="Circle4Fill" Color="Blue"/> 
      <SolidColorBrush x:Key="Circle3Fill" Color="Green"/> 
      <SolidColorBrush x:Key="Circle2Fill" Color="Yellow"/> 
      <SolidColorBrush x:Key="Circle1Fill" Color="White"/> 
      <SolidColorBrush x:Key="CircleStroke" Color="Black"/> 
    </ResourceDictionary> 
    <ResourceDictionary x:Key="HighContrastBlack"> 
       <SolidColorBrush x:Key="TargetBackground" Color="Black"/> 
       <SolidColorBrush x:Key="TargetBorderBrush" Color="White"/> 
       <SolidColorBrush x:Key="Circle4Fill" Color="Black"/> 
       <SolidColorBrush x:Key="Circle3Fill" Color="Black"/> 
       <SolidColorBrush x:Key="Circle2Fill" Color="Black"/> 
       <SolidColorBrush x:Key="Circle1Fill" Color="Black"/> 
       <SolidColorBrush x:Key="CircleStroke" Color="White"/> 
     </ResourceDictionary> 
     <ResourceDictionary x:Key="HighContrastWhite"> 
       <SolidColorBrush x:Key="TargetBackground" Color="White"/> 
       <SolidColorBrush x:Key="TargetBorderBrush" Color="Black"/> 
       <SolidColorBrush x:Key="Circle4Fill" Color="White"/> 
       <SolidColorBrush x:Key="Circle3Fill" Color="White"/> 
       <SolidColorBrush x:Key="Circle2Fill" Color="White"/> 
       <SolidColorBrush x:Key="Circle1Fill" Color="White"/> 
       <SolidColorBrush x:Key="CircleStroke" Color="Black"/> 
    </ResourceDictionary> 
    <ResourceDictionary x:Key="HighContrastCustom"> 
      <SolidColorBrush x:Key="TargetBackground" Color="{StaticResource SystemColorButtonFaceColor}"/> 
      <SolidColorBrush x:Key="TargetBorderBrush" Color="{StaticResource SystemColorButtonTextColor}"/> 
      <SolidColorBrush x:Key="Circle4Fill" Color="{StaticResource SystemColorHotlightColor}"/> 
      <SolidColorBrush x:Key="Circle3Fill" Color="{StaticResource SystemColorHotlightColor}"/> 
      <SolidColorBrush x:Key="Circle2Fill" Color="{StaticResource SystemColorHotlightColor}"/> 
      <SolidColorBrush x:Key="Circle1Fill" Color="{StaticResource SystemColorHotlightColor}"/> 
      <SolidColorBrush x:Key="CircleStroke" Color="{StaticResource SystemColorHighlightTextColor}"/> 
    </ResourceDictionary> 
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary> 


The starting Visual Studio templates for a Windows Store 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.


<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <!-- Non-brush values that vary across themes -->
    
    <ResourceDictionary.ThemeDictionaries>
        <ResourceDictionary x:Key="Default">
            <x:String x:Key="BackButtonGlyph">&#xE071;</x:String>
            <x:String x:Key="BackButtonSnappedGlyph">&#xE0BA;</x:String>
        </ResourceDictionary>

        <ResourceDictionary x:Key="HighContrast">
            <x:String x:Key="BackButtonGlyph">&#xE0A6;</x:String>
            <x:String x:Key="BackButtonSnappedGlyph">&#xE0C4;</x:String>
        </ResourceDictionary>
    </ResourceDictionary.ThemeDictionaries>
...
</ResourceDictionary>

Requirements (device family)

Device family

Universal

API contract

Windows.Foundation.UniversalApiContract, introduced version 1.0

Namespace

Windows.UI.Xaml
Windows::UI::Xaml [C++]

Metadata

Windows.Foundation.UniversalApiContract.winmd

Requirements (operating system)

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Xaml
Windows::UI::Xaml [C++]

Metadata

Windows.winmd

See also

ResourceDictionary
MergedDictionaries
AccessibilitySettings
XAML theme resources reference
ResourceDictionary and XAML resource references
UI contrast and settings sample
High contrast sample
XAML requested theme sample
Control and app styling in XAML sample
Supporting high-contrast themes

 

 

Show:
© 2015 Microsoft