Storyboard.TargetProperty attached property

Gets or sets the property that should be animated.

<object Storyboard.TargetProperty="simplePropertyName" />
-or-
<object Storyboard.TargetProperty="propertyPath" />

XAML Values

simplePropertyName

The name of the dependency property to animate.

propertyPath

A more complex property path, to support animating a targeted property or an attached property through an indirect animation. For more info see PropertyPath syntax.

Remarks

Storyboard.TargetProperty is an attached property, which supports a XAML usage. When getting this property in code, use GetTargetProperty. When setting this property in code, use SetTargetProperty instead. In code usages, the target parameter is the object where the attached property value is set. Another way to get or set the value in code is to use the dependency property system, calling either GetValue or SetValue and passing TargetPropertyProperty as the dependency property identifier.

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, and uses a property path syntax to specify indirect 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 property of that object instead of the object type itself. This is particularly necessary when markup cannot provide a name for targeting the sub-object, 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 a property path is applying an animation to objects that are added to a collection at run time. 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 are able to target an animation to an object that has no name but that exists as a sub-property of a named object.

Attempting to set Storyboard.TargetProperty on a running animation will cause a run-time error. However, you can retarget existing animations that are stopped or not yet running. 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 cause 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 object types contained in the collections cannot be directly animated with the Double, Color, and Point animation types. You must terminate the property chain with a specific property of the object that comes from an index in a collection.

Indirect targeting cannot infer or create an object that doesn't exist or is not initialized. For example, a common scenario for indirect targeting is to use a Transform type such as TranslateTransform for the RenderTransform value of a UIElement. Indirect targeting is necessary here because you don't typically animate the whole Transform object, but you can animate the Double properties of such a transform, such as TranslateTransform.X and TranslateTransform.Y as two animations in the same Storyboard. But in order to resolve the property path to TranslateTransform.X and TranslateTransform.Y, a TranslateTransform must already exist as the RenderTransform value, even if its values are all 0 in initialization. You'd typically establish the intermediate objects that you'll eventually want to animate the sub-properties of in the UI definitions in XAML.

For more info on indirect targeting and other aspects of defining the property path that supplies a Storyboard.TargetProperty value, see PropertyPath syntax.

Requirements

See also

Storyboard

Storyboarded animations

PropertyPath syntax

Attached properties overview

Build date: 12/4/2012