Edit

Share via

ThemeDictionary Markup Extension

  • Article

Provides a way for custom control authors or applications that integrate third-party controls to load theme-specific resource dictionaries to use in styling the control.

XAML Attribute Usage

XML 
<object property="{ThemeDictionary assemblyUri}" ... />

XAML Object Element Usage

XML 
<object>  
  <object.property>  
    <ThemeDictionary AssemblyName="assemblyUri"/>  
  <object.property>  
<object>

XAML Values

Value Description
assemblyUri The uniform resource identifier (URI) of the assembly that contains theme information. Typically, this is a pack URI that references an assembly in the larger package. Assembly resources and pack URIs simplify deployment issues. For more information see Pack URIs in WPF.

Remarks

This extension is intended to fill only one specific property value: a value for ResourceDictionary.Source.

By using this extension, you can specify a single resources-only assembly that contains some styles to use only when the Windows Aero theme is applied to the user's system, other styles only when the Luna theme is active, and so on. By using this extension, the contents of a control-specific resource dictionary can be automatically invalidated and reloaded to be specific for another theme when required.

The assemblyUri string (AssemblyName property value) forms the basis of a naming convention that identifies which dictionary applies for a particular theme. The ProvideValue logic for ThemeDictionary completes the convention by generating a uniform resource identifier (URI) that points to a particular theme dictionary variant, as contained within a precompiled resource assembly. Describing this convention, or theme interactions with general control styling and page/application level styling as a concept, is not covered fully here. The basic scenario for using ThemeDictionary is to specify the Source property of a ResourceDictionary declared at the application level. When you provide a URI for the assembly through a ThemeDictionary extension rather than as a direct URI, the extension logic will provide invalidation logic that applies whenever the system theme changes.

Attribute syntax is the most common syntax used with this markup extension. The string token provided after the ThemeDictionary identifier string is assigned as the AssemblyName value of the underlying ThemeDictionaryExtension extension class.

ThemeDictionary may also be used in object element syntax. In this case, specifying the value of the AssemblyName property is required.

ThemeDictionary can also be used in a verbose attribute usage that specifies the Member property as a property=value pair:

XML 
<object property="{ThemeDictionary AssemblyName=assemblyUri}" ... />

The verbose usage is often useful for extensions that have more than one settable property, or if some properties are optional. Because ThemeDictionary has only one settable property, which is required, this verbose usage is not typical.

In the WPF XAML processor implementation, the handling for this markup extension is defined by the ThemeDictionaryExtension class.

ThemeDictionary 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. For more information, see Markup Extensions and WPF XAML.

See also