Storyboard.TargetProperty attached property

Applies to Windows and Windows Phone

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 Property-path syntax.

Remarks

The Storyboard.TargetProperty attached property is typically set on the individual Timeline-derived animations that make up the Storyboard.Children collection of an animation definition in XAML. For more info on the general concepts of storyboards and timelines, see Storyboarded animations.

The value of Storyboard.TargetProperty must refer to an existing property of the element that is referenced by Storyboard.TargetName. You almost always set both Storyboard.TargetName and Storyboard.TargetProperty together on any given animation you define in XAML.

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 value to animate 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. This might come up if you're animating a LinearGradientBrush or a PointCollection.

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 for a UIElement. Indirect targeting is necessary here because you don't animate the whole Transform object, you can animate the Double properties of such a transform, but first it needs to exist. See "Animating transforms" section for more details on how you must initialize RenderTransform values in order to animate them.

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

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.

Animating transforms

Animating a transformation in order to make an element scale, stretch or move is a relatively common UI scenario. In order to have a transformation affect a UIElement, you must change the value of its RenderTransform property. However, by default the value of RenderTransform for an element is null. So in order to successfully target the properties of a transform in order to animate it, you need to supply a non-null value of the desired transformation type as the initial RenderTransform value, even if your only use for that property is to animate it later. For example, given this UI definition: <Rectangle x:Name="myRectangle" Fill="Blue" Width="200" Height="30"> an animation with Storyboard.TargetProperty="(UIElement.RenderTransform).(ScaleTransform.ScaleY)"> will fail, because there's no ScaleTransform there, only null. Instead, your Rectangle should be initially defined like this:

    <Rectangle x:Name="myRectangle" Fill="Blue" Width="200" Height="30">
        <Rectangle.RenderTransform>
            <ScaleTransform x:Name="rectScaleTransform" />
        </Rectangle.RenderTransform>
    </Rectangle>

If you're animating RenderTransformOrigin, you don't have this issue, because the initial value is not null, it's a Point with value "(0,0)".

Animating brushes

Animating brushes is another common scenario. But you're typically animating just the color of the brush, not the entire Brush value. This usually means you'll be using property path syntax to target a Brush property such as (Control.Background).(SolidColorBrush.Color) and applying a ColorAnimation to that value. When animating Brush properties, you also need to make sure that the starting value has a real value and not null. But for Brush properties it's common that the property will have a starting value as applied by a style or template, often from the default templates provided by the Windows Runtime.

Migration notes

The underlying type of this attached property for its getter and setter methods is not PropertyPath, it's a string. For more info, see "Migration notes" in SetTargetProperty.

Examples

This example shows a small piece of UI definition and then two Storyboard definitions that apply animations to properties within it. The two animation definitions are really the same; one directly targets the ScaleTransform by name, the other uses indirect targeting from a property path to "dot down" from the parent Rectangle.


<!-- UI definition-->
    <Rectangle x:Name="myRectangle" Fill="Blue" Width="200" Height="30">
        <Rectangle.RenderTransform>
            <ScaleTransform x:Name="rectScaleTransform" />
        </Rectangle.RenderTransform>
    </Rectangle>
<!-- storyboards, defined elsewhere in a .Resources collection -->
        <Storyboard x:Name="directStoryboard">
            <DoubleAnimation From="1" To="6" Duration="00:00:6" 
              Storyboard.TargetName="rectScaleTransform" 
              Storyboard.TargetProperty="ScaleY">
            </DoubleAnimation>
        </Storyboard>
        <Storyboard x:Name="indirectStoryboard">
            <DoubleAnimation From="1" To="6" Duration="00:00:6" 
              Storyboard.TargetName="myRectangle" 
              Storyboard.TargetProperty="(UIElement.RenderTransform).(ScaleTransform.ScaleY)">
            </DoubleAnimation>
        </Storyboard>

Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Xaml.Media.Animation

Metadata

Windows.winmd

See also

Storyboard.TargetName
Storyboard
Storyboarded animations
Property-path syntax
Attached properties overview

 

 

Show:
© 2014 Microsoft