Animating XAML elements with composition animations
This article introduces new properties that let you animate a XAML UIElement with the performance of composition animations and the ease of setting XAML properties.
Prior to Windows 10, version 1809, you had 2 choices to build animations in your UWP apps:
- use XAML constructs like Storyboarded animations, or the *ThemeTransition and *ThemeAnimation classes in the Windows.UI.Xaml.Media.Animation namespace.
- use composition animations as described in Using the Visual Layer with XAML.
Using the visual layer provides better performance than using the XAML constructs. But using ElementCompositionPreview to get the element's underlying composition Visual object, and then animating the Visual with composition animations, is more complex to use.
Starting in Windows 10, version 1809, you can animate properties on a UIElement directly using composition animations without the requirement to get the underlying composition Visual.
To use these properties on UIElement, your UWP project target version must be 1809 or later. For more info about configuring your project version, see Version adaptive apps.
|XAML Controls Gallery|
If you have the XAML Controls Gallery app installed, click here to open the app and see Animation interop in action.
New rendering properties replace old rendering properties
This table shows the properties you can use to modify the rendering of a UIElement, that can also be animated with a CompositionAnimation.
|Opacity||Double||The degree of the object's opacity|
|Translation||Vector3||Shift the X/Y/Z position of the element|
|TransformMatrix||Matrix4x4||The transform matrix to apply to the element|
|Scale||Vector3||Scale the element, centered on the CenterPoint|
|Rotation||Float||Rotate the element around the RotationAxis and CenterPoint|
|RotationAxis||Vector3||The axis of rotation|
|CenterPoint||Vector3||The center point of scale and rotation|
The TransformMatrix property value is combined with the Scale, Rotation, and Translation properties in the following order: TransformMatrix, Scale, Rotation, Translation.
These properties have the same purpose and behavior as the like-named properties on the composition Visual class (except for Translation, which isn't on Visual).
Example: Setting the Scale property
This example shows how to set the Scale property on a Button.
<Button Scale="2,2,1" Content="I am a large button" />
var button = new Button(); button.Content = "I am a large button"; button.Scale = new Vector3(2.0f,2.0f,1.0f);
Mutual exclusivity between new and old properties
The Opacity property does not enforce the mutual exclusivity described in this section. You use the same Opacity property whether you use XAML or composition animations.
The properties that can be animated with a CompositionAnimation are replacements for several existing UIElement properties:
When you set (or animate) any of the new properties, you cannot use the old properties. Conversely, if you set (or animate) any of the old properties, you cannot use the new properties.
You also cannot use the new properties if you use ElementCompositionPreview to get and manage the Visual yourself using these methods:
Attempting to mix the use of the two sets of properties will cause the API call to fail and produce an error message.
It’s possible to switch from one set of properties by clearing them, though for simplicity it's not recommended. If the property is backed by a DependencyProperty (for example, UIElement.Projection is backed by UIElement.ProjectionProperty), then call ClearValue to restore it to its "unused" state. Otherwise (for example, the Scale property), set the property to its default value.
Animating UIElement properties with CompositionAnimation
You can animate the rendering properties listed in the table with a CompositionAnimation. These properties can also be referenced by an ExpressionAnimation.
Example: Animating the Scale property with a Vector3KeyFrameAnimation
This example shows how to animate the scale of a Button.
var compositor = Window.Current.Compositor; var animation = compositor.CreateVector3KeyFrameAnimation(); animation.InsertKeyFrame(1.0f, new Vector3(2.0f,2.0f,1.0f)); animation.Duration = TimeSpan.FromSeconds(1); animation.Target = "Scale"; button.StartAnimation(animation);
Example: Animating the Scale property with an ExpressionAnimation
A page has two buttons. The second button animates to be twice as large (via scale) as the first button.
<Button x:Name="sourceButton" Content="Source"/> <Button x:Name="destinationButton" Content="Destination"/>
var compositor = Window.Current.Compositor; var animation = compositor.CreateExpressionAnimation("sourceButton.Scale*2"); animation.SetExpressionReferenceParameter("sourceButton", sourceButton); animation.Target = "Scale"; destinationButton.StartAnimation(animation);