Storyboard.TargetProperty
Microsoft Silverlight will reach end of support after October 2021. Learn more.
Gets or sets the property that should be animated.
<object Storyboard.TargetProperty="propertyName" .../>
value = object["Storyboard.TargetProperty"]
object["Storyboard.TargetProperty"] = value
Property Value
Type: string
The name of the property to animate.
This property is read/write. The default value is null.
propertyName Grammar
Storyboard.TargetProperty can target a property simply by naming the property. Storyboard.TargetProperty also supports more complex forms of property name specifications, including targeting an object and then the properties of that object, or accessing child objects in collections and then accessing the properties of those child objects.
Scheme |
Grammar |
Example |
|---|---|---|
Simple property name |
propertyName |
"Width" |
Multiple objects and subproperties |
(objectType1.sPropName1).sPropName2 |
"(Rectangle.Fill).Color" |
Item from a collection, and then subproperty of that object |
collectionProp[index].sPropName |
"(Rectangle.RenderTransform).Children[1].Angle" |
Attached property name |
(ownerType.propertyName) |
"(Canvas.Left)" |
A property chain can be greater than two. For instance, the collection example is actually a chain of three properties, the middle of which is a collection property.
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, subproperties need only be named, not qualified with owning types, but those subproperties 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)".
Remarks
This property is an example of a Storyboard-specific attached property, which non-Storyboard objects can set.
Notice the script syntax, which resembles an indexer or array syntax. The ["propertyName"] form (with no dot separating it and the target object) is necessary to get or set an attached property such as Storyboard.TargetProperty in script.
The value of Storyboard.TargetProperty must refer to an existing property of the element that is referenced by Storyboard.TargetName.
Storyboard.TargetProperty supports the concept of indirect property targeting. Indirect property targeting is necessary when the type of the property that is being animated is itself an object, but the actual animated value is a subproperty of that object instead of the object type itself. This is particularly necessary when markup cannot provide a name for targeting the subobject, perhaps because it was specified originally in XAML attribute form instead of as a XAML object element. For example, to animate the Fill of a Rectangle using a linear interpolation of a SolidColorBrush, you would specify a ColorAnimation and give it a Storyboard.TargetProperty value of "(Rectangle.Fill).Color".
Another scenario for using property paths is if you are applying an animation to objects that were added into a collection at run time, and you did not choose to apply a Name to the added objects. In this case, you might name the object that holds the collection and then use the property path syntax to iterate to a specific index. In this way, you would be able to target an animation to an object that has no name but that exists as a subproperty of a named object.
Attempting to set Storyboard.TargetProperty on a running animation will raise a run-time SetValue method error. However, you can use scripting to retarget existing animations that are not yet running or have called Stop. If you retarget animations, you usually want to use a target that is the same type, or that shares the property because of a base object definition. If you retarget an animation by changing Storyboard.TargetName, and Storyboard.TargetProperty references an unsupported property, you will get a run-time error.
The property you target must use the type of the animation that you are applying. For example, if you want to animate properties of an EllipseGeometry, you would use a DoubleAnimation (or DoubleAnimationUsingKeyFrames) to animate RadiusX or RadiusY, and a PointAnimation (or PointAnimationUsingKeyFrames) to animate Center. A mismatch of types will raise a parser error. The types must be exact matches; there is no implicit type conversion for animated properties. For example, you cannot animate a target of "(Canvas.ZIndex)" with a DoubleAnimation because Canvas.ZIndex takes an integer, not a double.
For the propertyName syntax that involves collections, the collection cannot be the last item in the property chain, because Silverlight object types contained in the collections cannot be directly animated with the Double, Color and Point animation types that are supported in Silverlight under the JavaScript API. You must terminate the property chain with a property of the object that comes from an index in a collection.