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

Overview

Xamarin.Forms did not handle touch gestures very well. They only had the TapGestureRecognizer in the beginning. This is not enough to write advanced mobile apps. .NET MAUI added some more gesture recognizers but they still don’t provide all information you need. Furthermore the API which they use (the GestureRecognizers collection) 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, 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 get all the information you need about the gesture.

You can work with the gestures completely from shared code. The platform specific code is all done in MR.Gestures.

Getting Started

Install MR.Gestures into your MAUI project(s) with NuGet and then add a call to ConfigureMRGestures in your MauiProgram.cs:

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

        return builder.Build();
    }

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

You can also clone the GestureSample app. 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.

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.

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

About MR.Gestures

MR.Gestures 5.0 is free and open source. The older versions were proprietary and you needed to buy a license. I’ll leave the old questions here for the time being and remove them in the future.

I currently do not plan to use MAUI myself. In the past couple of months the effort for MR.Gestures support was more than the benefit. MAUI changed how the native controls are created and disposed and they did not document that process. It is quite difficult to always find workarounds for their bugs. So I decided to be done with it.

If somebody sends a PR I’ll consider merging it, but I will not do any further development on MR.Gestures myself.

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.

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.

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 gestures do not work on cells on Windows.

Xamarins Windows renderers (WinUI, 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.

The following questions are related to the license in MR.Gestures versions older than 5.0.

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.

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.

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.