Interaction​Tracker Interaction​Tracker Interaction​Tracker Class

Definition

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

Prerelease APIs are identified by a Prerelease label.

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

public : sealed class InteractionTracker : CompositionObject, IInteractionTracker, IInteractionTracker2public sealed class InteractionTracker : CompositionObject, IInteractionTracker, IInteractionTracker2Public NotInheritable Class InteractionTracker Inherits CompositionObject Implements IInteractionTracker, IInteractionTracker2
Inheritance
InteractionTrackerInteractionTrackerInteractionTracker
Attributes
Windows 10 requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Inherited Members

Inherited methods

Inherited properties

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 CompositionAnimation s for custom interaction experiences. In order to build interactive experiences, it is necessary to associate one or more VisualInteractionSource s with the InteractionTracker.

Common Scenarios

IneractionTracker is intended to be used for:

  • Adding custom swipe behavior, for exmaple 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.

InteractionTracker states: Idle, Inertia, Interacting, and Custom Animation

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 StateEnd StatePossible Triggers
IdleInteractingThis state transition only happens when a user manipulation that aligns with a VisualInteractionSource associated with the InteractionTracker is being performed.
IdleInertiaThis state transition only happens when the InteractionTracker is in the Idle state and TryUpdatePositionWithVelocity or TryUpdateScaleWithVelocity is called.
IdleCustomAnimationThis state transition happens when InteractionTracker is in the Idle state and TryUpdatePositionWithAnimation or TryUpdateScaleWithAnimation is called.
InteractingInertiaThis 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.
InertiaIdleThis 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.
InertiaInertiaThis 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.
InertiaCustomAnimationThis state transition happens when a call to TryUpdatePositionWithAnimation or TryUpdateScaleWithAnimation is made while in the Inertia sate.
InertiaInteractingThis state transition happens when active input from the user that hit-tests to the VisualInteractionSource comes in before Inertia has completed.
CustomAnimationIdleThis state transition happens when all animations set on the InteractionTracker’s position and scale properties have completed.
CustomAnimationCustomAnimationThis state transition happens when a call to TryUpdatePositionWithAnimation or TryUpdateScaleWithAnimation is made while already in the CustomAnimation state.
CustomAnimationInertiaThis state transition happens when a call to TryUpdatePositionWithVelocity or TryUpdateScaleWithVelocity is made when in the CustomAnimation state.
CustomAnimationInteractingThis 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 ExpressionAnimation s 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

InteractionSources InteractionSources InteractionSources

A collection of objects that generate interactions.

public : CompositionInteractionSourceCollection InteractionSources { get; }public CompositionInteractionSourceCollection InteractionSources { get; }Public ReadOnly Property InteractionSources As CompositionInteractionSourceCollection
Attributes

IsPositionRoundingSuggested IsPositionRoundingSuggested IsPositionRoundingSuggested

Boolean value indicating whether position rounding is currently suggested.

public : PlatForm::Boolean IsPositionRoundingSuggested { get; }public bool IsPositionRoundingSuggested { get; }Public ReadOnly Property IsPositionRoundingSuggested As bool
Value
PlatForm::Boolean bool bool

Boolean value indicating whether position rounding is currently suggested.

Attributes

MaxPosition MaxPosition MaxPosition

The maximum position allowed for the InteractionTracker.

public : Vector3 MaxPosition { get; set; }public Vector3 MaxPosition { get; set; }Public ReadWrite Property MaxPosition As Vector3
Value
Vector3 Vector3 Vector3

The maximum position allowed for the InteractionTracker.

Attributes

MaxScale MaxScale MaxScale

The maximum scale for the InteractionTracker.

public : float MaxScale { get; set; }public float MaxScale { get; set; }Public ReadWrite Property MaxScale As float
Value
float float float

The maximum scale for the InteractionTracker.

Attributes

MinPosition MinPosition MinPosition

The minimum position allowed for the InteractionTracker.

public : Vector3 MinPosition { get; set; }public Vector3 MinPosition { get; set; }Public ReadWrite Property MinPosition As Vector3
Value
Vector3 Vector3 Vector3

The minimum position allowed for the InteractionTracker.

Attributes

MinScale MinScale MinScale

The minimum scale for the InteractionTracker.

public : float MinScale { get; set; }public float MinScale { get; set; }Public ReadWrite Property MinScale As float
Value
float float float

The minimum scale for the InteractionTracker.

Attributes

NaturalRestingPosition NaturalRestingPosition 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.

public : Vector3 NaturalRestingPosition { get; }public Vector3 NaturalRestingPosition { get; }Public ReadOnly Property NaturalRestingPosition As Vector3
Value
Vector3 Vector3 Vector3

Natural resting position for the InteractionTracker.

Attributes

Examples


// Listen for the InertiaStateEntered event, so can grab NaturalRestingPosition value.
public void InertiaStateEntered(InteractionTracker sender, InteractionTrackerInertiaStateEnteredArgs args)
{
  // Grab the NaturalRestingPosition out of the args when the event is fired. Now have access to calculated Natural Rest spot
  Vector3 naturalRest = args.NaturalRestingPosition;
}

// Reference the NaturalRestingPosition property in an expression for things like   SnapPoints
void CreateBasicSnapPoint(float highBound, float lowBound)
{
  var snappoint = InteractionTrackerInertiaRestingValue.Create(_compositor);

  // Reference the NaturalRestingPosition of InteractionTracker in an ExpressionAnimation for conditional portion of an InertiaModifier.
  snappoint.Condition = _compositor.CreateExpressionAnimation("this.target.NaturalRestingPosition.Y >=  lowBound && this.target.NaturalRestingPosition.Y < highBound ");

  snappoint.Condition.SetScalarParameter("lowBound", lowBound);
  snappoint.Condition.SetScalarParameter("highBound", highBound);

  // Snap to the highbound if condition met
  snappoint.RestingValue = _compositor.CreateExpressionAnimation("highBound");
  snappoint.RestingValue.SetScalarParameter("highBound", highBound);

  yInertiaModifier.Add(snappoint);

  _tracker.ConfigurePositionYInertiaModifiers(yInertiaModifier);
}

Remarks

The two use cases described in the code snippet above are the primary uses of the NaturalRestingPosition property. Although you may be tempted to reference this property off InteractionTracker like any other object.property relationship, you will not always get the most up-to-date value. It is recommended in this situation that you listen for the InertiaStateEntered event and grab the latest value from the arguments.

NaturalRestingScale NaturalRestingScale 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.

public : float NaturalRestingScale { get; }public float NaturalRestingScale { get; }Public ReadOnly Property NaturalRestingScale As float
Value
float float float

Natural resting scale for the InteractionTracker.

Attributes

Examples


// Listen for the InertiaStateEntered event
public void InertiaStateEntered(InteractionTracker sender,  InteractionTrackerInertiaStateEnteredArgs args)
{
  // Grab the NaturalRestingScale out of the args when the event is fired.
  float scaleRest = args.NaturalRestingScale;
}
void CreateBasicScaleSnapPoint(float maxScale, float minScale)
{
  var snappoint = InteractionTrackerInertiaRestingValue.Create(_compositor);

  // Reference the NaturalRestingScale of InteractionTracker in an ExpressionAnimation for conditional portion of an InertiaModifier.
  snappoint.Condition = _compositor.CreateExpressionAnimation("this.target.NaturalRestingScale >= min && this.target.NaturalRestingScale < max ");

  snappoint.Condition.SetScalarParameter("min", minScale);
  snappoint.Condition.SetScalarParameter("max", maxScale);

  // Snap to the highbound if condition met
  snappoint.RestingValue = _compositor.CreateExpressionAnimation("max");
  snappoint.RestingValue.SetScalarParameter("max", maxScale);

  scaleInertiaModifier.Add(snappoint);

  _tracker.ConfigureScaleInertiaModifiers(scaleInertiaModifier);
}

Remarks

The two use cases described in the code snippet are the primary uses of the NaturalRestingScale property. Although you may be tempted to reference this property off InteractionTracker like any other object.property relationship, you will not always get the most up-to-date value. It is recommended in this situation that you listen for the InertiaStateEntered event and grab the latest value from the arguments.

Owner Owner Owner

The IInteractionTrackerOwner associated with the InteractionTracker.

public : IInteractionTrackerOwner Owner { get; }public IInteractionTrackerOwner Owner { get; }Public ReadOnly Property Owner As IInteractionTrackerOwner
Attributes

Position Position 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.

public : Vector3 Position { get; }public Vector3 Position { get; }Public ReadOnly Property Position As Vector3
Value
Vector3 Vector3 Vector3

The output position calculated by the InteractionTracker.

Attributes

Remarks

The InteractionTracker position is populated either by active input through the VisualInteractionSource or by direct calls to update the position. Active vertical or horizontal panning will respectively update the Y and X channels of the Vector3. All calls to animate or update the position accept Vector3 input and each channel can be evaluated individually. The position property used in an ExpressionAnimation will always reflect the current position of the InteractionTracker taking into account factors such as boundaries and inertia modifiers.

PositionInertiaDecayRate PositionInertiaDecayRate 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.

public : IReference<Vector3> PositionInertiaDecayRate { get; set; }public Nullable<Vector3> PositionInertiaDecayRate { get; set; }Public ReadWrite Property PositionInertiaDecayRate As Nullable<Vector3>
Value
IReference<Vector3> Nullable<Vector3> Nullable<Vector3>

Inertia decay rate for position. Range is from 0 to 1.

Attributes

Examples


void SetupInteractionTracker()
{
  // Setup InteractionTracker
  _tracker = InteractionTracker.Create(_compositor);

  // Set the PositionInertiaDecayRate value
  _tracker.PositionInertiaDecayRate = new Vector3(0.95f);
}

Remarks

Below is a graph of the equation that models the PositionInertiaDecayRate property against the position from the starting position of InteractionTracker after entering inertia. Note that as the value of the property approaches 1, the impact of inertia increases more significantly.

In the graph, time is on the X axis, and position from the start of the interaction is on the Y. Notice that with a much larger value (closer to 1), the position from start is much smaller and plateaus earlier.

Slopes of inertia values with decay rates of 0.9, 0.6, 0.4, and 0.2.

PositionVelocityInPixelsPerSecond PositionVelocityInPixelsPerSecond 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.

public : Vector3 PositionVelocityInPixelsPerSecond { get; }public Vector3 PositionVelocityInPixelsPerSecond { get; }Public ReadOnly Property PositionVelocityInPixelsPerSecond As Vector3
Value
Vector3 Vector3 Vector3

The velocity currently applied to position.

Attributes

Examples


// Listen for the InertiaStateEntered event, so we can grab PositionVelocityInPixelsPerSecond value.
public void InertiaStateEntered(InteractionTracker sender, InteractionTrackerInertiaStateEnteredArgs args)
{
  // Grab the current velocity of InteractionTracker after interaction occurs out of the args when the event is fired.
  Vector3 interactionVelocity = args.PositionVelocityInPixelsPerSecond;}
}

void CustomSpringMotion(float springCoefficient, float dampingCoefficient, float maxPosition)
{
  // Create the InertiaModifier that will be a custom motion emulating a spring
  InteractionTrackerInertiaMotion modifier = InteractionTrackerInertiaMotion.Create(_compositor);

  modifier.Condition = _compositor.CreateExpressionAnimation("this.Target.NaturalRestingPosition.X > maxPosition");
  modifier.Condition.SetScalarParameter("maxPosition", maxPosition);

  // Utilize the current Velocity of InteractionTracker in the Expression defining  the custom spring motion
  modifier.Motion = _compositor.CreateExpressionAnimation("(-springStiffnessCoefficient * (this.Target.Position.X – maxPosition)) + (-dampingCoefficient * this.target.PositionVelocityInPixelsPerSecond.X");
  modifier.Motion.SetScalarParameter("springStiffnessCoefficient",  springCoefficient);
  modifier.Motion.SetScalarParameter("dampingCoefficient", dampingCoefficient);
  modifier.Motion.SetScalarParameter("maxPosition", maxPosition); 
}

Remarks

When accessing the PositionVelocityInPixelsPerSecond property from the InertiaStateEntered event, you will be retrieving a snapshot of the calculated velocity based on the interaction. This event will only fire once after the interaction has occurred.

Scale Scale 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.

public : float Scale { get; }public float Scale { get; }Public ReadOnly Property Scale As float
Value
float float float

The output scale calculated by the InteractionTracker.

Attributes

Remarks

The InteractionTracker scale is populated either by active input through the VisualInteractionSource or by direct calls to update the scale. Active “pinch” input will update the InteractionTracker ’s scale property if configured. All calls to animate or update the scale accept float input. The scale property referenced in an ExpressionAnimation will always reflect the current scale of the InteractionTracker taking into account factors such as boundaries and inertia modifiers.

ScaleInertiaDecayRate ScaleInertiaDecayRate 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.

public : IReference<float> ScaleInertiaDecayRate { get; set; }public Nullable<float> ScaleInertiaDecayRate { get; set; }Public ReadWrite Property ScaleInertiaDecayRate As Nullable<float>
Value
IReference<float> Nullable<float> Nullable<float>

Inertia decay rate for scale. Range is from 0 to 1.

Attributes

Examples


void SetupInteractionTracker()
{
  // Setup InteractionTracker
  _tracker = InteractionTracker.Create(_compositor);

  // Set the ScaleInertiaDecayRate value
  _tracker.ScaleInertiaDecayRate = 0.95f;
}

Remarks

Below is a graph of the equation that models the ScaleInertiaDecayRate property. Note that as the value of the property approaches 1, the impact of inertia increases more significantly.

In the graph, time is on the X axis, and position from the start of the interaction is on the Y. Notice that with a much larger value (closer to 1), the position from start is much smaller and plateaus earlier.

Slopes of inertia values with decay rates of 0.9, 0.6, 0.4, and 0.2.

ScaleVelocityInPercentPerSecond ScaleVelocityInPercentPerSecond 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.

public : float ScaleVelocityInPercentPerSecond { get; }public float ScaleVelocityInPercentPerSecond { get; }Public ReadOnly Property ScaleVelocityInPercentPerSecond As float
Value
float float float

The rate of change for scale.

Attributes

Examples


// Listen for the InertiaStateEntered event
public void InertiaStateEntered(InteractionTracker sender,  InteractionTrackerInertiaStateEnteredArgs args)
{
  // Grab the Scale velocity out of the args when the event is fired. 
  float scaleVelocity = args.ScaleVelocityInPercentPerSecond;
}

void CustomSpringMotion(float springCoefficient, float dampingCoefficient, float    maxScale)
{
  // Create the InertiaModifier that will be a custom motion emulating a spring
  InteractionTrackerInertiaMotion modifier = InteractionTrackerInertiaMotion.Create(_compositor);
  modifier.Condition = _compositor.CreateExpressionAnimation("this.Target.NaturalRestingPosition.X > maxScale");
  modifier.Condition.SetScalarParameter("maxScale", maxScale);

  // Utilize the current Velocity of InteractionTracker in the Expression defining  the custom spring motion
  modifier.Motion = _compositor.CreateExpressionAnimation("(-springStiffnessCoefficient * (this.Target.Position.X – maxScale)) + " +
    "(-dampingCoefficient * this.target.ScaleVelocityInPercentPerSecond");
  modifier.Motion.SetScalarParameter("springStiffnessCoefficient", springCoefficient);
  modifier.Motion.SetScalarParameter("dampingCoefficient", dampingCoefficient);
  modifier.Motion.SetScalarParameter("maxScale", maxScale);
}

Remarks

When accessing the ScaleVelocityInPercentPerSecond property off the InertiaStateEntered event, you will be retrieving a snapshot of the calculated velocity based on the Interaction. This event will only fire once after the interaction has occurred.

Methods

AdjustPositionXIfGreaterThanThreshold(Single, Single) AdjustPositionXIfGreaterThanThreshold(Single, Single) AdjustPositionXIfGreaterThanThreshold(Single, Single)

Adjusts the position x coordinate if it is greater than the specified threshold.

public : void AdjustPositionXIfGreaterThanThreshold(float adjustment, float positionThreshold)public void AdjustPositionXIfGreaterThanThreshold(Single adjustment, Single positionThreshold)Public Function AdjustPositionXIfGreaterThanThreshold(adjustment As Single, positionThreshold As Single) As void
Parameters
adjustment
float Single Single

The amount to adjust the position x coordinate.

positionThreshold
float Single Single

The threshold for ajusting the position x coordinate.

Attributes

AdjustPositionYIfGreaterThanThreshold(Single, Single) AdjustPositionYIfGreaterThanThreshold(Single, Single) AdjustPositionYIfGreaterThanThreshold(Single, Single)

Adjusts the position y coordinate if it is greater than the specified threshold.

public : void AdjustPositionYIfGreaterThanThreshold(float adjustment, float positionThreshold)public void AdjustPositionYIfGreaterThanThreshold(Single adjustment, Single positionThreshold)Public Function AdjustPositionYIfGreaterThanThreshold(adjustment As Single, positionThreshold As Single) As void
Parameters
adjustment
float Single Single

The amount to adjust the position y coordinate.

positionThreshold
float Single Single

The threshold for ajusting the position y coordinate.

Attributes

ConfigureCenterPointXInertiaModifiers(IIterable<CompositionConditionalValue>) ConfigureCenterPointXInertiaModifiers(IIterable<CompositionConditionalValue>) 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.

public : void ConfigureCenterPointXInertiaModifiers(IIterable<CompositionConditionalValue> conditionalValues)public void ConfigureCenterPointXInertiaModifiers(IEnumerable<CompositionConditionalValue> conditionalValues)Public Function ConfigureCenterPointXInertiaModifiers(conditionalValues As IEnumerable<CompositionConditionalValue>) As void
Parameters
conditionalValues
IIterable<CompositionConditionalValue> IEnumerable<CompositionConditionalValue> IEnumerable<CompositionConditionalValue>
Attributes
Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

ConfigureCenterPointYInertiaModifiers(IIterable<CompositionConditionalValue>) ConfigureCenterPointYInertiaModifiers(IIterable<CompositionConditionalValue>) 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.

public : void ConfigureCenterPointYInertiaModifiers(IIterable<CompositionConditionalValue> conditionalValues)public void ConfigureCenterPointYInertiaModifiers(IEnumerable<CompositionConditionalValue> conditionalValues)Public Function ConfigureCenterPointYInertiaModifiers(conditionalValues As IEnumerable<CompositionConditionalValue>) As void
Parameters
conditionalValues
IIterable<CompositionConditionalValue> IEnumerable<CompositionConditionalValue> IEnumerable<CompositionConditionalValue>
Attributes
Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

ConfigurePositionXInertiaModifiers(IIterable<InteractionTrackerInertiaModifier>) ConfigurePositionXInertiaModifiers(IIterable<InteractionTrackerInertiaModifier>) 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 InteractionTrackerInertiaModifier s 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.

public : void ConfigurePositionXInertiaModifiers(IIterable<InteractionTrackerInertiaModifier> modifiers)public void ConfigurePositionXInertiaModifiers(IEnumerable<InteractionTrackerInertiaModifier> modifiers)Public Function ConfigurePositionXInertiaModifiers(modifiers As IEnumerable<InteractionTrackerInertiaModifier>) As void
Parameters
modifiers
IIterable<InteractionTrackerInertiaModifier> IEnumerable<InteractionTrackerInertiaModifier> IEnumerable<InteractionTrackerInertiaModifier>

The collection of InteractionTrackerInertiaModifier objects to apply to the x inertia of an InteractionTracker.

Attributes

Examples


void SimpleXModifer(CompositionPropertySet shared)
{
  // Create the Inertia Modifier for X Direction.
  var xModifier = InteractionTrackerInertiaRestingValue.Create(_compositor);

  // For sample purpose, always true condition
  xModifier.Condition = _compositor.CreateExpressionAnimation("5 > 3");
  xModifier.RestingValue = _compositor.CreateExpressionAnimation("this.Target.Position.X - shared.snapRangeX");
  xModifier.RestingValue.SetReferenceParameter("shared", _sharedDelta);
  var xModifierList = new InteractionTrackerInertiaRestingValue[] { xModifier };

  // Add modifier list to InteractionTracker.
  _tracker.ConfigurePositionXInertiaModifiers(xModifierList); 
}

Remarks

If you have a dependency on the system evaluating the inertia modifiers in a particular order, ensure that they are inserted into the list (if multiple) or into InteractionTracker directly (if single) in the order you want them evaluated. The system will evaluate the conditions of the inertia modifiers in the order they are inserted.

ConfigurePositionYInertiaModifiers(IIterable<InteractionTrackerInertiaModifier>) ConfigurePositionYInertiaModifiers(IIterable<InteractionTrackerInertiaModifier>) 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 InteractionTrackerInertiaModifier s 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.

public : void ConfigurePositionYInertiaModifiers(IIterable<InteractionTrackerInertiaModifier> modifiers)public void ConfigurePositionYInertiaModifiers(IEnumerable<InteractionTrackerInertiaModifier> modifiers)Public Function ConfigurePositionYInertiaModifiers(modifiers As IEnumerable<InteractionTrackerInertiaModifier>) As void
Parameters
modifiers
IIterable<InteractionTrackerInertiaModifier> IEnumerable<InteractionTrackerInertiaModifier> IEnumerable<InteractionTrackerInertiaModifier>

The collection of InteractionTrackerInertiaModifier objects to apply to the y inertia of an InteractionTracker.

Attributes

Examples


void SimpleYModifer(CompositionPropertySet shared)
{
  // Create the Inertia Modifier for Y Direction.
  var yModifier = InteractionTrackerInertiaRestingValue.Create(_compositor);

  // For sample purpose, always true condition
  yModifier.Condition = _compositor.CreateExpressionAnimation("5 > 3");
  yModifier.RestingValue = _compositor.CreateExpressionAnimation("this.Target.Position.Y - shared.snapRangeY");
  yModifier.RestingValue.SetReferenceParameter("shared", shared);
  var yModifierList = new InteractionTrackerInertiaRestingValue[] { yModifier };

  // Add modifier list to InteractionTracker.
  _tracker.ConfigurePositionYInertiaModifiers(yModifierList); 
}

ConfigureScaleInertiaModifiers(IIterable<InteractionTrackerInertiaModifier>) ConfigureScaleInertiaModifiers(IIterable<InteractionTrackerInertiaModifier>) 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 InteractionTrackerInertiaModifier s 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.

public : void ConfigureScaleInertiaModifiers(IIterable<InteractionTrackerInertiaModifier> modifiers)public void ConfigureScaleInertiaModifiers(IEnumerable<InteractionTrackerInertiaModifier> modifiers)Public Function ConfigureScaleInertiaModifiers(modifiers As IEnumerable<InteractionTrackerInertiaModifier>) As void
Parameters
modifiers
IIterable<InteractionTrackerInertiaModifier> IEnumerable<InteractionTrackerInertiaModifier> IEnumerable<InteractionTrackerInertiaModifier>

The collection of InteractionTrackerInertiaModifier objects to apply to the scale of an InteractionTracker.

Attributes

Examples


void SimpleScaleModifer(CompositionPropertySet shared)
{
  // Create the Inertia Modifier for Scale.
  var scaleModifier = InteractionTrackerInertiaRestingValue.Create(_compositor);

  // For sample purpose, always true condition
  scaleModifier.Condition = _compositor.CreateExpressionAnimation("5 > 3");

  scaleModifier.RestingValue = _compositor.CreateExpressionAnimation("this.Target.Scale - shared.scaleRange");
  scaleModifier.RestingValue.SetReferenceParameter("shared", shared);
  var scaleModifierList = new InteractionTrackerInertiaRestingValue[] { scaleModifier };

  // Add modifier list to InteractionTracker.
  _tracker.ConfigureScaleInertiaModifiers(scaleModifierList); 
}

ConfigureVector2PositionInertiaModifiers(IIterable<InteractionTrackerVector2InertiaModifier>) ConfigureVector2PositionInertiaModifiers(IIterable<InteractionTrackerVector2InertiaModifier>) ConfigureVector2PositionInertiaModifiers(IIterable<InteractionTrackerVector2InertiaModifier>)

Prerelease. Applies a collection of InteractionTrackerInertiaModifier objects to the position of an InteractionTracker.

public : void ConfigureVector2PositionInertiaModifiers(IIterable<InteractionTrackerVector2InertiaModifier> modifiers)public void ConfigureVector2PositionInertiaModifiers(IEnumerable<InteractionTrackerVector2InertiaModifier> modifiers)Public Function ConfigureVector2PositionInertiaModifiers(modifiers As IEnumerable<InteractionTrackerVector2InertiaModifier>) As void
Parameters
modifiers
IIterable<InteractionTrackerVector2InertiaModifier> IEnumerable<InteractionTrackerVector2InertiaModifier> IEnumerable<InteractionTrackerVector2InertiaModifier>

The collection of InteractionTrackerInertiaModifier objects to apply to the position of an InteractionTracker.

Attributes
Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.16225.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

Create(Compositor) Create(Compositor) 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.

public : static InteractionTracker Create(Compositor compositor)public static InteractionTracker Create(Compositor compositor)Public Static Function Create(compositor As Compositor) As InteractionTracker
Parameters
compositor
Compositor Compositor Compositor

The compositor to use when creating the InteractionTracker.

Returns
Attributes

CreateWithOwner(Compositor, IInteractionTrackerOwner) CreateWithOwner(Compositor, IInteractionTrackerOwner) 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.

public : static InteractionTracker CreateWithOwner(Compositor compositor, IInteractionTrackerOwner owner)public static InteractionTracker CreateWithOwner(Compositor compositor, IInteractionTrackerOwner owner)Public Static Function CreateWithOwner(compositor As Compositor, owner As IInteractionTrackerOwner) As InteractionTracker
Parameters
compositor
Compositor Compositor Compositor

The compositor to use to create the instance of InteractionTracker.

Returns
Attributes

TryUpdatePosition(Vector3) TryUpdatePosition(Vector3) 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.

public : int TryUpdatePosition(Vector3 value)public int TryUpdatePosition(Vector3 value)Public Function TryUpdatePosition(value As Vector3) As int
Parameters
value
Vector3 Vector3 Vector3

The new position for the InteractionTracker.

Returns
int int int

Returns the request ID. On state transitions, the request which caused the change in state will be included in the args. These IDs will start at 1 and increase with each try call during the lifetime of the application.

Attributes

Examples


void SetupInteractionTracker()
{
  // Setup InteractionTracker
  _tracker = InteractionTracker.Create(_compositor);
  _interactionSource.PositionXSourceMode = InteractionSourceMode.EnabledWithInertia;
  _interactionSource.PositionYSourceMode = InteractionSourceMode.EnabledWithInertia;

  _tracker.InteractionSources.Add(_interactionSource);
  _tracker.PositionInertiaDecayRate = new Vector3(0.95f);

  // Update the position of InteractionTracker, so doesn’t start at (0,0)
  _tracker.TryUpdatePosition(new Vector3(50f));
}

Remarks

If InteractionTracker is in its Interacting State (user actively manipulating), and TryUpdatePosition is called, the system will ignore this request – an event gets fired when this occurs that can be listened for. If sent from one of the other states, listen for the event fired for IdleStateEntered and check the RequestId property that identifies which request triggered the callback. The table below summarizes the expected behavior when this method is called in a particular state:

Current StateOutcome
IdleProperty updates to requested value, no state changes
InteractingRequest ignored
InertiaProperty updates to requested value, state changes to Idle
CustomAnimationProperty updates to requested value, state changes to Idle

TryUpdatePositionBy(Vector3) TryUpdatePositionBy(Vector3) 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.

public : int TryUpdatePositionBy(Vector3 amount)public int TryUpdatePositionBy(Vector3 amount)Public Function TryUpdatePositionBy(amount As Vector3) As int
Parameters
amount
Vector3 Vector3 Vector3

The value to add to the current position.

Returns
int int int

Returns the request ID. On state transitions, the request which caused the change in state will be included in the args. These IDs will start at 1 and increase with each try call during the lifetime of the application.

Attributes

Examples


public void InertiaStateEntered(InteractionTracker sender,  InteractionTrackerInertiaStateEnteredArgs args)
{
  // For sample purpose, will overwrite Inertia motion definitions by moving InteractionTracker to a specified position based on a delta
  _tracker.TryUpdatePositionBy(new Vector3(50f));}
}

Remarks

If InteractionTracker is in its Interacting State (user actively manipulating), and TryUpdatePositionBy is called, the system will ignore this request – an event gets fired when this occurs that can be listened for. If sent from one of the other states, listen for the event fired for IdleStateEntered and check the RequestId property that identifies which request triggered the callback. The table below summarizes the expected behavior when this method is called in a particular state:

Current StateOutcome
IdleProperty updates to requested value, no state changes
InteractingRequest ignored
InertiaProperty updates to requested value, state changes to Idle
CustomAnimationProperty updates to requested value, state changes to Idle

TryUpdatePositionWithAdditionalVelocity(Vector3) TryUpdatePositionWithAdditionalVelocity(Vector3) 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.

public : int TryUpdatePositionWithAdditionalVelocity(Vector3 velocityInPixelsPerSecond)public int TryUpdatePositionWithAdditionalVelocity(Vector3 velocityInPixelsPerSecond)Public Function TryUpdatePositionWithAdditionalVelocity(velocityInPixelsPerSecond As Vector3) As int
Parameters
velocityInPixelsPerSecond
Vector3 Vector3 Vector3

The velocity to add in pixels per second.

Returns
int int int

Returns the request ID. On state transitions, the request which caused the change in state will be included in the args. These IDs will start at 1 and increase with each try call during the lifetime of the application.

Attributes

Examples


// Listen for the InertiaStateEntered event
public void InertiaStateEntered(InteractionTracker sender,  InteractionTrackerInertiaStateEnteredArgs args)
{
  // Adding velocity to InteractionTracker if condition met
  if (_extraVelocityNeeded)
  {
    // Only adding velocity in the Y direction
    _tracker.TryUpdatePositionWithAdditionalVelocity(new Vector3(0.0f, 50.0f,   0.0f));
  }
}

Remarks

If InteractionTracker is in its Interacting State (user actively manipulating), and TryUpdatePositionWithAdditionalVelocity is called, the system will ignore this request – an event gets fired when this occurs that can be listened for. If sent from one of the other states, listen for the event fired for InertiaStateEntered and check the RequestId property that identifies which request triggered the callback. The table below summarizes the expected behavior when this method is called in a particular state:

Current StateOutcome
IdleState changes to inertia and inertia modifiers are evaluated with requested velocity as initial velocity
InteractingRequest ignored
InertiaInertia is restarted (state re-enters inertia) and inertia modifiers are evaluated with requested velocity added to current velocity
CustomAnimationCurrent animation stops and state changes to inertia with inertia modifiers evaluated using requested velocity as initial velocity

TryUpdatePositionWithAnimation(CompositionAnimation) TryUpdatePositionWithAnimation(CompositionAnimation) 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.

public : int TryUpdatePositionWithAnimation(CompositionAnimation animation)public int TryUpdatePositionWithAnimation(CompositionAnimation animation)Public Function TryUpdatePositionWithAnimation(animation As CompositionAnimation) As int
Parameters
Returns
int int int

Returns the request ID. On state transitions, the request which caused the change in state will be included in the args. These IDs will start at 1 and increase with each try call during the lifetime of the application.

Attributes

Examples


void CustomAnimationForIT(Vector3 newPosition)
{
  // Create a cubic bezier easing function that will be used in the KeyFrames
  CompositionEasingFunction cubicBezier = _compositor.CreateCubicBezierEasingFunction(new Vector2(.17f, .67f), new Vector2(1f, 1f);

  // Create the Vector3 KFA
  Vector3KeyFrameAnimation kfa = _compositor.CreateVector3KeyFrameAnimation();
  kfa.Duration = TimeSpan.FromSeconds(3);

  // Create the KeyFrames
  kfa.InsertKeyFrame(1.0f, newPosition, cubicBezier);

  // Update InteractionTracker position using this animation
  _tracker.TryUpdatePositionWithAnimation(kfa);
}

Remarks

When creating the animation you want to update InteractionTracker ’s position with, you do not need to call StartAnimation. The system will take care of this behind the scenes once the animation is passed in via TryUpdatePositionWithAnimation.

When defining the animation that will animate InteractionTracker ’s position, be sure to either use a Vector3KeyFrameAnimation or an ExpressionAnimation that resolves to a Vector3.

The table below summarizes the expected behavior when this method is called in a particular state:

Current StateOutcome
IdleRequested animation starts on requested property, state changes to CustomAnimation
InteractingRequest ignored
InertiaRequested animation starts on requested property, state changes to CustomAnimation
CustomAnimationCurrent animation stops and new requested animation starts on requested property, state re-enters CustomAnimation

TryUpdateScale(Single, Vector3) TryUpdateScale(Single, Vector3) 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.

public : int TryUpdateScale(float value, Vector3 centerPoint)public int TryUpdateScale(Single value, Vector3 centerPoint)Public Function TryUpdateScale(value As Single, centerPoint As Vector3) As int
Parameters
value
float Single Single

The new value for scale.

centerPoint
Vector3 Vector3 Vector3

The new center point.

Returns
int int int

Returns the request ID. On state transitions, the request which caused the change in state will be included in the args. These IDs will start at 1 and increase with each try call during the lifetime of the application.

Attributes

Examples


void SetupInteractionTracker()
{
  // Setup InteractionTracker
  _tracker = InteractionTracker.Create(_compositor);
  _interactionSource.PositionXSourceMode = InteractionSourceMode.EnabledWithInertia;
  _interactionSource.PositionYSourceMode = InteractionSourceMode.EnabledWithInertia;

  _tracker.InteractionSources.Add(_interactionSource);
  _tracker.PositionInertiaDecayRate = new Vector3(0.95f);

  // Update the scale position of InteractionTracker
  _tracker.TryUpdateScale(0.5f, new Vector3(50f));
}

Remarks

If InteractionTracker is in its Interacting State (user actively manipulating), and TryUpdateScale is called, the system will ignore this request – an event gets fired when this occurs that can be listened for. If sent from one of the other states, listen for the event fired for IdleStateEntered and check the RequestID property that identifies which request triggered the callback.

The table below summarizes the expected behavior when this method is called in a particular state:

Current StateOutcome
IdleProperty updates to requested value, no state changes
InteractingRequest ignored
InertiaProperty updates to requested value, state changes to Idle
CustomAnimationProperty updates to requested value, state changes to Idle

TryUpdateScaleWithAdditionalVelocity(Single, Vector3) TryUpdateScaleWithAdditionalVelocity(Single, Vector3) 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.

public : int TryUpdateScaleWithAdditionalVelocity(float velocityInPercentPerSecond, Vector3 centerPoint)public int TryUpdateScaleWithAdditionalVelocity(Single velocityInPercentPerSecond, Vector3 centerPoint)Public Function TryUpdateScaleWithAdditionalVelocity(velocityInPercentPerSecond As Single, centerPoint As Vector3) As int
Parameters
velocityInPercentPerSecond
float Single Single

The velocity to add to the scale.

centerPoint
Vector3 Vector3 Vector3

The new center point.

Returns
int int int

Returns the request ID. On state transitions, the request which caused the change in state will be included in the args. These IDs will start at 1 and increase with each try call during the lifetime of the application.

Attributes

Examples


// Listen for the InertiaStateEntered event
public void InertiaStateEntered(InteractionTracker sender,  InteractionTrackerInertiaStateEnteredArgs args)
{
  // Adding velocity to InteractionTracker if condition met
  if (_extraVelocityNeeded)
  {
    // Adding velocity to the scale motion.
    _tracker.TryUpdateScaleWithAdditionalVelocity(3.0f, new Vector3(75f));
  }
}

Remarks

If InteractionTracker is in its Interacting State (user actively manipulating), and TryUpdateScaleWithAdditionalVelocity is called, the system will ignore this request – an event gets fired when this occurs that can be listened for. If sent from one of the other states, listen for the event fired for InertiaStateEntered and check the RequestId property that identifies which request triggered the callback.

The table below summarizes the expected behavior when this method is called in a particular state:

Current StateOutcome
IdleState changes to inertia and inertia modifiers are evaluated with requested velocity as initial velocity
InteractingRequest ignored
InertiaInertia is restarted (state re-enters inertia) and inertia modifiers are evaluated with requested velocity added to current velocity
CustomAnimationCurrent animation stops and state changes to inertia with inertia modifiers evaluated using requested velocity as initial velocity

TryUpdateScaleWithAnimation(CompositionAnimation, Vector3) TryUpdateScaleWithAnimation(CompositionAnimation, Vector3) 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.

public : int TryUpdateScaleWithAnimation(CompositionAnimation animation, Vector3 centerPoint)public int TryUpdateScaleWithAnimation(CompositionAnimation animation, Vector3 centerPoint)Public Function TryUpdateScaleWithAnimation(animation As CompositionAnimation, centerPoint As Vector3) As int
Parameters
animation
CompositionAnimation CompositionAnimation CompositionAnimation

The animation to apply to the scale.

centerPoint
Vector3 Vector3 Vector3

The new center point.

Returns
int int int

Returns the request ID. On state transitions, the request which caused the change in state will be included in the args. These IDs will start at 1 and increase with each try call during the lifetime of the application.

Attributes

Examples


void CustomAnimationForIT(float newScale, Vector3 newCenterPoint)
{
  // Create a cubic bezier easing function that will be used in the KeyFrames
  CompositionEasingFunction cubicBezier = _compositor.CreateCubicBezierEasingFunction(new Vector2(.17f, .67f), new Vector2(1f, 1f);

  // Create the Vector3 KFA
  ScalarKeyFrameAnimation kfa = _compositor.CreateScalarKeyFrameAnimation();
  kfa.Duration = TimeSpan.FromSeconds(3);

  // Create the KeyFrames
  kfa.InsertKeyFrame(1.0f, newScale, cubicBezier);

  // Update InteractionTracker position using this animation
  _tracker.TryUpdatePositionWithAnimation(kfa, newCenterPoint);
}

Remarks

When creating the animation you want to update InteractionTracker ’s position with, you do not need to call StartAnimation. The system will take care of this behind the scenes once the animation is passed in via TryUpdateScaleWithAnimation.

When defining the animation that will animate InteractionTracker ’s scale position, be sure to either use a ScalarKeyFrameAnimation or an ExpressionAnimation that resolves to a Scalar.

The table below summarizes the expected behavior when this method is called in a particular state:

Current StateOutcome
IdleRequested animation starts on requested property, state changes to CustomAnimation
InteractingRequest ignored
InertiaRequested animation starts on requested property, state changes to CustomAnimation
CustomAnimationCurrent animation stops and new requested animation starts on requested property, state re-enters CustomAnimation