ResourceDictionary.ThemeDictionaries property

Applies to Windows and Windows Phone

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 be intended to supply theme values for named resources that are otherwise consumed by other resources.

Note   Inside each dictionary, keys for individual resources are not unique, which is intentional so that the theme resources can replace other resources. For example, a theme dictionary for "HighContrast" might include redefinitions for some or all of the Brush or Color keyed resources used elsewhere in other style or transition resources, in order to produce the necessary contrast levels to satisfy high-contrast design requirements.

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 aren't intended to supply the definition of an entire app theme. They're only for certain non-brush resources used in composition such as glyphs, where the resource should be different between the themes for design reasons. The resources in ThemeDictionaries are intended for scenarios where design considerations interact with certain run-time considerations or app fundamentals such as accessibility. In particular, different resources might be needed for high contrast themes which are active when the user specifically requests high contrast as a system setting. For more info on the high contrast scenario, see Supporting high-contrast themes. For more info on app themes, see RequestedTheme or XAML requested theme sample.

Brush resources are often theme-specific, but aren't defined in StandardStyles.xaml and ThemeDictionaries. Instead these are system theme resources, which you can reference but not override.

The expected keys for the basic app themes are "Light" and "Dark". You should also have a "HighContrast" keyed theme dictionary. There are other named high contrast themes, but the "HighContrast" key is the fallback for high contrast if no other themes 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 define these 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 or use system theme resources so they can respond to themes, so the starting content of ThemeDictionaries 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

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
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:
© 2014 Microsoft