VisualInteractionSource Class

Definition

Object for configuring input to the InteractionTracker relative to a visual.

The VisualInteractionSource is designed to be used only with InteractionTracker and defines which input will be sent to the InteractionTracker to drive its state and properties. This class contains both the visual to be used for hit-testing, as well as a variety of configuration properties for which gestures and types of input will be sent to the InteractionTracker.

Equivalent WinUI class: Microsoft.UI.Composition.Interactions.VisualInteractionSource.

public ref class VisualInteractionSource sealed : CompositionObject, ICompositionInteractionSource
public ref class VisualInteractionSource : CompositionObject, ICompositionInteractionSource
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 196608)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class VisualInteractionSource final : CompositionObject, ICompositionInteractionSource
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 196608)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class VisualInteractionSource : CompositionObject, ICompositionInteractionSource
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 196608)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class VisualInteractionSource : CompositionObject, ICompositionInteractionSource
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 196608)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public class VisualInteractionSource : CompositionObject, ICompositionInteractionSource
Public NotInheritable Class VisualInteractionSource
Inherits CompositionObject
Implements ICompositionInteractionSource
Public Class VisualInteractionSource
Inherits CompositionObject
Implements ICompositionInteractionSource
Inheritance
VisualInteractionSource
Attributes
Implements

Windows requirements

Device family
Windows 10 Anniversary Edition (introduced in 10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced in v3.0)

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 
  // end 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 axis.
  //

  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

The VisualInteractionSource is used to define important properties about the types of interactions that should drive the InteractionTracker's state and properties. The source property is used both for hit-testing, as well as the coordinate space for gesture detection. As a result, it is important to use a Visual that is not going to be in motion during the manipulation. Multiple VisualInteractionSources can be associated with the same InteractionTracker if there are multiple hit-test regions, but the most common cases require only one VisualInteractionSource for a given InteractionTracker.

VisualInteractionSource is the class for configuring which types of gestures should be considered for driving the InteractionTracker. Position X and Y are associated with horizontal and vertical panning respectively. Scale is detected with a pinch gesture, often associated with zooming. These three source modes are all configurable for touch and Precision Touchpad input. Each of these source modes can be enabled with or without inertia:

  • Enabling inertia indicates that position or scale will naturally interpolate from the release velocity to no velocity during the inertia state.

  • Disabling inertia indicates that position or scale velocity will immediately go to 0 upon completion of the interaction. When input that drives position or scale is routed to the InteractionTracker, the InteractionTracker property of the same name will be updated appropriately.

The rails configurations indicate how the gesture will be detected. Rails, by default, is on and indicates that the horizontal or vertical pan will lock to a particular axis when started primarily on that axis. This is explained in more detail on the railing property pages.

The chaining configuration indicates whether input that is processed by one VisualInteractionSource can flow to another entity when the InteractionTracker reaches the min or max in that direction. This configuration will allow input to chain to either another InteractionTracker via another VisualInteractionSource, or to a ScrollViewer if the VisualInteractionSource's source visual is a child of the ScrollViewer.

Version history

Windows version SDK version Value added
1703 15063 ConfigureCenterPointXModifiers
1703 15063 ConfigureCenterPointYModifiers
1703 15063 ConfigureDeltaPositionXModifiers
1703 15063 ConfigureDeltaPositionYModifiers
1703 15063 ConfigureDeltaScaleModifiers
1703 15063 DeltaPosition
1703 15063 DeltaScale
1703 15063 Position
1703 15063 PositionVelocity
1703 15063 Scale
1703 15063 ScaleVelocity
1809 17763 PointerWheelConfig
1903 18362 CreateFromIVisualElement

Properties

Comment

A string to associate with the CompositionObject.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionObject.Comment.

(Inherited from CompositionObject)
Compositor

The Compositor used to create this CompositionObject.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionObject.Compositor.

(Inherited from CompositionObject)
DeltaPosition

The amount of position change to be applied during the upcoming frame. Defaults to 0. Readable only via expression/animation.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.DeltaPosition.

DeltaScale

The amount of scale change to be applied during the upcoming frame. Multiplicative. Defaults to 1. Readable only via expression/animation.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.DeltaScale.

Dispatcher

The dispatcher for the CompositionObject.

(Inherited from CompositionObject)
DispatcherQueue

Gets the DispatcherQueue for the CompostionObject.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionObject.DispatcherQueue.

(Inherited from CompositionObject)
ImplicitAnimations

The collection of implicit animations attached to this object.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionObject.ImplicitAnimations.

(Inherited from CompositionObject)
IsPositionXRailsEnabled

Indicates whether panning on the x-axis is railed.

The IsPositionXRailsEnabled property defines the railing configuration for when X-axis panning gets sent to the corresponding InteractionTracker. When enabled, if the initial part of the pan is angled within a particular range relative to the X-axis, the Y component of the pan is ignored and considered a perfect horizontal pan. This property is often enabled in situations where both an X and Y scrolling experience is enabled, but also requires reliable, perfect horizontal panning.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.IsPositionXRailsEnabled.

IsPositionYRailsEnabled

Indicates whether panning on the y-axis is railed.

The IsPositionYRailsEnabled property defines the railing configuration for when Y-axis panning gets sent to the corresponding InteractionTracker. When enabled, if the initial part of the pan is angled within a particular range relative to the Y-axis, the X component of the pan is ignored and considered a perfect vertical pan. This property is often enabled in situations where both an X and Y scrolling experience is enabled, but also requires reliable, perfect vertical panning.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.IsPositionYRailsEnabled.

ManipulationRedirectionMode

Indicates what input should be redirected to the InteractionTracker.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.ManipulationRedirectionMode.

PointerWheelConfig

Gets the configuration for pointer wheel input.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.PointerWheelConfig.

Position

The total amount of position change since the start of the interaction. Defaults to 0. Readable only via expression/animation.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.Position.

PositionVelocity

The instantaneous rate of change of position in the interaction, in pixels per second. Defaults to 0. Readble only via expression/animation.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.PositionVelocity.

PositionXChainingMode

The PositionXChainingMode property defines the chaining behavior for an InteractionSource in the X direction. There are three types of InteractionChainingMode s: Auto , Always , Never . When chaining in the X direction is enabled, input will flow to the nearest ancestor's VisualInteractionSource whenever the interaction (such as panning) would otherwise take InteractionTracker ’s position past its minimum or maximum X position.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.PositionXChainingMode.

PositionXSourceMode

Source mode for the X-axis.

The PositionXSourceMode property defines how interactions are processed for a VisualInteractionSource on the X-axis. There are 3 types of InteractionSourceMode s to choose from: Interactions are Disabled, EnabledWithInertia and EnabledWithoutInertia. This property must be enabled to allow the VisualInteractionSource to send X-axis data to InteractionTracker.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.PositionXSourceMode.

PositionYChainingMode

The PositionYChainingMode property defines the chaining behavior for an InteractionSource in the Y direction. There are three types of InteractionChainingMode s: Auto , Always , Never . When chaining in the Y direction is enabled, input will flow to the nearest ancestor’s VisualInteractionSource whenever the interaction (such as panning) would otherwise take InteractionTracker ’s position past its minimum or maximum Y position.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.PositionYChainingMode.

PositionYSourceMode

Source mode for the Y-axis.

The PositionYSourceMode property defines how interactions are processed for a VisualInteractionSource on the Y-axis. There are 3 types of InteractionSourceMode s to choose from: Interactions are Disabled, EnabledWithInertia and EnabledWithoutInertia. This property must be enabled to allow the VisualInteractionSource to send Y-axis data to InteractionTracker.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.PositionYSourceMode.

Properties

The collection of properties associated with the CompositionObject.

Equivalent WinUI property: Microsoft.UI.Composition.CompositionObject.Properties.

(Inherited from CompositionObject)
Scale

The total percentage-difference in scale since the start of the interaction. Multiplicative. Defaults to 1. Readable only via expression/animation.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.Scale.

ScaleChainingMode

The ScaleChainingMode property defines the chaining behavior for an InteractionSource in the Scale direction. There are three types of InteractionChainingMode s: Auto, Always, Never. When Scale chaining is enabled, input will flow to the nearest ancestor’s VisualInteractionSource whenever the interaction (such as panning) would otherwise take InteractionTracker ’s position past it’s minimum or maximum Scale position.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.ScaleChainingMode.

ScaleSourceMode

Defines how interactions are processed for an VisualInteractionSource on the scale axis. There are 3 types of InteractionSourceMode s to choose from: Interactions are Disabled , EnabledWithInertia and EnabledWithoutInertia . This property must be enabled to allow the VisualInteractionSource to send scale data to InteractionTracker.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.ScaleSourceMode.

ScaleVelocity

The instantaneous rate of change of scale in the interaction, in percent per second. Additive. Defaults to 0. Readble only via expression/animation.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.ScaleVelocity.

Source

The visual that is used for hit-testing and defines the co-ordinate space for gesture recognition.

Equivalent WinUI property: Microsoft.UI.Composition.Interactions.VisualInteractionSource.Source.

Methods

Close()

Closes the CompositionObject and releases system resources.

Equivalent WinUI method: Microsoft.UI.Composition.CompositionObject.Close.

(Inherited from CompositionObject)
ConfigureCenterPointXModifiers(IEnumerable<CompositionConditionalValue>)

Takes an ordered list of CompositionConditionalValue. In a frame, the first CompositionConditionalValue to have its “.Condition” evaluate to true replaces the zoom CenterPointX value the VisualInteractionSource provides with its “.Value”. If none evaluate to true, the CenterPointX is not replaced that frame. Equivalent WinUI method: Microsoft.UI.Composition.Interactions.VisualInteractionSource.ConfigureCenterPointXModifiers.

ConfigureCenterPointYModifiers(IEnumerable<CompositionConditionalValue>)

Takes an ordered list of CompositionConditionalValue. In a frame, the first CompositionConditionalValue to have its “.Condition” evaluate to true replaces the zoom CenterPointY value the VisualInteractionSource provides with its “.Value”. If none evaluate to true, the CenterPointY is not replaced that frame.

Equivalent WinUI method: Microsoft.UI.Composition.Interactions.VisualInteractionSource.ConfigureCenterPointYModifiers.

ConfigureDeltaPositionXModifiers(IEnumerable<CompositionConditionalValue>)

Takes an ordered list of CompositionConditionalValue. In a frame, the first CompositionConditionalValue to have its “.Condition” evaluate to true replaces the DeltaPositionX value the VisualInteractionSource provides with its “.Value”. If none evaluate to true, the DeltaPositionX is not replaced that frame.

Equivalent WinUI method: Microsoft.UI.Composition.Interactions.VisualInteractionSource.ConfigureDeltaPositionXModifiers.

ConfigureDeltaPositionYModifiers(IEnumerable<CompositionConditionalValue>)

Takes an ordered list of CompositionConditionalValue. In a frame, the first CompositionConditionalValue to have its “.Condition” evaluate to true replaces the DeltaPositionY value the VisualInteractionSource provides with its “.Value”. If none evaluate to true, the DeltaPositionY is not replaced that frame.

Equivalent WinUI method: Microsoft.UI.Composition.Interactions.VisualInteractionSource.ConfigureDeltaPositionYModifiers.

ConfigureDeltaScaleModifiers(IEnumerable<CompositionConditionalValue>)

Takes an ordered list of CompositionConditionalValue. In a frame, the first CompositionConditionalValue to have its “.Condition” evaluate to true replaces the DeltaScale value the VisualInteractionSource provides with its “.Value”. If none evaluate to true, the DeltaScale is not replaced that frame.

Equivalent WinUI method: Microsoft.UI.Composition.Interactions.VisualInteractionSource.ConfigureDeltaScaleModifiers.

ConnectAnimation(String, CompositionAnimation)

Connects and animation.

(Inherited from CompositionObject)
Create(Visual)

Creates an instance of VisualInteractionSource.

Equivalent WinUI method: Microsoft.UI.Composition.Interactions.VisualInteractionSource.Create.

CreateFromIVisualElement(IVisualElement)

Creates an instance of VisualInteractionSource from an element that implements IVisualElement.

Equivalent WinUI method: Microsoft.UI.Composition.Interactions.VisualInteractionSource.CreateFromIVisualElement.

DisconnectAnimation(String)

Disconnects an animation.

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

Equivalent WinUI method: Microsoft.UI.Composition.CompositionObject.PopulatePropertyInfo.

(Inherited from CompositionObject)
StartAnimation(String, CompositionAnimation)

Connects an animation with the specified property of the object and starts the animation.

Equivalent WinUI method: Microsoft.UI.Composition.CompositionObject.StartAnimation.

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

Equivalent WinUI method: Microsoft.UI.Composition.CompositionObject.StartAnimationGroup.

(Inherited from CompositionObject)
StopAnimation(String)

Disconnects an animation from the specified property and stops the animation.

Equivalent WinUI method: Microsoft.UI.Composition.CompositionObject.StopAnimation.

(Inherited from CompositionObject)
StopAnimationGroup(ICompositionAnimationBase)

Stops an animation group.

Equivalent WinUI method: Microsoft.UI.Composition.CompositionObject.StopAnimationGroup.

(Inherited from CompositionObject)
TryGetAnimationController(String)

Returns an AnimationController for the animation running on the specified property.

Equivalent WinUI method: Microsoft.UI.Composition.CompositionObject.TryGetAnimationController.

(Inherited from CompositionObject)
TryRedirectForManipulation(PointerPoint)

Indicates that configured manipulations for the given pointer stream should be sent to the InteractionTracker, not the app's UI thread, starting at the given PointerPoint.

TryRedirectForManipulation enables the VisualInteractionSource to redirect the Pointer stream to the InteractionTracker if the gesture matches the configuration on the VisualInteractionSource. This method should only be called with Pointer input of the DeviceType Touch.

Applies to

See also