VisualInteractionSource Class

Definition

Namespace:

Windows.UI.Composition.Interactions

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.

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 : 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 Class VisualInteractionSource
Inherits CompositionObject
Implements ICompositionInteractionSource

Inheritance

Object Platform::Object IInspectable CompositionObject VisualInteractionSource

Attributes

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implements

ICompositionInteractionSource

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. (Inherited from CompositionObject)
Compositor	The Compositor used to create this CompositionObject. (Inherited from CompositionObject)
DeltaPosition	The amount of position change to be applied during the upcoming frame. Defaults to 0. Readable only via expression/animation.
DeltaScale	The amount of scale change to be applied during the upcoming frame. Multiplicative. Defaults to 1. Readable only via expression/animation.
Dispatcher	The dispatcher for the CompositionObject. (Inherited from CompositionObject)
DispatcherQueue	Gets the DispatcherQueue for the CompostionObject. (Inherited from CompositionObject)
ImplicitAnimations	The collection of implicit animations attached to this object. (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.
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.
ManipulationRedirectionMode	Indicates what input should be redirected to the InteractionTracker.
PointerWheelConfig	Gets the configuration for pointer wheel input.
Position	The total amount of position change since the start of the interaction. Defaults to 0. Readable only via expression/animation.
PositionVelocity	The instantaneous rate of change of position in the interaction, in pixels per second. Defaults to 0. Readble only via expression/animation.
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.
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 InteractionSourceModes 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.
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.
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 InteractionSourceModes 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.
Properties	The collection of properties associated with the CompositionObject. (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.
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.
ScaleSourceMode	Defines how interactions are processed for an VisualInteractionSource on the scale axis. There are 3 types of InteractionSourceModes to choose from: Interactions are Disabled , EnabledWithInertia and EnabledWithoutInertia . This property must be enabled to allow the VisualInteractionSource to send scale data to InteractionTracker.
ScaleVelocity	The instantaneous rate of change of scale in the interaction, in percent per second. Additive. Defaults to 0. Readble only via expression/animation.
Source	The visual that is used for hit-testing and defines the co-ordinate space for gesture recognition.

Methods

Close()	Closes the CompositionObject and releases system resources. (Inherited from CompositionObject)
ConfigureCenterPointXModifiers(IIterable<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.
ConfigureCenterPointYModifiers(IIterable<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.
ConfigureDeltaPositionXModifiers(IIterable<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.
ConfigureDeltaPositionYModifiers(IIterable<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.
ConfigureDeltaScaleModifiers(IIterable<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.
ConnectAnimation(String, CompositionAnimation)	Connects and animation. (Inherited from CompositionObject)
Create(Visual)	Creates an instance of VisualInteractionSource.
CreateFromIVisualElement(IVisualElement)	Creates an instance of VisualInteractionSource from an element that implements IVisualElement.
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. (Inherited from CompositionObject)
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)
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.

See also

• CompositionObject
• IClosable
• ICompositionInteractionSource