InteractionTracker Class

Definition

Namespace:

Microsoft.UI.Composition.Interactions

Handles the logic of input that can be used as targets in ExpressionAnimations—typically to drive the motion of visuals based on input.

public ref class InteractionTracker sealed : CompositionObject

/// [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 InteractionTracker final : CompositionObject

[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 InteractionTracker : CompositionObject

Public NotInheritable Class InteractionTracker
Inherits CompositionObject

Inheritance

Object Platform::Object IInspectable CompositionObject InteractionTracker

Attributes

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Examples

void SetupSimpleInteractionTracker(Visual viewportVisual, Visual contentVisual)
{
  //
  // Create the InteractionTracker and set its min/max position and scale.  These could 
  // also be bound to expressions.  Note: The scrollable area can be changed from either 
  // the min or the max position to facilitate content updates/virtualization.
  //

  _tracker = InteractionTracker.Create(_compositor);

  _tracker.MaxPosition = new Vector3(
    contentVisual.Size.X - viewportVisual.Size.X,
    contentVisual.Size.Y - viewportVisual.Size.Y,
    0.0f);

  _tracker.MinScale = 0.5f;
  _tracker.MaxScale = 4.0f;


  //
  // Configure the interaction source.  Enable input with inertia on all axes.
  //

  var interactionSource = VisualInteractionSource.Create(viewportVisual);

  interactionSource.PositionXSourceMode = InteractionSourceMode.EnabledWithInertia;
  interactionSource.PositionYSourceMode = InteractionSourceMode.EnabledWithInertia;
  interactionSource.ScaleSourceMode = InteractionSourceMode.EnabledWithInertia;

  _tracker.InteractionSources.Add(interactionSource);


  //
  // Bind the InteractionTracker outputs to the contentVisual.
  //

  var positionExpression = _compositor.CreateExpressionAnimation("-tracker.Position");
  positionExpression.SetReferenceParameter("tracker", _tracker);

  contentVisual.StartAnimation("Offset", positionExpression);


  var scaleExpression = _compositor.CreateExpressionAnimation("Vector3(tracker.Scale, tracker.Scale, 1.0)");

  scaleExpression.SetReferenceParameter("tracker", _tracker);

  contentVisual.StartAnimation("Scale", scaleExpression);
}

Remarks

InteractionTracker is a state machine that can be driven by active input, or by explicit calls to update or animate its properties. The InteractionTracker class is intended to enable input to drive CompositionAnimations for custom interaction experiences. In order to build interactive experiences, it is necessary to associate one or more VisualInteractionSources with the InteractionTracker.

Common Scenarios

IneractionTracker is intended to be used for:

• Adding custom swipe behavior, for example swiping ListView items or other visuals to delete/dismiss
• Transitions tied to panning, for example swiping to transition between "closed" and "open" states
• Input-driven animation of an effect, for example panning causes the screen to blur
• Custom Controls, for example creating a custom implementation of a ScrollViewer with different panning speeds or the ability to be controlled programmatically

InteractionTracker States and Transitions

The InteractionTracker is a state machine with four states:

• Idle: No active input or animations driving the InteractionTracker
• Interacting: Active user input is driving the InteractionTracker
• Inertia: Active animations that are a result of active input or programmatic velocity are driving the InteractionTracker
• CustomAnimation: A property of the InteractionTracker is being directly animated The diagram below shows these four states and which state transitions are valid.

State transitions can happen due to user actions (such as starting or stopping a manipulation) or due to explicit calls to methods on the InteractionTracker. Any time one of these explicit calls is made, a requestID is issued for tracking whether the request is ignored or causes a state change.

An important thing to note is that InteractionTracker is running in a different process than the application that is using it. As such, all method calls on InteractionTracker and associated classes are asynchronous, as are the callbacks issued through the IInteractionTrackerOwner interface.

The following describes what triggers each state change to happen:

Begin State	End State	Possible Triggers
Idle	Interacting	This state transition only happens when a user manipulation that aligns with a VisualInteractionSource associated with the InteractionTracker is being performed.
Idle	Inertia	This state transition only happens when the InteractionTracker is in the Idle state and TryUpdatePositionWithVelocity or TryUpdateScaleWithVelocity is called.
Idle	CustomAnimation	This state transition happens when InteractionTracker is in the Idle state and TryUpdatePositionWithAnimation or TryUpdateScaleWithAnimation is called.
Interacting	Inertia	This state transition only happens when a user manipulation that has been sent to the InteractionTracker completes. When the active input ends, the InteractionTracker will enter the Inertia state, and information such as the finger's release velocity and the InertiaDecayRate will determine the behavior during the Inertia state.
Inertia	Idle	This state transition happens when the function(s) being used to update position and/or scale are no longer resulting in change. In other words, position and scale velocity have both gotten to zero. This state transition can also happen if a call is made to explicitly update position or scale without animation or velocity. These calls will end inertia and transition to Idle with the updated property values.
Inertia	Inertia	This state transition happens when TryUpdatePositionWithVelocity or TryUpdateScaleWithVelocity is called when already in the Inertia state. Re-entering Inertia will cause all InertiaStateEntered properties to be reevaluated.
Inertia	CustomAnimation	This state transition happens when a call to TryUpdatePositionWithAnimation or TryUpdateScaleWithAnimation is made while in the Inertia sate.
Inertia	Interacting	This state transition happens when active input from the user that hit-tests to the VisualInteractionSource comes in before Inertia has completed.
CustomAnimation	Idle	This state transition happens when all animations set on the InteractionTracker's position and scale properties have completed.
CustomAnimation	CustomAnimation	This state transition happens when a call to TryUpdatePositionWithAnimation or TryUpdateScaleWithAnimation is made while already in the CustomAnimation state.
CustomAnimation	Inertia	This state transition happens when a call to TryUpdatePositionWithVelocity or TryUpdateScaleWithVelocity is made when in the CustomAnimation state.
CustomAnimation	Interacting	This state transition happens when a user manipulation that hit-tests to a VisualInteractionSource associated with the InteractionTracker is being performed.

Any state transition made by the InteractionTracker will produce a callback indicating the new state with args that include information relevant to that state as well as the requestID for the request that caused the state change. Active manipulations from the user will result in a requestID of 0. Any Try* call will issue a requestID that can be used for tracking which Try* call caused the state change. The first requestID during the lifetime of the application will be 1, and each subsequent call will increment the requestID, meaning that each will be unique.

InteractionTracker Position and Scale

The two most commonly used properties of the InteractionTracker are position and scale. Whenever there is a change to one or both of these properties the ValuesChanged callback will be sent with information on the current values. Due to the asynchronous nature of InteractionTracker, values received through InteractionTracker callbacks are the best way to update application logic on the current state and values of InteractionTracker and its properties.

An important distinction about the InteractionTracker is that its position and scale are not associated with the coordinate space of any particular visual. At the time the InteractionTracker is created, its position will have the x, y and z subchannels of the vector set to 0, and scale will be set to 1. Only active input or Try* calls can cause these values to change. The minimum and maximum values for each property will dictate the range in which values can fluctuate. The one exception is the concept of "overpan" or "overzoom", where an active manipulation can cause values to go slightly beyond the minimum or maximum during the Interacting state. When the manipulation completes, however, the values will always come to rest within the set range. CustomAnimations will always be clamped within the ranges set for position and scale.

The InteractionTracker coordinate space concept aligns with the concept of screen coordinates in that an up/left motion increases the position value and an down/right motion decreases the position value. As a result, it is very common to negate the position property when attaching it to a Visual's Offset.

By default, the minimum and maximum position channels are all 0, and the minimum and maximum scale values are 1. If the desired behavior for either property is to allow it to change outside of these starting values, the minimum/maximum values need to be updated.

InteractionTracker and ExpressionAnimations

InteractionTracker exposes a variety of properties that can be used in the context of ExpressionAnimations to drive updates to animatable properties of CompositionObject s. Due to the asynchronous nature of InteractionTracker, it is not advised to query these properties directly. Instead, you should use the properties delivered in callbacks for driving application logic, and to reference the values in an ExpressionAnimation for updating animatable properties.

As mentioned above, the two most commonly used properties of the InteractionTracker are the Position and Scale properties. These are the properties that will update in response to user input and Try* calls. Using these properties inside ExpressionAnimations will cause the animatable properties of CompositionObjects to update in response. For example, the InteractionTracker.position property may be tied to the Offset of a Visual. It is also common to use these properties to populate a CompositionPropertySet that tracks progress, which can in turn drive a series of coordinated animations.

Directing Input to the InteractionTracker

After being configured, InteractionTracker still requires one last step to actually receive touch input and respond. Please see the documentation on VisualInteractionSource.TryRedirectForManipulation for more information on configuring incoming input to flow into the InteractionTracker.

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)
ImplicitAnimations	The collection of implicit animations attached to this object. (Inherited from CompositionObject)
InteractionSources	A collection of objects that generate interactions.
IsInertiaFromImpulse	Gets a value that indicates whether the inertia is the result of an impulse.
IsPositionRoundingSuggested	Boolean value indicating whether position rounding is currently suggested.
MaxPosition	The maximum position allowed for the InteractionTracker.
MaxScale	The maximum scale for the InteractionTracker.
MinPosition	The minimum position allowed for the InteractionTracker.
MinScale	The minimum scale for the InteractionTracker.
NaturalRestingPosition	Natural resting position for the InteractionTracker. The NaturalRestingPosition property is the calculated position that InteractionTracker will come to a stop at without accounting for boundaries or inertia modifiers. This property is often useful for actions like virtualization in a scrolling experience, where it is important to know the location of where InteractionTracker will stop. There are two main use cases for using the NaturalRestingPosition property: Retrieving its current value in the InertiaStateEntered event args or referencing this property in an ExpressionAnimation when creating things like inertia modifiers.
NaturalRestingScale	Natural resting scale for the InteractionTracker. The NaturalRestingScale property is the calculated scale position that InteractionTracker will come to a stop at without accounting for boundaries or inertia modifiers. This property is often useful for actions like virtualization in a scrolling experience, where it is important to know the location of where InteractionTracker will stop. There are two main use cases for using the NaturalRestingScale property: Retrieving its current value in the InertiaStateEntered event args or referencing this property in an ExpressionAnimation when creating things like inertia modifiers.
Owner	The IInteractionTrackerOwner associated with the InteractionTracker.
Position	The output position calculated by the InteractionTracker. The current position is a relative value. During the Idle and CustomAnimation states, it will always be between the values specified in the MinPosition and MaxPosition properties. The InteractionTracker’s position property can go outside this range during the Interacting and Inertia states in order to show a bounce or resistance at the boundary. The position property of the InteractionTracker is a Vector3 representing position in the X, Y, and Z axis. The X and Y channels are the only components that will be updated by the InteractionTracker at this point. The channels of this Vector3 will not fluctuate outside of 0 (the default value) if the MinPosition and MaxPosition are not set.
PositionInertiaDecayRate	Inertia decay rate for position. Range is from 0 to 1. The PositionInertiaDecayRate property defines the rate at which InteractionTracker will slow to a stop when it has entered Inertia and position is changing. The closer to 1, the faster InteractionTracker will slow to a stop and vice versa. Defined as a Vector3, each component represents the inertia decay rate for x, y, z accordingly.
PositionVelocityInPixelsPerSecond	The velocity currently applied to position. The PositionVelocityInPixelsPerSecond property represents the current position velocity of InteractionTracker while in Inertia. There are two main use cases for this property: Retrieving the position velocity of InteractionTracker right after an interaction has occurred or reference the most current velocity of InteractionTracker in an ExpressionAnimation.
Properties	The collection of properties associated with the CompositionObject. (Inherited from CompositionObject)
Scale	The output scale calculated by the InteractionTracker. The current scale is a relative value that depends on the values specified in the MinScale and MaxScale properties. The scale property of the InteractionTracker is a float representing the scale in the InteractionTracker ’s coordinate space. This value will start at 1 and will increase or decrease based on active input or direct calls to update or animate the property. The scale property when the InteractionTracker is in the Idle or CustomAnimation states will not change from 1 unless the MinScale and MaxScale properties, which both default to 1, are updated. InteractionTracker ’s scale can go slightly outside this range during the Interacting and Inertia states in order to show a bounce or resistance at the boundary.
ScaleInertiaDecayRate	Inertia decay rate, for scale. Range is from 0 to 1. The ScaleInertiaDecayRate property defines the rate at which InteractionTracker will slow to a stop when it has entered Inertia and scale is changing. The closer to 1, the faster InteractionTracker will slow to a stop and vice versa. Unlike the PositionInertiaDecayRate which is defined as a Vector3, ScaleInertiaDecayRate is defined as a single float.
ScaleVelocityInPercentPerSecond	The rate of change for scale. The ScaleVelocityInPercentPerSecond property represents the current scale velocity of InteractionTracker while in Inertia. Grabbing the position velocity of InteractionTracker right after an Interaction has occurred or reference the most current velocity of InteractionTracker in an ExpressionAnimation.

Methods

AdjustPositionXIfGreaterThanThreshold(Single, Single)	Adjusts the position x coordinate if it is greater than the specified threshold.
AdjustPositionYIfGreaterThanThreshold(Single, Single)	Adjusts the position y coordinate if it is greater than the specified threshold.
Close()	Closes the CompositionObject and releases system resources. (Inherited from CompositionObject)
ConfigureCenterPointXInertiaModifiers(IIterable<CompositionConditionalValue>)	Takes an ordered list of CompositionConditionalValue. In a frame, while the tracker is in Inertia, the first CompositionConditionalValue to have its “.Condition” evaluate to true replaces the zoom CenterPointX value the tracker uses with its “.Value”. If none evaluate to true, the CenterPointX is not replaced that frame.
ConfigureCenterPointYInertiaModifiers(IIterable<CompositionConditionalValue>)	Takes an ordered list of CompositionConditionalValue. In a frame, while the tracker is in Inertia, the first CompositionConditionalValue to have its “.Condition” evaluate to true replaces the zoom CenterPointY value the tracker uses with its “.Value”. If none evaluate to true, the CenterPointY is not replaced that frame.
ConfigurePositionXInertiaModifiers(IIterable<InteractionTrackerInertiaModifier>)	Applies a collection of InteractionTrackerInertiaModifier objects to the x inertia of an InteractionTracker. The ConfigurePositionXInertiaModifiers method applies an individual or a collection of InteractionTrackerInertiaModifiers to the x component of InteractionTracker. The system will evaluate each of X modifier's condition property in the order they were added to InteractionTracker. Thus, the order that the InteractionTrackerInertiaModifier have in the collection will be the same order that the system will evaluate with.
ConfigurePositionYInertiaModifiers(IIterable<InteractionTrackerInertiaModifier>)	Applies a collection of InteractionTrackerInertiaModifier objects to the y inertia of an InteractionTracker. The ConfigurePositionYInertiaModifiers method applies an individual or a collection of InteractionTrackerInertiaModifiers to the y component of InteractionTracker. The system will evaluate each of Y modifier’s condition property in the order they were added to InteractionTracker. Thus, the order that the InteractionTrackerInertiaModifier have in the collection will be the same order that the system will evaluate with.
ConfigureScaleInertiaModifiers(IIterable<InteractionTrackerInertiaModifier>)	Applies a collection of InteractionTrackerInertiaModifier objects to the scale of an InteractionTracker. The ConfigureScaleInertiaModifiers method applies an individual or a collection of InteractionTrackerInertiaModifiers to the scale component of InteractionTracker. The system will evaluate each of Scale modifier’s condition property in the order they were added to InteractionTracker. Thus, the order that the InteractionTrackerInertiaModifier have in the collection will be the same order that the system will evaluate with.
ConfigureVector2PositionInertiaModifiers(IIterable<InteractionTrackerVector2InertiaModifier>)	Applies a collection of InteractionTrackerInertiaModifier objects to the position of an InteractionTracker.
Create(Compositor)	Creates an instance of InteractionTracker. This Create method will instantiate an InteractionTracker. After creating the InteractionTracker setting the properties, attaching a VisualInteractionSource, and referencing position or scale in an ExpressionAnimation, active input can drive the ExpressionAnimation.
CreateWithOwner(Compositor, IInteractionTrackerOwner)	Creates an instance of InteractionTracker with the specified owner. This Create method will instantiate an InteractionTracker with an owner for registering for callbacks. After creating the InteractionTracker setting the properties, attaching a VisualInteractionSource, and referencing position or scale in an ExpressionAnimation, active input can drive the ExpressionAnimation. Creating the InteractionTracker with an owner is only required if the application needs to receive callbacks regarding state and values of the InteractionTracker.
Dispose()	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. (Inherited from CompositionObject)
GetBindingMode(InteractionTracker, InteractionTracker)	Retrieves the binding axis mode between two interaction trackers.
PopulatePropertyInfo(String, AnimationPropertyInfo)	Defines a property that can be animated. (Inherited from CompositionObject)
SetBindingMode(InteractionTracker, InteractionTracker, InteractionBindingAxisModes)	Sets the binding axis mode between two interaction trackers.
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)
TryUpdatePosition(Vector3, InteractionTrackerClampingOption, InteractionTrackerPositionUpdateOption)	Tries to update the position of the InteractionTracker using the specified clamping option.
TryUpdatePosition(Vector3, InteractionTrackerClampingOption)	Tries to update the position of the InteractionTracker using the specified clamping option.
TryUpdatePosition(Vector3)	Tries to update the InteractionTracker's position. The TryUpdatePosition method updates the location of InteractionTracker to the Vector3 position specified as a parameter. TryUpdatePosition is used to declaratively define the position of InteractionTracker at any point in time (either at start, from some state-entered event, etc.). TryUpdatePosition can be called from either the Idle, CustomAnimation or Inertia state – doing so will move the position of InteractionTracker to the defined position and enter the idle state.
TryUpdatePositionBy(Vector3, InteractionTrackerClampingOption)	Tries to adjust the position of the InteractionTracker by the specified amount using the specified clamping option.
TryUpdatePositionBy(Vector3)	Tries to adjust the InteractionTracker's position by the specified amount. The TryUpdatePositionBy method updates the current location of InteractionTracker by the Vector3 delta specified as a parameter. Similarly to TryUpdatePosition, TryUpdatePositionBy is used to declaratively move InteractionTracker by a defined delta without the need of an animation or Inertia. TryUpdatePositionBy can be called from either the Idle, CustomAnimation or Inertia state – doing so will move the position of InteractionTracker by the defined delta and enter the idle state.
TryUpdatePositionWithAdditionalVelocity(Vector3)	Tries to update the InteractionTracker's position by adding velocity. The TryUpdatePositionWithAdditionalVelocity method adds the input Vector3 representing additional velocity to the current velocity of InteractionTracker. As a result, because the velocity of InteractionTracker has now changed, the targeted rest position for InteractionTracker now changes. TryUpdatePositionWithAdditionalVelocity can be called from either Idle, Inertia or CustomAnimation states – doing so will either add or update the velocity of InteractionTracker and enter the Inertia state.
TryUpdatePositionWithAnimation(CompositionAnimation)	Tries to update the InteractionTracker's position by applying an animation. The TryUpdatePositionWithAnimation method updates the position of InteractionTracker based on the CompositionAnimation input as a parameter. This method is used in situations in which the motion of InteractionTracker needs to be defined by a specific animation, instead of the traditional Inertia experience. TryUpdatePositionWithAnimation can be called from the Idle or Inertia state – doing so, InteractionTracker ’s position will be driven by the defined animation and enter the CustomAnimation state.
TryUpdateScale(Single, Vector3)	Tries to update the scale to the specified value. The TryUpdateScale method updates the scale location of InteractionTracker to the Scale position and centerpoint specified as a parameter. TryUpdateScale is used to declaratively define the scale of InteractionTracker at any point in time (either at start, from some state-entered event, etc.). TryUpdateScale can be called from either the Idle, CustomAnimation or Inertia state – doing so will move the scale position of InteractionTracker to the defined position and enter the idle state.
TryUpdateScaleWithAdditionalVelocity(Single, Vector3)	Tries to update the scale by adding the specified velocity. The TryUpdateScaleWithAdditionalVelocity method adds the inputted scalar representing additional velocity to the current velocity of InteractionTracker as well as shifts the centerpoint to the inputted Vector3. As a result, because the velocity of InteractionTracker has now changed, the targeted rest scale position for InteractionTracker now changes. TryUpdateScaleWithAdditionalVelocity can be called from either Idle, Inertia or CustomAnimation states – doing so will either add or update the velocity of InteractionTracker and enter the Inertia state.
TryUpdateScaleWithAnimation(CompositionAnimation, Vector3)	Tries to update the scale with the specified animation. The TryUpdateScaleWithAnimation method updates the scale position of InteractionTracker based on the CompositionAnimation inputted as a parameter. This method is used in situations in which the motion of InteractionTracker needs to be defined by a specific animation, instead of the traditional Inertia experience. TryUpdateScaleWithAnimation can be called from the Idle or Inertia state – doing so, InteractionTracker ’s position will be driven by the defined animation and enter the CustomAnimation state.

See also

• VisualInteractionSource
• ExpressionAnimation