Welcome Sign in
Silverlight Developer Center
Click to Rate and Give Feedback
MSDN
MSDN Library
Web Development
Silverlight
 Property Path Syntax
Silverlight
Property Path Syntax

The PropertyPath object supports a string-based syntax for setting various properties that take the PropertyPath type as their value. A property path string might be set directly to an attribute in XAML. The same string syntax can be used to set the Path property for a PropertyPath that sets the equivalent property in code. There are two distinct feature areas that use a property path: data binding, and animation targeting. Data binding and animation targeting each evaluate the paths differently, and thus this topic describes property path syntax separately for data binding and for animation targeting.

This topic contains the following sections.

PropertyPath is a common object that is used in several Silverlight features. Despite using the common PropertyPath to convey property path information, the usages for each feature area where PropertyPath is used as a type vary. Therefore, it is more practical to document the syntax on a per-feature basis.

Primarily, Silverlight uses PropertyPath to describe object-model paths for traversing the properties of an object that is used as a data binding source, and to describe the target path for targeted animations.

Data binding is a Silverlight feature whereby you can bind to the target value of any dependency property. The source property value for a data binding need not be a dependency property; it can be a property on a CLR object so long as certain conditions are met.

A key to understanding property paths in data binding is that you can target the binding to an individual property value, or you can instead bind to target properties that take lists or collections. If you are binding collections, then your property path should reference a collection, not individual collection items. The data binding engine will match the collections of source to target automatically, resulting in behavior such as populating a ListBox with an items array.

Single Property on the Immediate Object as Data Context

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

propertyName must resolve to be the name of a property that is in the current DataContext for a Path usage. If your binding updates the source, that property must be read/write and the source object must be mutable.

Multiple Property (Indirect Property Targeting)

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

propertyName must resolve to be the name of a property that is the current DataContext. 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 meets the general criteria (property must be public; must be mutable if used for two-way binding.)

Single Property, Attached or Waiting for Context Through Style/Template

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

The parentheses indicate that this property in a PropertyPath should be constructed using a partial qualification. 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 http://schemas.microsoft.com/winfx/2006/xaml/presentation namespace, so a prefix is usually only necessary for custom types or types otherwise outside that namespace. propertyName must resolve to be the name of a property existing on the ownerType. This syntax is generally used for one of the following cases:

  • The path is specified in XAML that is in a style or template that does not have a specified Target Type. A qualified usage is generally not valid for cases other than this, because in non-style, non-template cases, the property exists on an instance, not a type.

  • The property is an attached property.

  • You are binding to a static property. In this case, ownerType really is a type.

For use as storyboard target, the property specified as propertyName must be a DependencyProperty.

Source Traversal (Binding to Hierarchies of Collections)

<object Path="propertyName/propertyNameX" .../>

The / in this syntax is used to navigate within a hierarchical data source object, and multiple steps into the hierarchy with successive / characters are supported. The source traversal accounts for the current record pointer position, which is determined by synchronizing the data with the UI of its view.

For animations, a property path is used to define the connection between the named animation target object's property and the intended target animation property, by traversing object-property relationships in the property values.

The target property of an animation must be a dependency property. The property that starts the path must resolve to be the name of a dependency property that exists on the specified Storyboard..::.TargetName type. The targeted property on a type and the eventual animated property can exist on different objects.

Single Property on the Target Object

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

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

Indirect Property Targeting

<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 specified Storyboard..::.TargetName type.

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 by x:Name or Name. Although template and style elements also can have names, those names are only valid within the namescope of the style and template. (If templates and styles did share namescopes with application markup, names could not be unique. The styles and templates are literally shared between instances and would perpetuate duplicate names.) Thus, if the individual properties of an element that you might wish to animate came from a style or template, you need to start with a named element instance that is not from a style template, and then target into the style or template visual tree to arrive at the property you wish to animate.

For instance, the Background property of a Panel is a complete Brush (actually a SolidColorBrush) that came from a default template. To animate a Brush completely, there would need to be a BrushAnimation (probably one for every Brush type) and 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 sub-properties 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 sub-properties must exist on the preceding property's value type. A slightly more verbose form that qualifies subsequent subproperty owning types is also acceptable; for example, "(Rectangle.Fill).(SolidColorBrush.Color)".

Attached Properties

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

The parentheses indicate that this property in a PropertyPath should be constructed using a partial qualification. 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 only necessary for custom types or types otherwise outside that namespace. propertyName must resolve to be the name of a property existing on the ownerType. The property specified as propertyName must be a DependencyProperty. (All Silverlight  attached properties are implemented as dependency properties, so this issue is only of concern for custom attached properties.)

Indexers

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

Most dependency properties do not support an indexer. Therefore, the only usage for an indexer in an animation path is at an intermediate position between the property that starts the chain on the named target and the eventual animated property. In the provided syntax, that is propertyName2. For instance, 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.

You can use the PropertyPath..::.PropertyPath signature for either data binding or animation targeting usages, and use the sections above for guidance on the specific string syntax to use for the constructor string parameter.

Because the second parameter of the PropertyPath constructor is keyworded as params in C# and ParamArray in Visual Basic, the second parameter is effectively optional for most practical usages, and is typically not specified.

In code, rather than using a property path string, you also have the option to create a PropertyPath by specifying a DependencyProperty identifier, with the PropertyPath..::.PropertyPath constructor signature. This is appropriate if you are only referencing a single property and not truly a "property path" in the literal sense where the path has intermediate properties. Specifying a PropertyPath by DependencyProperty identifier is potentially useful because with the identifier there is no ambiguity regarding the owner type of the relevant dependency property.

Tags What's this?: Add a tag
Community Content   What is Community Content?
Add new content RSS  Annotations
© 2008 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Page view tracker