Property Path Syntax

<Binding Path="propertyName" .../>

propertyName must resolve to the name of a property that is in the current DataContext or is a specific dependency object source specified by ElementName or RelativeSource. If your binding updates the source (TwoWay), that property must be read/write and the source object must be mutable.

<Binding Path="propertyName.propertyName2" .../>
-or-
<Binding Path="propertyName.propertyName2.propertyName3" .../>
-etc.-

propertyName must resolve to the name of a property that is in the current DataContext or is a specific dependency object source specified by ElementName or RelativeSource. The path properties propertyName and propertyName2 can be any properties that exist in a relationship, where propertyName2 is a property that exists on the type that is the value of propertyName. This syntax can extend beyond two properties: you can traverse into the object tree to return deeply nested properties, so long as every property along the path meets general criteria (all pathed properties must be public; the end property must be public and must be mutable, end property must be read/write if used for two-way binding.)

<Binding Path="(ownerType.propertyName)" .../>

The parentheses indicate that this property in a PropertyPath should be constructed using a partial qualification because it needs late-binding context information, such as the type being applied to for applied templates. It can use a prefix usage for a XAML namespace to find the type. The ownerType searches types that a XAML processor has access to, based on xmlns mappings (or using the default XAML namespace if unqualified). propertyName must resolve to the name of a property that exists on the ownerType.

<object Path="...(ownerType.propertyName)..." .../>

The parentheses indicate that this portion in a PropertyPath should be constructed using an owner qualification rather than traversal. It can use a prefix usage for a XAML namespace to find the type. propertyName must resolve to the name of a property that exists on the ownerType. The property specified as propertyName must be a DependencyProperty. (All Silverlight attached properties are implemented as dependency properties, so this is a concern only for custom attached properties. Also, attached properties generally appear in paths only when ElementName or RelativeSource specifies the source, because using a DependencyObject for a business object data source is uncommon.)

Indexers can be used for accessing properties in a path and obtaining items from a list, but with some notable restrictions:

• Numeric integer indexers are supported.

• Beginning in Silverlight 4, string indexers are supported.

• Only one-dimensional array indexing is supported.

• The type being indexed must implement or inherit IList. (List<T> is accepted, because it implements IList. However IList<T> is not accepted.)

Numeric integer indexes are specified by declaring the zero-based index within bracket ([]) characters after the property name; for example, Employees[2].

Property path evaluation first attempts to use integer indexing for a collection. If that indexing is not valid for the collection, then the information within [] is processed as a string. String indexing from a property path generally expects a collection / business object that is a dictionary with string keys. String indexing supports binding to dynamic data objects where the CLR structure of the data source can change, but the string keys represent a data contract that can still be bound to by a client UI.

Validation uses indexers to access items of an attached property's collection as part of its property path usage. The validation structure for the application can declare UI states within templates that are used only when validation errors are raised, and can then reference the active error objects in that context. For example, the following is a property path for a binding that accesses the first item in a Validation.Errors collection; the context of the property path is modified by RelativeSource so that the errors are checked only at run time on the applied template:

<TextBlock Text="{Binding RelativeSource={RelativeSource TemplatedParent}, Path=(Validation.Errors)[0].Exception.Message }">

Silverlight includes some properties where there is a text syntax that resembles a property path syntax because it is parsed to result in a "dot-down" traversal of an object model. However, these are not a true property path, in that the properties do not use the PropertyPath type. Examples of such properties are ItemsControl.DisplayMemberPath and Selector.SelectedValuePath. The usages described in this topic do not necessarily apply to such properties. Generally, such Path properties support a simple dot-down traversal of a CLR object model for their associated source, and do not support XAML namespace qualification or context deferral.

<animation Storyboard.TargetProperty="propertyName" .../>

propertyName must resolve to the name of a dependency property that exists on the type specified by Storyboard.TargetName.

<animation Storyboard.TargetProperty="(objectType.propertyName).propertyName2" .../>

objectType must be the type name of a type that has propertyName available as a member.

propertyName must be a property that exists on the type specified by Storyboard.TargetName.

propertyName2 must be the name of a dependency property that exists on the object that is the value of propertyName. In other words, propertyName2 must exist as a dependency property on the type that is the propertyName property type.

Indirect targeting of animations is necessary because of applied styles and templates. In order to target an animation, you need a TargetName on a target object, and that name is established on the target by x:Name or Name. Although template and style elements also can have names, those names are valid only within the XAML namescope of the style and template. (Styles and templates are literally shared between instances and would perpetuate duplicate names if XAML namescopes were extended here.) Thus, if the individual properties of an element that you want to animate come from a style or template, you need to start with a named element instance that is not from a style template. You then specify a path into the applied template-created visual tree that exists at run time to target the property you wish to animate.

For example, the Background property of a Panel is a complete Brush (actually a SolidColorBrush) that comes from a default template. To animate a Brush completely, there would need to be a BrushAnimation (probably one for every Brush type), but there is no such type. To animate a Brush, you instead animate properties of a particular Brush type. You need to get from SolidColorBrush to its Color to apply a ColorAnimation there. The property path for this example would be Background.Color.

In the multiple objects and subproperties form, you must use an owning object to disambiguate the initial property and place parentheses around this initial object.property combination. Thereafter, sub-properties need only be named, not qualified with owning types, but those subproperties must exist on the type of the preceding property in the property path. A slightly more verbose form that qualifies subsequent subproperty owning types is also acceptable; for example, "(Rectangle.Fill).(SolidColorBrush.Color)".

<animation Storyboard.TargetProperty="(ownerType.propertyName)" .../>

The parentheses indicate that this property in a PropertyPath should be constructed using an ownerType qualification, not a traversal. It can use an XML namespace to find the type. The ownerType searches types that a XAML processor has access to, through the XmlnsDefinitionAttribute declarations in each assembly. Most applications have the default XML namespace mapped to the Silverlight client namespace, so a prefix is usually necessary only for custom types or types otherwise outside that namespace. propertyName must resolve to the name of a property that exists on the ownerType. The property specified as propertyName must be a DependencyProperty. (All Silverlight attached properties are implemented as dependency properties, so this is a concern only for custom attached properties.)

<animation Storyboard.TargetProperty="propertyName.propertyName2[index].propertyName3" .../>

Most dependency properties do not support an indexer. An indexer in an animation path should be at an intermediate position between the property that starts the chain on the named target and the eventual animated property. In the syntax shown, that is propertyName2. For example, an indexer usage might be necessary if the intermediate property is a collection such as TransformGroup, in a property path such as RenderTransform.Children[1].Angle.