Storyboard.SetTargetProperty(Timeline, String) Method

Reference

Definition

Namespace:: Microsoft.UI.Xaml.Media.Animation

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

Sets the value of the Storyboard.TargetProperty XAML attached property for a target element.

public:
 static void SetTargetProperty(Timeline ^ element, Platform::String ^ path);

 static void SetTargetProperty(Timeline const& element, winrt::hstring const& path);

public static void SetTargetProperty(Timeline element, string path);

function setTargetProperty(element, path)

Public Shared Sub SetTargetProperty (element As Timeline, path As String)

Parameters

element: Timeline

The target element for which to set the value.

path: String
Platform::String

winrt::hstring

The Storyboard.TargetProperty value of the target element to set. This specifies a qualification path that targets the dependency property where the animation applies. See Remarks.

Remarks

Using SetTargetProperty in code as opposed to targeting an animation in initial XAML definitions is rare. It's tricky to get all the targeting and timing correct in an animation, particularly if you're trying to incorporate values that are only available at run time. We recommend that you create your animations in XAML, which means you'll use the Storyboard.TargetProperty attached property, not the SetTargetProperty runtime method (which supports the XAML behind the scenes). Building up animations in code is an advanced scenario. Here's a very basic code example of what's involved:

Rectangle rect = new Rectangle();
rect.RenderTransform = new ScaleTransform();
//TODO - connect this Rectangle to the visual tree
Storyboard storyboard = new Storyboard();
DoubleAnimation scalex = new DoubleAnimation()
{
    From = 0,
    To = 8,
    AutoReverse = true,
    Duration = TimeSpan.FromSeconds(2)
};
Storyboard.SetTargetProperty(scalex, "(Rectangle.RenderTransform).(ScaleTransform.ScaleX)");
Storyboard.SetTarget(scalex, rect);
//TODO - Begin the animation

Property paths for animation property targeting

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.

The Storyboard.TargetName property can process a string syntax that enables targeting a subproperty of a property value. The syntax uses a "dot-down" metaphor for targeting a chain of object-property relationships until a particular subproperty is identified. This enables animations to apply to the value types where there is a supporting animation structure (Double, Color, Point, and Object for DiscreteObjectKeyFrameAnimation). For example, you might want to animate the Background value of a Control, which takes an object type of Brush. There is no "BrushAnimation" animation type, so you cannot directly target an animation for Background . But what you can do instead is reference a SolidColorBrush subproperty that is named Color, which takes type Color and can thus be targeted by a ColorAnimation. The string syntax for this is:

(Control.Background).(SolidColorBrush.Color)

The parentheses around "(Control.Background)" inform the processing that the intermediate "dot" should not "dot down" and is instead part of the qualification name that finds the ownertype-qualified Background property for targeting. The following "dot" is treated as a "dot-down" instruction, which requests a subproperty of the Brush type. The final "(SolidColorBrush.Color)" fragment again includes the parentheses so that the interior "dot" is again used as ownertype.member qualification, not a "dot-down".

Note that for subproperty values, there can be some value inference. For example, the following string works by inference even though "Color" is actually a value of the particular Brush subclass SolidColorBrush:

(Control.Background).Color

There is a lot more to property path specification than this. This remark is just intended to get you started with the basic targeting scenarios. For more info, see Property-path syntax and Storyboarded animations.

Migration notes

When you specify a path value for the path parameter, you specify the string, and if you retrieve the value again using GetTargetProperty, you also get the value as a string. This is in contrast to some other implementations of animation property targeting concepts such as Microsoft Silverlight and Windows Presentation Foundation (WPF). These XAML technologies use a representative object type (a discrete PropertyPath object) to store the property path information for animation targeting, and the syntax for the SetTargetProperty methods use the PropertyPath type. The Windows Runtime also has a PropertyPath class; however that class is only used for data binding, which is another scenario for property path definitions. The Windows Runtime doesn't support modifying a property path in a Storyboard after it's defined using the string, so its implementation of Storyboard.TargetProperty takes a string. This distinction doesn't even matter for XAML syntax and attached property support. It only matters for creating dynamic storyboards in code, or programmatically modifying storyboard values after they are initially defined in XAML. If you have any need to retarget an animation to a different property at run time, create an entirely new Storyboard with the new property path string, run animations with the new Storyboard, and stop using the previous one.

Applies to

Share via