ExpressionAnimation Class

Definition

Namespace:

Microsoft.UI.Composition

A Composition Animation that uses a mathematical equation to calculate the value for an animating property every frame.

public ref class ExpressionAnimation sealed : CompositionAnimation

/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.Foundation.WindowsAppSDKContract, 65536)]
class ExpressionAnimation final : CompositionAnimation

[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.Foundation.WindowsAppSDKContract), 65536)]
public sealed class ExpressionAnimation : CompositionAnimation

Public NotInheritable Class ExpressionAnimation
Inherits CompositionAnimation

Inheritance

Object Platform::Object IInspectable CompositionObject CompositionAnimation ExpressionAnimation

Attributes

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Examples

void AnimateOpacity()
{
  // The Expression below will animate the opacity of the target Visual based on its position to the edge of the window.
  ExpressionAnimation exp = _compositor.CreateExpressionAnimation();
  float xWinSize = (float) Window.Current.Bounds.Width;
  SpriteVisual targetVisual = _compositor.CreateSpriteVisual();

  // Define the Expression Equation and references
  exp.Expression = "this.Target.Offset.X / xWindowSize";
  exp.SetScalarParameter("xWindowSize", xWinSize);

  // Attach the animation to the target Opacity property
  targetVisual.StartAnimation("Opacity", exp);
}

// Creates an Expression that calculates the angle between two Visual's Offset vectors 
// And assigns it to the RotationAngle of a third Visual
void angleBetweenVectors()
{
  SpriteVisual visualA = _compositor.CreateSpriteVisual();
  SpriteVisual visualB = _compositor.CreateSpriteVisual();

  SpriteVisual lineVisual = _compositor.CreateSpriteVisual();
  lineVisual.Size = new Vector2(50.0f, 5.0f);

  var rotationAnimation = _compositor.CreateExpressionAnimation();
  rotationAnimation.SetReferenceParameter("A", visualA);
  rotationAnimation.SetReferenceParameter("B", visualB);

  rotationAnimation.Expression = "ACos( ( (A.Offset.X * B.Offset.X) + (A.Offset.Y*B.Offset.Y) + (A.Offset.Z * B.Offset.Z) ) / ( Length(A.Offset) * 	Length(B.Offset) ) )";
  lineVisual.StartAnimation("RotationAngle", rotationAnimation);
}

Remarks

The core of ExpressionAnimations allows a developer to define a mathematical equation that can be used to calculate the value of a targeted animating property each frame. This contrasts KeyFrameAnimation s, which use an interpolator to define how the animating property changes over time. The mathematical equation can be defined using references to properties of Composition objects, mathematical functions and operators and Input. Expression Animations open the door to making experiences such as sticky headers and parallax easily describable.

For a detailed walkthrough of using Composition ExpressionAnimation, check out the Animations Overview document.

Use the CompositionObject.StartAnimation and CompositionObject.StopAnimation methods to start and stop the animation.

So why are Expression Animations useful?

The real power of Expression Animations comes from their ability to create a mathematical relationship with references to properties on other objects. This means you can have an equation referencing property values on other Composition objects, local variables, or even shared values in Composition Property Sets. As these references change and update over time, your expression will as well. This opens up bigger possibilities beyond traditional KeyFrame Animations where values must be discrete and pre-defined – ExpressionAnimations can make more dynamic animation experiences.

Things to Note

• ExpressionAnimation has an infinite lifetime – they will continue to run until they are explicitly stopped.

• The mathematical equation will be input into the expression as a string – this can be done when constructing the ExpressionAnimation or separately by changing the property. If done during construction, the property will be set. + ExpressionAnimation exp = _compositor.CreateExpressionAnimation(); exp.Expression = "this.Target.Offset.X / xWindowSize";

  • ExpressionAnimation exp = _compositor.CreateExpressionAnimation("this.Target.Offset.X / xWindowSize")

• The mathematical equation will be used every frame to calculate the value of the animating property (this is in stark contrast to KeyFrameAnimations that use an interpolator)

• Pay attention to the type of the property you plan to animate – your equation must resolve to the same type. Otherwise, an error will get thrown when the expression gets calculated. If your equation resolves to Nan (number/0), the system will use the previously calculated value

The key to making dynamic animation UI with expression animations is to create an equation in which the references to properties or other values will change over time.

When attached to an animating property, the system will use this equation to calculate the value for the property for each frame. This means as a result, the system will re-evaluate all the references which will drive changes to the equation. For instance, in the example above, if either Visual A or B move due to another animation or input, the rotation angle of the line visual will change accordingly due to the equation.

When constructing the mathematical equation, there are a number of different components to keep in mind (For a detailed walkthrough of each of these components, see the Animation Overview):

• Operators, Precedence and Associativity + The Expression string supports usage of typical mathematical operators (+, -, /, , etc.) you would expect to use in any equation.

  • When the expression is evaluated, it will adhere to operator precedence and associativity as defined in the C# language specification.

• Property Parameters + When defining your Expression, you have the option to define type references to other properties on Composition Visuals, Property Sets or other C# objects.

  • To use in an expression string, utilize the “SetParameter” functions based on type, defining the string utilized in the expression string and its mapped value. These functions are listed as part of the top level CompositionAnimation class.

• Helper Functions and Constructors + The Expression can also leverage a list of functions and constructors for different object types in the equation.

  • There are also constructor methods that will construct an object type when the equation is evaluated by the system
  • A list of the functions per type is listed further below

• Keywords + The Expression also can take advantage of a number of keywords that are treated differently when the Expression String Is evaluated. Consider these keywords and cannot be used as a string key in property references.

  • List of available keywords listed further below

• Conditionals + An expression can also utilize conditional statements using the Ternary operator (condition ? ifTrue_expression : ifFalse_expression)

  • Ternary operators can be nested as the expression for the true or false statements.

Expression Keywords

Keyword	Description
This.StartingValue	Provides a reference to the original starting value of the property that is being animated.
This.CurrentValue	Provides a reference to the currently “known” value of the property
This.FinalValue	Provides a reference to the final value of the animation (if defined) Note: Relevant for Implicit Animations, for explicit, maintains same functionality as This.StartingValue
Pi	Provides a keyword reference to the value of PI
True / False	Provides a reference to Boolean values of “true” or “false”
This.Target	Provides a reference to the target object the animations is bound to.

Expression Functions per Type

Scalar

Function and Constructor Operations	Description
Abs(Float value)	Returns a Float representing the absolute value of the float parameter
Clamp(Float value, Float min, Float max)	Returns a float value that is either greater than min and less than max or min if the value is less than min or max if the value is greater than max
Max (Float value1, Float value2)	Returns the greater float between value1 and value2.
Min (Float value1, Float value2)	Returns the lesser float between value1 and value2.
Lerp(Float value1, Float value2, Float progress)	Returns a float that represents the calculated linear interpolation calculation between the two Scalar values based on the progress (Note: Progress is between 0.0 and 1.0)
Slerp(Float value1, Float value2, Float progress)	Returns a Float that represents the calculated spherical interpolation between the two Float values based on the progress (Note: progress is between 0.0 and 1.0)
Mod(Float value1, Float value2)	Returns the Float remainder resulting from the division of value1 and value2
Ceil(Float value)	Returns the Float parameter rounded to next greater whole number
Floor(Float value)	Returns the Float parameter to the next lesser whole number
Sqrt(Float value)	Returns the square root of the Float parameter
Square(Float value)	Returns the square of the Float parameter
Sin(Float value1) Asin(Float value2)	Returns the Sin or ArcSin of the Float parameter
Cos(Float value1) ACos(Float value2)	Returns the Cos or ArcCos of the Float parameter
Tan(Float value1) ATan(Float value2)	Returns the Tan or ArcTan of the Float parameter
Round(Float value)	Returns the Float parameter rounded to the nearest whole number
Log10(Float value)	Returns the Log (base 10) result of the Float parameter
Ln(Float value)	Returns the Natural Log result of the Float parameter
Pow(Float value, Float power)	Returns the result of the Float parameter raised to a particular power
ToDegrees(Float radians)	Returns the Float parameter converted into Degrees
ToRadians(Float degrees)	Returns the Float parameter converted into Radians

Vector2

Function and Constructor Operations	Description
Abs (Vector2 value)	Returns a Vector2 with absolute value applied to each component
Clamp (Vector2 value1, Vector2 min, Vector2 max)	Returns a Vector2 that contains the clamped values for each respective component
Max (Vector2 value1, Vector2 value2)	Returns a Vector2 that has performed a Max on each of the corresponding components from value1 and value2
Min (Vector2 value1, Vector2 value2)	Returns a Vector2 that has performed a Min on each of the corresponding components from value1 and value2
Scale(Vector2 value, Float factor)	Returns a Vector2 with each component of the vector multiplied by the scaling factor.
Transform(Vector2 value, Matrix3x2 matrix)	Returns a Vector2 resulting from the linear transformation between a Vector2 and a Matrix3x2 (aka multiplying a vector by a matrix).
Lerp(Vector2 value1, Vector2 value2, Scalar progress)	Returns a Vector2 that represents the calculated linear interpolation calculation between the two Vector2 values based on the progress (Note: Progress is between 0.0 and 1.0)
Length(Vector2 value)	Returns a Float value representing the length/magnitude of the Vector2
LengthSquared(Vector2)	Returns a Float value representing the square of the length/magnitude of a Vector2
Distance(Vector2 value1, Vector2 value2)	Returns a Float value representing the distance between two Vector2 values
DistanceSquared(Vector2 value1, Vector2 value2)	Returns a Float value representing the square of the distance between two Vector2 values
Normalize(Vector2 value)	Returns a Vector2 representing the unit vector of the parameter where all components have been normalized
Vector2(Float x, Float y)	Constructs a Vector2 using two Float parameters

Vector3

Function and Constructor Operations	Description
Abs (Vector3 value)	Returns a Vector3 with absolute value applied to each component
Clamp (Vector3 value1, Vector3 min, Vector3 max)	Returns a Vector3 that contains the clamped values for each respective component
Max (Vector3 value1, Vector3 value2)	Returns a Vector3 that has performed a Max on each of the corresponding components from value1 and value2
Min (Vector3 value1, Vector3 value2)	Returns a Vector3 that has performed a Min on each of the corresponding components from value1 and value2
Scale(Vector3 value, Float factor)	Returns a Vector3 with each component of the vector multiplied by the scaling factor.
Lerp(Vector3 value1, Vector3 value2, Float progress)	Returns a Vector3 that represents the calculated linear interpolation calculation between the two Vector3 values based on the progress (Note: Progress is between 0.0 and 1.0)
Length(Vector3 value)	Returns a Float value representing the length/magnitude of the Vector3
LengthSquared(Vector3)	Returns a Float value representing the square of the length/magnitude of a Vector3
Distance(Vector3 value1, Vector3 value2)	Returns a Float value representing the distance between two Vector3 values
DistanceSquared(Vector3 value1, Vector3 value2)	Returns a Float value representing the square of the distance between two Vector3 values
Normalize(Vector3 value)	Returns a Vector3 representing the unit vector of the parameter where all components have been normalized
Vector3(Float x, Float y, Float z)	Constructs a Vector3 using three Float parameters

Vector4

Function and Constructor Operations	Description
Abs (Vector4 value)	Returns a Vector3 with absolute value applied to each component
Clamp (Vector4 value1, Vector4 min, Vector4 max)	Returns a Vector4 that contains the clamped values for each respective component
Max (Vector4 value1 Vector4 value2)	Returns a Vector4 that has performed a Max on each of the corresponding components from value1 and value2
Min (Vector4 value1 Vector4 value2)	Returns a Vector4 that has performed a Min on each of the corresponding components from value1 and value2
Scale(Vector3 value, Float factor)	Returns a Vector3 with each component of the vector multiplied by the scaling factor.
Transform(Vector4 value, Matrix4x4 matrix)	Returns a Vector4 resulting from the linear transformation between a Vector4 and a Matrix4x4 (aka multiplying a vector by a matrix).
Lerp(Vector4 value1, Vector4 value2, Float progress)	Returns a Vector4 that represents the calculated linear interpolation calculation between the two Vector4 values based on the progress (Note: progress is between 0.0 and 1.0)
Length(Vector4 value)	Returns a Float value representing the length/magnitude of the Vector4
LengthSquared(Vector4)	Returns a Float value representing the square of the length/magnitude of a Vector4
Distance(Vector4 value1, Vector4 value2)	Returns a Float value representing the distance between two Vector4 values
DistanceSquared(Vector4 value1, Vector4 value2)	Returns a Float value representing the square of the distance between two Vector4 values
Normalize(Vector4 value)	Returns a Vector4 representing the unit vector of the parameter where all components have been normalized
Vector4(Float x, Float y, Float z, Float w)	Constructs a Vector4 using four Float parameters

Matrix3x2

Function and Constructor Operations	Description
Scale(Matrix3x2 value, Float factor)	Returns a Matrix3x2 with each component of the matrix multiplied by the scaling factor.
Inverse(Matrix 3x2 value)	Returns a Matrix3x2 object that represents the reciprocal matrix
Matrix3x2(Float M11, Float M12, Float M21, Float M22, Float M31, Float M32)	Constructs a Matrix3x2 using 6 Float parameters
Matrix3x2.CreateFromScale(Vector2 scale)	Constructs a Matrix3x2 from a Vector2 representing scale[scale.X, 0.0 0.0, scale.Y 0.0, 0.0 ]
Matrix3x2.CreateFromTranslation(Vector2 translation)	Constructs a Matrix3x2 from a Vector2 representing translation[1.0, 0.0, 0.0, 1.0, translation.X, translation.Y]
Matrix3x2.CreateSkew(Float x, Float y, Vector2 centerpoint)	Constructs a Matrix3x2 from two Float and Vector2[1.0, Tan(y), Tan(x), 1.0, -centerpoint.Y * Tan(x), -centerpoint.X * Tan(y)]
Matrix3x2.CreateRotation(Float radians)	Constructs a Matrix3x2 from a rotation in radians[Cos(radians), Sin(radians), -Sin(radians), Cos(radians), 0.0, 0.0 ]
Matrix3x2.CreateTranslation(Vector2 translation)	(Exact same as CreateFromTranslation for Matrix3x2, just different naming for new consistency)
Matrix3x2.CreateScale(Vector2 scale)	(Exact same as CreateFromScale for Matrix3x2, just different naming for new consistency)

Matrix4x4

Function and Constructor Operations	Description
Scale(Matrix4x4 value, Float factor)	Returns a Matrix 4x4 with each component of the matrix multiplied by the scaling factor.
Inverse(Matrix4x4)	Returns a Matrix4x4 object that represents the reciprocal matrix
Matrix4x4(Float M11, Float M12, Float M13, Float M14, Float M21, Float M22, Float M23, Float M24, Float M31, Float M32, Float M33, Float M34, Float M41, Float M42, Float M43, Float M44)	Constructs a Matrix4x4 using 16 Float parameters
Matrix4x4(Matrix3x2 matrix)	Constructs a Matrix4x4 using a Matrix3x2[matrix.11, matrix.12, 0, 0, matrix.21, matrix.22, 0, 0, 0, 0, 1, 0, matrix.31, matrix.32, 0, 1]
Matrix4x4.CreateFromScale(Vector3 scale)	Constructs a Matrix4x4 from a Vector3 representing scale[scale.X, 0.0, 0.0, 0.0, 0.0, scale.Y, 0.0, 0.0, 0.0, 0.0, scale.Z, 0.0, 0.0, 0.0, 0.0, 1.0]
Matrix4x4.CreateFromTranslation(Vector3 translation)	Constructs a Matrix4x4 from a Vector3 representing translation[1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, translation.X, translation.Y, translation.Z, 1.0]
Matrix4x4.CreateTranslation(Vector3 translation)	(Exact same as CreateFromTranslation for Matrix4x4, just different naming for new consistency)
Matrix4x4.CreateScale(Vector3 scale)	(Exact same as CreateFromScale for Matrix4x4, just different naming for new consistency)
Matrix4x4.CreateFromAxisAngle(Vector3 axis, Float angle)	Constructs a Matrix4x4 from a Vector3 axis and a Float representing an angle

Quaternion

Function and Constructor Operations	Description
Slerp(Quaternion value1, Quaternion value2, Float progress)	Returns a Quaternion that represents the calculated spherical interpolation between the two Quaternion values based on the progress (Note: progress is between 0.0 and 1.0)
Concatenate(Quaternion value1 Quaternion value2)	Returns a Quaternion representing a concatenation of two Quaternions (aka a Quaternion that represents a combined two individual rotations)
Length(Quaternion value)	Returns a Float value representing the length/magnitude of the Quaternion.
LengthSquared(Quaternion)	Returns a Float value representing the square of the length/magnitude of a Quaternion
Normalize(Quaternion value)	Returns a Quaternion whose components have been normalized
Quaternion.CreateFromAxisAngle(Vector3 axis, Scalar angle)	Constructs a Quaternion from a Vector3 axis and a Scalar representing an angle
Quaternion(Float x, Float y, Float z, Float w)	Constructs a Quaternion from four Float values

Color

Function and Constructor Operations	Description
ColorLerp(Color colorTo, Color colorFrom, Float progress)	Returns a Color object that represents the calculated linear interpolation value between two color objects based on a given progress. (Note: Progress is between 0.0 and 1.0)
ColorLerpRGB(Color colorTo, Color colorFrom, Float progress)	Returns a Color object that represents the calculated linear interpolation value between two objects based on a given progress in the RGB color space.
ColorLerpHSL(Color colorTo, Color colorFrom, Float progress)	Returns a Color object that represents the calculated linear interpolation value between two objects based on a given progress in the HSL color space.
ColorRGB(Float a, Float r, Float g, Float b)	Constructs an object representing Color defined by ARGB components. (Note: ARGB components are between 0.0 and 255.0)
ColorHsl(Float h, Float s, Float l)	Constructs an object representing Color defined by HSL components (Note: Hue is defined from 0 and 2pi)

Properties

Comment	A string to associate with the CompositionObject. (Inherited from CompositionObject)
Compositor	The Compositor used to create this CompositionObject. (Inherited from CompositionObject)
DispatcherQueue	Gets the DispatcherQueue for the CompositionObject. (Inherited from CompositionObject)
Expression	The mathematical equation specifying how the animated value is calculated each frame. The Expression is the core of an ExpressionAnimation and represents the equation the system will use to calculate the value of the animation property each frame. The equation is set on this property in the form of a string. Although expressions can be defined by simple mathematical equations such as “2+2”, the real power lies in creating mathematical relationships where the input values can change frame over frame.
ImplicitAnimations	The collection of implicit animations attached to this object. (Inherited from CompositionObject)
InitialValueExpressions	Gets the initial values for the animation. (Inherited from CompositionAnimation)
Properties	The collection of properties associated with the CompositionObject. (Inherited from CompositionObject)
Target	The target of the animation. (Inherited from CompositionAnimation)

Methods

ClearAllParameters()	Clears all of the parameters of the animation. (Inherited from CompositionAnimation)
ClearParameter(String)	Clears a parameter from the animation. (Inherited from CompositionAnimation)
Close()	Closes the CompositionObject and releases system resources. (Inherited from CompositionObject)
Dispose()	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. (Inherited from CompositionObject)
PopulatePropertyInfo(String, AnimationPropertyInfo)	Defines a property that can be animated. (Inherited from CompositionObject)
SetBooleanParameter(String, Boolean)	Sets a boolean value parameter for use with an ExpressionAnimation or an expression keyframe. (Inherited from CompositionAnimation)
SetColorParameter(String, Color)	Sets a Color value parameter for use with an ExpressionAnimation or an expression keyframe. (Inherited from CompositionAnimation)
SetExpressionReferenceParameter(String, IAnimationObject)	Sets an object that implements IAnimationObject as a reference parameter in an ExpressionAnimation. (Inherited from CompositionAnimation)
SetMatrix3x2Parameter(String, Matrix3x2)	Sets a Matrix3x2 value parameter for use with an ExpressionAnimation or an expression keyframe. (Inherited from CompositionAnimation)
SetMatrix4x4Parameter(String, Matrix4x4)	Sets a Matrix4x4 value parameter for use with an ExpressionAnimation or an expression keyframe. (Inherited from CompositionAnimation)
SetQuaternionParameter(String, Quaternion)	Sets a Quaternion value for use with an ExpressionAnimation or an expression keyframe. (Inherited from CompositionAnimation)
SetReferenceParameter(String, CompositionObject)	Sets a reference to a Composition object for use with an ExpressionAnimation or an expression keyframe. (Inherited from CompositionAnimation)
SetScalarParameter(String, Single)	Sets a Scalar value parameter for use with an ExpressionAnimation or an expression keyframe. (Inherited from CompositionAnimation)
SetVector2Parameter(String, Vector2)	Sets a Vector2 value parameter for use with an ExpressionAnimation or an expression keyframe. (Inherited from CompositionAnimation)
SetVector3Parameter(String, Vector3)	Sets a Vector3 value parameter for use with an ExpressionAnimation or an expression keyframe. (Inherited from CompositionAnimation)
SetVector4Parameter(String, Vector4)	Sets a Vector4 value parameter for use with an ExpressionAnimation or an expression keyframe. (Inherited from CompositionAnimation)
StartAnimation(String, CompositionAnimation, AnimationController)	Connects an animation with the specified property of the object and starts the animation. (Inherited from CompositionObject)
StartAnimation(String, CompositionAnimation)	Connects an animation with the specified property of the object and starts the animation. (Inherited from CompositionObject)
StartAnimationGroup(ICompositionAnimationBase)	Starts an animation group. The StartAnimationGroup method on CompositionObject lets you start CompositionAnimationGroup. All the animations in the group will be started at the same time on the object. (Inherited from CompositionObject)
StopAnimation(String)	Disconnects an animation from the specified property and stops the animation. (Inherited from CompositionObject)
StopAnimationGroup(ICompositionAnimationBase)	Stops an animation group. (Inherited from CompositionObject)
TryGetAnimationController(String)	Returns an AnimationController for the animation running on the specified property. (Inherited from CompositionObject)

See also

• Expression
• Animations Overview document