MR.Gestures Handle all the touch gestures in your Xamarin.Forms mobile apps

Overview

Xamarin Forms is great if you want to develop apps for different mobile platforms. But when it comes to touch gestures, it is still very limited.
For more than a year they only had the TapGestureRecognizer. Although they did add some others lately, they still don’t provide all information which you need. Furthermore the API which they use has been copied from iOS and is not what a .NET developer would expect.

MR.Gestures tries to close that gap.

It adds Down, Up, Tapping, Tapped, DoubleTapped, LongPressing, LongPressed, Panning, Panned, Swiped, Pinching, Pinched, Rotating and Rotated events to each and every layout, cell and view and to the ContentPage. These events will be raised when the user performs the corresponding touch gesture on the element.

In the EventArgs passed to the handlers you can see exactly what happened.

You can work with the touch gestures completely from the .NET Standard / PCL project. The platform specific code is all done in MR.Gestures.

Getting Started

If you just want to see how it works, then download the free GestureSample app from GitHub. In this app you can see how all the elements use all events. You can change the code however you like, add break points and see what it does. You will find all the examples from here in the GestureSample and many more.

To add MR.Gestures to your own app just follow these simple steps:

• Install MR.Gestures with NuGet
• Obtain a license key
• Configure the license key(s) in each platform specific project

And now you can use the new elements from the namespace MR.Gestures.

Code Samples

All the elements which are usually in the Xamarin.Forms namespace can also be found in MR.Gestures. But those have additional event handlers and command properties.

Adding the event handlers works the same way as in standard Xamarin Forms or WPF controls in both XAML and code.

Event Handlers in XAML

To add the event handler in XAML you have to:

1. Add the namespace MR.Gestures from the dll
2. Use the element from that namespace instead of Xamarin.Forms
3. Add the handlers for the gestures you want to listen to

Here on LongPressed the method Red_LongPressed should be called. The method must be defined in the code behind file like this

    void Red_LongPressed(object sender, MR.Gestures.LongPressEventArgs e)
    {
        Console.WriteLine("BoxViewXaml.Red_LongPressed method called");
    }

Event Handlers in Code

Of course you can do the same in code. Either with a lambda expression

    var box1 = new MR.Gestures.BoxView { Color = Color.Red };
    box1.LongPressed += (s, e) => Console.WriteLine("Code: Red LongPressed");

or by assigning the method as a handler.

    box1.LongPressed += Red_LongPressed;

Commands in XAML

But IMHO if you really want to separate the view from any code, then the view should be in XAML. So instead of the event handlers you can also use commands in your view model and bind them to the respective properties.

    <mr:BoxView Color="Green"
        LongPressedCommand="{Binding LongPressedCommand}"
        LongPressedCommandParameter="Green" />

The properties for the commands are called like the events, just with Command appended. You can also define a parameter passed to the command with the *CommandParameter properties. If you suppress the CommandParameter, then the respective event args are passed to your command. In this case a MR.Gestures.LongPressEventArgs object.

For the Tapped, DoubleTapped and LongPressed events you may not need the event args and defining a CommandParameter could make sense. But for the more complicated events you will always need the event args or you won’t know what happened. E.g. it does not help to just know that an element has been swiped unless you also know in which direction. The Direction is contained in the SwipeEventArgs.

Commands in Code

You can bind the commands in code too.

    var box2 = new MR.Gestures.BoxView { Color = Color.Green };
    box2.SetBinding(MR.Gestures.BoxView.LongPressedCommandProperty, "LongPressedCommand");
    box2.LongPressedCommandParameter = "Green";

The syntax for binding in code is a bit complicated, therefore my favorite is using commands in XAML. You will also see this, when you look through the code in the GestureSample. Although there are samples in all these categories, most of them are written in XAML and bound to commands.

Buy

MR.Gestures is licensed per app name.

If your app has the same name on all platforms, you only need one license key. If you have hundreds of developers working on the same app, you only need one license key. If you have different versions of your app with different names (e.g. different languages, customized for different clients or free and pro), then you need a separate key for each version.

The license will be valid forever. You don’t need to refresh it every year.

The price for one license is EUR 40,00 (+VAT).

The payment process will be handled by MyCommerce. You will be forwarded to their site when you click the Buy button.

Please enter the EXACT name of your app.
This is NOT the bundle name. If you write it in lower case or append any whitespaces, it won’t work either. See the FAQs on how to configure it.

Once you purchased a license, instructions how to configure it will be displayed on the MyCommerce page. These instructions can also be found in the email they will send you and in the FAQs.

If you forget to configure the license key properly, then all the events will still be raised, but the properties of the EventArgs will be empty. That may be enough for the tap and long press events, but not for the more complicated ones.

Documentation

Events

You can handle fourteen different events with MR.Gestures.

The -ing event is raised when at least one finger is on the screen and a gesture is in progress. The -ed event is raised, when the gesture is finished and all fingers left the screen.

EventArgs

Your event handlers will receive one of seven different EventArgs objects with all the detailed information what happened.
Click on the class names to see all its properties.

Settings

You can configure the behavior of MR.Gestures with different static Settings classes.
Some of those settings are the same for all platforms. These can be found in MR.Gestures.Settings. Platform dependant settings are in MR.Gestures.platform.Settings.

Compatibility

Some elements need to listen to some touch gestures themselves to work properly. Depending on the exact implementation by Xamarin and the native platforms, these events may be consumed.
Some of the views are simply too small to be touched. Therefore the gestures are also not forwarded to us.

WPF:
When I tested the GestureSample with WPF the same happened again as on macOS; I found a bunch of very serious bugs. I filed them, they were acknowledged, but only one has been fixed yet.
The bug which you see at once in the GestureSample is #3271. The transformations from TranslationX/Y, Scale and Rotation are applied in the wrong order. So when you rotate an element by 90° and change TranslationX, then the element is moved vertically instead of horizontaly. Also when you set Scale to 2 and TranslationX to 100, it will be moved by 200. This bug has been fixed, but the fix has not been released yet. I don't know, which Xamarin.Forms version will include it.

MacOS:
Apple still has no multi touch displays for macOS, so I made the touch gestures on the Mac to work as I would expect them to. If you think anything is awkward or doesn't behave as you would expect, please let me know.
Down, Up, Tapping, Tapped, DoubleTapped, LongPressing, LongPressed, Panning, Panned and Swiped can be triggered with the mouse. For Pinching, Pinched, Rotating and Rotated you need a Trackpad and two or more fingers. Panning, Panned and Swiped can also be triggered with the Trackpad with two or more fingers.
As the Trackpad has coordinates of its own which are not related to the touched view at all, the Points in Touches work a bit different then on the other platforms / using the mouse. When I returned the coordinates of the Trackpad (which is recommended by Apple), the values were very small for Pan gestures. So I added MR.Gestures.MacOS.Settings.TrackpadCoordinateRatio and multiply all coordinates by that setting. The default is 5/5, but you can change it however you want to get bigger or smaller values for the Touches.
Apple also doesn't use the same coordinate system in MacOS as every other computer on earth. They have the 0/0 point at the LOWER left. So keep this in mind when you work with the view, touch or other coordinates. Most likely you'll have to do some different logic on the Mac than on the other platforms. Fortunately this is consistent with Xamarin.Forms.VisualElement.TranslationY and other Y coordinates.
This also means that angles are counter clock wise instead of clock wise on every other platform.
There's also a bug in Xamarin.Forms.MacOS. Their PageRenderer and ScrollViewRenderer don't have virtual methods OnElementChanged and OnElementPropertyChanged to override. Therefore I cannot hook into those elements' touch handlers. I submitted a PR to Xamarin in October 2017 and they merged it into master, but almost 10 months later it is still not included in XF 3.1.

Here are all the elements and how they work in detail on each platform. Hover over any yellow or red icons to see the details.

Element	iOS	Android	UWP	WPF	MacOS
ContentPage
AbsoluteLayout
ContentView
Frame
Grid
RelativeLayout
ScrollView
StackLayout
TabbedPage
ActivityIndicator
BoxView
Button
DatePicker
Editor
Entry
Image
ImageButton
Label
ListView
Picker
ProgressBar
SearchBar
Slider
Stepper
Switch
TableView
TimePicker
WebView
EntryCell
ImageCell
SwitchCell
TextCell
ViewCell

	All events are fully supported.
	Some events do not work fully. Hover for details.
	No events are raised. Hover for details.

Release Notes

FAQ

How do I configure my license key?

As your app name can be different on each platform, the license key must be configured in all platform specific projects. The best place for it is in each project between the calls to Xamarin.Forms.Forms.Init(...) and LoadApplication(new App()).

Android

In your Android project open MainActivity.cs and in the OnCreate method after the call to global::Xamarin.Forms.Forms.Init(...) add the following line:

    MR.Gestures.Android.Settings.LicenseKey = "<your license key>";

iOS

In the iOS project this has to be done in AppDelegate.cs, in the FinishedLaunching method. Add this line:

    MR.Gestures.iOS.Settings.LicenseKey = "<your license key>";

Universal Windows Platform

In UWP you add the code to the OnLaunched method in App.xaml.cs.
For the .NET Native compilation you also have to tell Xamarin.Forms which assemblies it should scan for custom controls and renderers. Therefore you also have to change the call to Forms.Init slightly:

    var otherAssemblies = new[] {
        typeof(MR.Gestures.ContentPage).GetTypeInfo().Assembly,
        typeof(MR.Gestures.UWP.Renderers.PageRenderer).GetTypeInfo().Assembly,      // only for MR.Gestures 1.*
    };
    Xamarin.Forms.Forms.Init(e, otherAssemblies);

    MR.Gestures.UWP.Settings.LicenseKey = "<your license key>";

MacOS

In the MacOS project, Forms.Init is called from AppDelegate.DidFinishLaunching and that’s also where you set the LicenseKey:

    MR.Gestures.MacOS.Settings.LicenseKey = "<your license key>";

How do I configure my app name?

The name of the app has to be configured differently on each platform.

Android

In the Android project open MainActivity.cs. The MainActivity class should have a Activity attribute. The Label parameter is the app name.

If you configured your activity manually in the Properties / AndroidManifest.xml file, then you need to change the android:label attribute there.

iOS

In Visual Studio open the iOS project properties and go to the “iOS Application” tab. There you’ll find the “Application name”. If you don’t have a “iOS application” tab, then open the info.plist. The app name is in the CFBundleDisplayName or CFBundleName setting (should be the same if both are present).

In Xamarin Studio the “Application name” is the very first textbox when you open the info.plist file.

Universal Windows Platform

Here you need to open the Package.appxmanifest file in your platform project. On the “Application” tab change the “Display Name” and on the “Packaging” tab the “Package display name”.

MacOS

In Visual Studio for Mac open the MacOS project options and go to General / Main Settings. You need to set the “Name”.

How do I install MR.Gestures?

You can install it with NuGet. In Visual Studio for Windows the easiest way is to right click your solution and choose “Manage NuGet Packages for Solution…”, then search for MR.Gestures and install it to all projects which use XF.

On the Mac you need to install the package for each project separately.

Is there a trial version available?

I already released the GestureSample app with complete source code on GitHub. That app shows how to use MR.Gestures with each and every available element.

If you want to try it in your own app or the final name of your app has not been decided yet, you can simply call your app GestureSample and use the LicenseKey from that app.

My event handler is called, but some event arg properties are not set.

You did not set the LicenseKey properly or it does not match your app name. Please check if you set the correct LicenseKey in all platform specific projects and that your app name matches the key.

The Tapped and DoubleTapped events are not raised

In MR.Gestures 1.* the LicenseKey needed to be set properly for these events to be raised. Without LicenseKey the NumberOfTaps is always 0. Tapped was only raised if NumberOfTaps was 1 and DoubleTapped only if it was 2.

With version 2.0 these events are also raised without LicenseKey (although NumberOfTaps is still 0).

What’s the license agreement of MR.Gestures?

MR.Gestures is a library to be included in others apps. So Yes, with the license I grant the right to use MR.Gestures in your own app, no matter if it’s commercial or free. I wrote MR.Gestures myself and I hold all rights on it. I do not grant the right to tamper with the library in any way, decompile or resell the whole or only parts of it.

MR.Gestures is licensed per app name. I.e. if your app has the same name on all platforms, you only need one license key. If you have different versions of your app with different names (e.g. different languages, customized for different clients/environments or free and pro), then you need a separate key for each version.

You can use it for as many developers on as many computers for as long as you like.

I want to swipe with two fingers. How can I handle that gesture?

The native standard gesture recognizers only work with the standard amount of fingers. I.e. two fingers for pinch and rotate and one for the others.

I managed to get some gestures on some platforms running with more fingers, but this is not consistent over all platforms.

In the future I may use a different API which is nearer to the wire. But this is a very big change so I’m not sure if I’ll do that yet.

I try to move/zoom/rotate an element, but it jumps on the screen.

The Touches coordinates in the EventArgs are always relative to the View which handles the event. If you manipulate the TranslationX, TranslationY, Scale or Rotation(X/Y) properties during a gesture, then the Touches and Delta* values cannot be calculated anymore.

So you always have to listen to the events of a container element and manipulate those properties of a child.

So instead of

    <mr:Image
        PanningCommand="{Binding PanningCommand}"
        TranslationX="{Binding TranslationX}"
        TranslationY="{Binding TranslationY}" />

you should write

    <mr:ContentView PanningCommand="{Binding PanningCommand}">
        <Image
            TranslationX="{Binding TranslationX}"
            TranslationY="{Binding TranslationY}" />
    </mr:ContentView>

Event Propagation (aka Event Bubbling)

If multiple elements are nested within each other and they all handle the same events, this is called event propagation. Ideally you should be able to tell, which element should handle the event. When I wrote MR.Gestures, I also wanted to implement this. This is why I added the Handled flag to the EventArgs.

Unfortunately I couldn’t get it working reliably on all platforms. Especially with some of the elements natively handling (and consuming) the events, this proved impossible to implement in a generic way.

Therefore I decided to strive for a solution where all MR.Gestures elements raise the respective events. This way you can decide yourself, which element should handle it. The easiest way is to start a Timer in one handler and do your work unless another handler will be called within a given timeframe.

The gestures do not work on cells on Windows.

Xamarins Windows renderers (UWP and WPF) for cells do not provide anything I can hook into to add my functionality. So I had to add that functionality to the renderers for MR.Gestures.ListView and MR.Gestures.TableView.

So if you want to listen to touch gestures on cells, the containing ListView or TableView must also be used from MR.Gestures even if you don’t add any gesture listeners on that element itself.

I get “Could not load file or assembly ‘MR.Gestures’” or “Could not load type MR.Gestures…”.

Please check your references. With version 2.0 all projects need a reference to MR.Gestures. In version 1.* the standard/portable project needs to reference MR.Gestures and the platform specific projects need references to both MR.Gestures and MR.Gestures.platform.

Every Xamarin.Forms developer should be familiar with the procedure of closing Visual Studio, deleting all bin and obj folders manually and then trying again. I have a .bat file which does that. Cleaning the solution within VS or just recompiling fails to delete old files most of the time.

Please also check, if you set your Settings.LicenseKey like it is described above. If this is not set, then the linker may strip it out of your executable.

What data do you have from me and what do you do with it?

I don’t collect any data from people who are not my customers. I also don’t send newsletters, so there’s no need to unsubscribe anything.

If you buy a MR.Gestures license, then my distributor will collect all data which they need to process the payment. Once the payment is done, I receive an email with your contacts (technical and payment), app name and issued license key. I do not receive your credit card number or any other sensitive information. I keep this data for future reference in case anybody needs support from me. Also if you send me any emails yourself, I will keep those emails for future reference. You can request the deletion of these emails, but if I can’t find your data, then you’re no customer of mine and I may be slower with support requests.

There is no cookie banner on this page, because it does not use any cookies at all.

Contact

My name is Michael Rumpler and I’m a freelance developer located in Austria. I started with C# in 2004. Although I also coded a lot in JavaScript, Java and some others, C# is my language of choice.

If you have any questions, suggestions, you find bugs or whatever, then please read this page again. If you can’t find anything about your problem here, than search in the thread in the Xamarin forum I linked below.

If you still can’t find anything, then you can contact me in various ways:

• open an issue in GestureSample/Issues. I use that for both the GestureSample itself and MR.Gestures.
• send an email to mrgestures@mrumpler.at
• or a tweet @MRGestures.
• post to the Xamarin Forum

Imprint

Michael Rumpler
Trauttmansdorffstrasse 15
A-2544 Leobersdorf
Austria

VAT ID: ATU55244603