Section 5.1. Using Resources

5.1. Using Resources

When adding resources, you must add the appropriate namespace to the root element. You'll also need to give it a name to differentiate it from the default namespace. The default namespace, which references Avalon, contains the definitions of Avalon elements, such as Button, Page, and StackPanel. The namespace that must be added to define resources is the XAML namespace and describes the language itself.

Because resource definitions require the use of XAML-specific tagswhich are not described by the default namespaceyou must declare a reference to the XAML namespace and use it to prefix those attributes found only there, such as Key.

The key is a fully qualified attribute comprising the namespace, a colon, and the keyword Key. Elements defined as a resource must have a declared "key name" to be referenced by other elements. The value of the attribute is the name by which the resource will be referenced by other elements.

Resources are added by explicitly declaring elements as children of the Resources attribute of an element.

In Example 5-1, there are two instances of SolidColorBrush defined as resources: RedBrush and BlueBrush.

Example 5-1. Using resources to define global styles

 <Page     xmlns="http://schemas.microsoft.com/winfx/avalon/2005"     xmlns:x="http://schemas.microsoft.com/winfx/xaml/2005"     <Page.Resources>         <SolidColorBrush             x:Key="RedBrush"             Color="red"/>         <SolidColorBrush             x:Key="BlueBrush"             Color="blue"/>     </Page.Resources>     <StackPanel>         <Button             Background="{StaticResource RedBrush}" />         <Ellipse             Fill="{StaticResource BlueBrush}"             Margin="40"             Width="15"             Height="25"/>     </StackPanel> </Page> 

Resources must be declared in the file before they can be accessed. This is because the runtime engine interprets XAML as a stream of binary input and doesn't understand that a resource might be defined later in the stream. It can't render an element if a resource is required but hasn't yet been declared. In Example 5-2, the resource RedBrush is referenced before it is declared.

Example 5-2. Illegal use of a local resource

 <Button     Content="Click Me"     Background="{StaticResource RedBrush}" >     <Button.Resources>         <SolidColorBrush             x:Key="RedBrush"             Color="Red" />     </Button.Resources> </Button> 

This will result in an error in XamlPad and, although it will compile using MSBuild, it will raise a runtime exception. If you absolutely must declare a local resource, you'll have to declare it first, then explicitly declare the attribute that references the resource. Example 5-3 shows an example of declaring a local resource and then referencing it from within an explicitly declared attribute.

Example 5-3. Legal use of a resource

 <Button Content="Click Me">     <Button.Resources>         <SolidColorBrush                x:Key="RedBrush"                Color="Red" />     </Button.Resources>     <Button.Background>         {StaticResource RedBrush}     </Button.Background> </Button> 

There are two ways to access a resource: statically and dynamically. An element references the resource by specifying either the keyword StaticResource or DynamicResource, followed by the key name of the resource. The two methods differ in how the resource in question behaves during the course of the application. If the resource can change through an outside source, it should be accessed dynamically because it will be reloaded and changes will be applied to it. Conversely, static resources assume that the resource in question will not change and therefore will not be reloaded during the application's execution.

In Example 5-1, the Button element declared its background color as the resource RedBrush. Similarly, the Ellipse element specified that its fill attribute should be defined by the resource BlueBrush.

Resources are hierarchical. Locally defined resourcesthose resources defined with the elementoverride resources defined for its parent, and so on. When the XAML processor encounters {StaticResource RedBrush} on the Button, it first checks the Button resources collection. Because Button does not have a definition of RedBrush (its resource collection is empty), it checks the parent of the Button, the StackPanel. When it does not find the definition in StackPanel, it checks its parent, Page, and finds the resource defined. The nature of resources allows you to apply a resource to all elements in the application simply by defining it on the root element.

The closest resource declaration of the same name for any given attribute will be the one applied. If RedBrush is declared as a global resource (in Page.Resources) as a red brush and then declared again locally on a button as a blue brush, the button will have a blue background. The rule is that local resources override global resources with the same key.

The most common use of resources is in defining styles and triggers to dynamically alter the appearance of user-interface elements.