Storyboard.TargetProperty Property
Gets or sets the property that should be animated.
| XAML |
<object Storyboard.TargetProperty="propertyName" .../>
|
| Scripting |
value = object["Storyboard.TargetProperty"] object["Storyboard.TargetProperty"] = value |
Property Value
string
The name of the property to animate.
This property is read/write. The default value is null.
propertyName Grammar
A Storyboard.TargetProperty can target a property simply by naming the property. But Storyboard.TargetProperty also supports more complex forms of propertyName specifications, including targeting objects and then properties of that object, or accessing child objects in collections and then properties of that child.
| Scheme | Grammar | Example |
|---|---|---|
| Simple property name | propertyName | "Width" |
| Multiple objects and subproperties | (objectType1.sPropName1).sPropName2 | "(Rectangle.Fill).Color" |
| Item from within a collection, 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 an attached property, whereby non-Storyboard objects can set this Storyboard-specific property.
Notice particularly 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 referenced by Storyboard.TargetName. For more information, see the "Part 2: Create a Storyboard" section of Animation Overview.
Storyboard.TargetProperty supports a concept of indirect property targeting. Indirect property targeting is necessary when the type of the property being animated is itself an object, but the actual animated value is a subproperty of that object rather than the object type itself. This is particularly necessary if there was no means in markup to provide a name for targeting the subobject, perhaps because it was specified originally in XAML attribute form rather than 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 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, and are thus able to target an animation to an object that has no name.
Attempting to set Storyboard.TargetProperty on a running animation will raise a runtime SetValue method error. You can however use script to retarget existing animations that are not yet running, or animations where have called Stop. If you retarget animations, you usually want to use a target that is the same type, or at least 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 runtime error.
The property you target must use the type of the animation you are applying. For example, if you wanted 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, for instance 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 no Silverlight object type contained in the collections is directly animatable with the Double, Color and Point animation types that are supported in Silverlight 1.0. You must terminate the property chain with some property of the object that comes from an index in a collection.
Applies To
ColorAnimation, ColorAnimationUsingKeyFrames, DoubleAnimation, DoubleAnimationUsingKeyFrames, PointAnimation, PointAnimationUsingKeyFrames, Storyboard
See Also
Animation Overview
Referencing and Modifying Silverlight Objects