MR.Gestures Handle all the touch gestures in your .NET MAUI and Xamarin.Forms apps

Overview

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

.NET MAUI tries to position itself to be not only for mobile platforms, but also for Windows and macOS desktop. For the desktop you also need to know where the mouse pointer is - but they don’t have any mouse gesture support.

MR.Gestures tries to close that gap.

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

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

You can work with the gestures completely from the shared 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

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

If you don’t want to buy a license yet, you can try without setting a LicenseKey. Some gestures are also raised without license, but the EventArgs will be empty.

You could also rename your app to GestureSample and use the LicenseKey from that app.

Code Samples

All the elements which are usually in the Microsoft.Maui.Controls or 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 MAUI or Xamarin.Forms 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 MAUI/Xamarin.Forms
3. Add the handlers for the gestures you want to listen to

Here on LongPressed the method Red_LongPressed will 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

If you use MVVM then you probably have most of your logic in your ViewModels and you don’t want to use event handlers in your views. Of course this is also possible. There are commands for every event and you can bind them to the respective properties in the VM.

    <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.
• If you migrate your app from Xamarin.Forms to .NET MAUI and the app name stays the same, you can reuse your old license key.

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 eighteen 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 nine 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

.NET MAUI

Some elements need to listen to some gestures themselves to work properly. Depending on the exact implementation by Microsoft 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.

.NET MAUI itself still has many bugs. I found some problems in the GestureSample, but I did not check for each one, if they are caused by me or MAUI. All events are raised on all platforms, but I didn't check all the details like if the EventArgs values are correct, all events are raised on all controls and if any functionality is missing.

Xamarin.Forms

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, Swiped, MouseEntered, MouseMoved, MouseExited and ScrollWheelChanged 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 usual coordinate system in MacOS. They have 0/0 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 VisualElement.TranslationY and other Y coordinates.
This also means that angles are counter clock wise instead of clock wise on the other platforms.
There's also a bug in Xamarin.Forms.MacOS. Their ScrollViewRenderer doesn't have a virtual method OnElementChanged to override. Therefore I cannot hook into that elements' touch handlers. I submitted a PR to Xamarin in October 2017 and they merged it, but somehow it got removed again.

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
FlexLayout
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?

In .NET MAUI you add a call to ConfigureMRGestures in your MauiProgram.cs:

    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureMRGestures("your license key");

        return builder.Build();
    }

You can try MR.Gestures without license key. Then you just don’t pass anything to the ConfigureMRGestures method. But you still need to call the method to initialize the handlers.

In Xamarin.Forms you need to set the LicenseKey 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:

    Xamarin.Forms.Forms.Init(e, new[] { typeof(MR.Gestures.ContentPage).Assembly });

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

WPF

Here the call to Forms.Init is in the MainWindow constructor in MainWindow.xaml.cs.
Again you should pass the MR.Gestures assembly to Forms.Init:

    Xamarin.Forms.Forms.Init(e, new[] { typeof(MR.Gestures.ContentPage).Assembly });

    MR.Gestures.WPF.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

Microsoft likes to change where to find the app name for iOS. They move it every couple of versions. So the safest way is to edit the info.plist directly.

In the very beginning of XF (2014) they used to write it to CFBundleDisplayName. By the end of 2015 they changed it to CFBundleName. I tried to keep up by reading both values, using CFBundleName if it is configured, otherwise CFBundleDisplayName. But in 2021 they suddenly return the Assembly name when no CFBundleName is configured, so this stopped working.

So please write the app name to both CFBundleName AND CFBundleDisplayName in the info.plist.

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

WPF

The app name is configured in the Properties / AssemblyInfo.cs file. You can use either the AssemblyTitle or AssemblyProduct attribute. If the former is set, the latter will be ignored.

[assembly: AssemblyTitle("<your app 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. The NuGet package MR.Gestures is for both .NET MAUI and Xamarin.Forms.

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 MAUI / Xamarin.Forms.

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 mouse events don’t work on my iPhone

The iPhone doesn’t support mice. You need an iPad with iPadOS 13.0 or later. I use UIHoverGestureRecognizer internally and that was only added in iOS 13.0.

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 Xamarin forum.

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.

Imprint

Michael Rumpler
Trauttmansdorffstrasse 15
A-2544 Leobersdorf
Austria

VAT ID: ATU55244603