TouchGestureRecognizer.md

TouchGestureRecognizer

Generic Touch Gesture Recognizer

Whenever a touch state changes this Gesture Recognizer will fire an Updated event. This allows for a raw feed of touch data that a user could essentially use for anything.

API

Supporting APIs

In order to provide the user with as much available information as possible, we are going to add additional information about all currently active touches.

GestureEventArgs

Additional Touch Data Attached to Updated events

TouchGestureRecognizer

public class TouchGestureRecognizer : GestureRecognizer
{
	public event EventHandler<TouchEventArgs> TouchUpdated;
	public IList<TouchPoint> TouchPoints {get; set;}
}

Properties

API	Description
TouchPoints	A list that provides the ability to articulate events and commands for each individual touch occurring against the given target.

Events

API	Description
TouchUpdated	Occurs whenever there is a change is state for anything touching the view.

TouchEventArgs

GestureEventArgs will contain whatever data is needed to interpret the event

public class TouchEventArgs : GestureEventArgs
{
}

TouchPoint

public sealed class TouchPoint
{
	public static readonly BindableProperty TouchIndexProperty;
	public int TouchIndex {get; set;}
	
	public static readonly BindableProperty IsTouchingProperty;
	public bool IsTouching {get; set;}
	
	// Bindable Property will live on GestureRecognizer
	public ICommand CancelledCommand { get; set; }
	public object CancelledCommandParameter { get; set; }
	
	// Bindable Property will live on GestureRecognizer
	public ICommand StartedCommand { get; set; }
	public object StartedCommandParameter { get; set; }
	
	public ICommand CompletedCommand { get; set; }
	public object CompleteCommandParameter { get; set; }	
	
	public event EventHandler<TouchPointEventArgs> TouchPointUpdated {get;}
}

API	Description
TouchIndex	First touch is index 0, second touch is index 1, etc. This indicates the touch index that updates and commands will listen to
IsTouching	If the defined Touch Index is currently in contact with target view
StartedCommand	When the touch first hits the screen
StartedCommandParameter
CompletedCommand	When the touch is lifted
CompletedCommandParameter
CancelledCommand	The touch is still on the screen but it's been cancelled and no longer reporting gesture changes
CancelledCommandParameter

Events

API	Description
TouchPointUpdated	Occurs whenever there is a change is state for any touch point currently interacting with the target view

TouchPointEventArgs

public class TouchPointEventArgs : GestureEventArgs
{
	public Touch TouchData {get;}
}

Examples

public class TouchContainer : ContentView
{
  public TouchContainer ()
  {
    var touchGesture = new TouchGestureRecognizer ();
    touchGesture.TouchUpdated += OnTouchUpdated;
    GestureRecognizers.Add (touchGesture);
  }

  void OnTouchUpdated (object sender, TouchUpdatedEventArgs e)
  {
    IReadOnlyList<Touch> data = e.TouchEvent.ChangedTouches;
    
    if(data.Any())
    {
    	if(data[0].StatusType == GestureStatus.Started)
	{
		//new touch on screen
	}
	else if(data[0].StatusType == GestureStatus.Running)
	{
		//new position data for touch
	}
	else if(data[0].StatusType == GestureStatus.Completed)
	{
		//touch has left the screen
	}
	else if(data[0].StatusType == GestureStatus.Canceled)
	{
		//touch is most likely still on the screen but something has cancelled this touch from being reported anymore
	}
    }
  }
}

This demonstrates listening to the TouchUpdated event and then where the user could provide behavior based on the changing states of the touch

---

<Image Source="TwoFingers.jpg">
    <Image.GestureRecognizers>
        <TouchGestureRecognizer>
		<TouchGestureRecognizer.TouchPoints>
			<TouchPoint TouchIndex="0" IsTouching="{Binding IsTouching}"/>
			<TouchPoint TouchIndex="1" 
				CompletedCommand="{OnSecondFingerUp}" 
				StartedCommand="{OnSecondFingerDown}"/>
		</TouchGestureRecognizer.TouchPoints>
	</TouchGestureRecognizer>
  </Image.GestureRecognizers>
</Image>

This demonstrates binding various Touch Points to a View Model

---

<Image Source="ThreeFingers.jpg">
    <Image.GestureRecognizers>
        <TouchGestureRecognizer>
		<TouchGestureRecognizer.TouchPoints>
			<TouchPoint TouchIndex="2" IsTouching="{Binding ThreeFingersTouching}"/>
		</TouchGestureRecognizer.TouchPoints>
	</TouchGestureRecognizer>
  </Image.GestureRecognizers>
</Image>

This demonstrates setting up an image that will only fire IsTouching when three fingers have made contact with the view