MR.Gestures 5.0.0

.NET 8.0 
dotnet add package MR.Gestures --version 5.0.0
NuGet\Install-Package MR.Gestures -Version 5.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="MR.Gestures" Version="5.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add MR.Gestures --version 5.0.0
#r "nuget: MR.Gestures, 5.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
// Install MR.Gestures as a Cake Addin
#addin nuget:?package=MR.Gestures&version=5.0.0

// Install MR.Gestures as a Cake Tool
#tool nuget:?package=MR.Gestures&version=5.0.0

MR.Gestures

MR.Gestures adds events and Commands for handling touch and mouse gestures to all the .NET MAUI elements.

With version 5 and the end of support for Xamarin.Forms I released it as open source under the MIT license.

To get started you

  1. install the NuGet package to your MAUI project,
  2. initialize it with a call to ConfigureMRGestures() in your MauiProgram
  3. and then use the elements from MR.Gestures instead of Microsoft.Maui.Controls.

The official website with a more detailed description is at www.mrgestures.com.

The GestureSample app demos how all the elements are used and what you get in the EventArgs.

Architecture

If you want to develop MR.Gestures yourself or want to know, how everything works, then read on. The rest of this page describes how MR.Gestures works and what the most important classes are for.

Shared Elements

MR.Gestures adds various properties and events to each and every element. The proper way to do this would be to add them to some base class like Element. But as an external library I cannot do this. I also couldn't add attached properties because I needed to override some methods of the native controls. C# also cannot inherit from two base classes.

So I needed my own class which inherits from the respective MAUI class and adds all the properties and events which MR.Gesture needs - 18 events and 36 properties in every class.

Of course I did not want to add the functionality in every class. The functionality is in GestureHandler. All the controls hold an instance of that class and forward their calls to the GestureHandler.

But even defining and forwarding those 18 x (1 event + 2 properties) in each class is a lot of code. So I wrote a T4 template to do that. T4 could generate any kind of files long before source generators were introduced in Roslyn. Unfortunately it never got much love from Microsoft. There was no intellisense in VS, so writing them is a lot of trial-and-error.

At the time of this writing the T4 file Controls.tt is 186 lines long and generates Controls.cs with 29,894 lines.

Handlers

MAUI Handlers translate the shared MAUI element to the respective native user control. It's similar to the renderers in Xamarin.Forms. Again, this is much repetitive code and again it will be generated by T4 templates.

File Generates Description
Handlers.json defines all the data I need. It is a list of all handler names (some of which are used for multiple elements) and their respective native control on each platform. This file is read by all T4 templates in the Handlersfolder.
Handlers.tt Handlers.cs This contains the part of the handler which is the same on every platform. It maps the event and command property names to the method HandlerHelper.MapPropertyChanged.
Handlers.Android.tt Handlers.Android.cs The Android handlers are a bit complicated. To add my gesture handling, I need to override DispatchTouchEvent and DispatchGenericMotionEvent in every native view. Therefore I need to define such a native view for each element and use that instead of the MAUI view.
Handlers.iOS.tt Handlers.iOS.cs This is currently not used.
Handlers.Windows.tt Handlers.Windows.cs This is currently not used.

The other files in the Handlers folder are for cases where the MAUI team did not adhere to their own naming conventions or did not migrate the Xamarin.Forms renderers to MAUI handlers. In these cases the T4 templates could not be used.

Platform dependent code

The PlatformSpecific folder contains a folder for each platform and within those

  • PlatformSpecific/Android/AndroidGestureHandler.cs
  • PlatformSpecific/iOS/iOSGestureHandler.cs
  • PlatformSpecific/Windows/WinUIGestureHandler.cs

are the most important files.

They each define static methods

  • AddInstance
  • RemoveInstance
  • OnElementPropertyChanged

The static methods are called from the handlers. They create instances of the respective *GestureHandler classes which do everything they need to do to handle the touch gestures on the native platform.

Raising events

Each PlatformSpecific/platform folder has a subfolder EventArgs. These inherit from the respective shared EventArgs and define constructors which convert the data from the native gesture objects to MR.Gesture.*EventArgs.

E.g.


namespace MR.Gestures.Android.EventArgs;

public class AndroidPanEventArgs : MR.Gestures.PanEventArgs
{
    public AndroidPanEventArgs(MotionEvent previous, MotionEvent current, PanEventArgs prevArgs, global::Android.Views.View view)

When the AndroidGestureHandler or one of its helper classes recognizes a pan gesture, then it creates a new AndroidPanEventArgs and sends it to IGestureListener.

IGestureListener is implemented by multiple classes which use a Chain of Responsibility pattern.

Class Description
GestureThrottler Some gestures can be configured to only raise when a certain minimum value is reached. E.g. Settings.MinimumDeltaDistance defines a minimum distance. If the delta distance between two pan gestures is lower than this value, then the event will not be raised. If it is above, then the gesture will be forwarded to its inner IGestureListener.
GestureFilter This only looks at the elements InputTransparent property. Îf it is True, then no events are raised. If it is False, then the gesture will be forwarded to its inner IGestureListener.
GestureHandler This class finally calls the event handler and/or command in the respective element.
Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-android34.0 is compatible.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-ios17.2 is compatible.  net8.0-maccatalyst was computed.  net8.0-maccatalyst17.2 is compatible.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net8.0-windows10.0.19041 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (5)

Showing the top 5 NuGet packages that depend on MR.Gestures:

Package Downloads
DK.Controls

Extended and improved controls for Xamarin Forms
DK.Forms

Package Description
DK.Controls.Android

Android platform specific code
ItEnterprise.HubberStandard

ItEnterprise HubberStandard for Xamarin Forms
DK.AppFramework

Package Description

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
5.0.0 81 4/29/2024
4.0.1 1,902 1/19/2024
4.0.0 7,069 10/19/2023
3.0.0 23,423 7/20/2022
3.0.0-pre1 322 5/6/2022
2.2.1 12,749 3/14/2022
2.2.0 1,904 2/8/2022
2.1.3 175,922 6/25/2020
2.1.2 11,116 4/2/2020
2.1.1 19,739 11/19/2019
2.1.0 59,220 11/2/2018
2.0.0 14,674 7/26/2018
1.5.4 37,247 5/19/2018
1.5.3 13,999 2/8/2018
1.5.2 4,439 1/5/2018
1.5.0 17,487 10/27/2017
1.4.3-pre1 2,625 5/29/2017
1.4.2.2 26,711 6/29/2017
1.4.2 20,035 3/30/2017
1.4.1 22,202 12/14/2016
1.4.0 16,307 11/22/2016
1.3.5 20,276 7/12/2016
1.3.4 10,848 5/27/2016
1.3.3 7,850 5/7/2016
1.3.2 8,512 2/29/2016
1.3.1 2,863 12/14/2015
1.3.0 2,116 12/10/2015
1.3.0-pre1 1,584 11/26/2015
1.2.5 2,194 11/17/2015
1.2.4 2,294 10/7/2015
1.2.3 2,904 9/18/2015
1.2.2 2,450 8/30/2015
1.2.1 2,333 7/21/2015
1.2.0 2,551 7/17/2015
1.2.0-pre1 1,990 4/28/2015
1.1.0 2,697 4/8/2015
1.0.8 2,070 3/17/2015
1.0.7 1,735 3/13/2015
1.0.6 1,751 3/10/2015
1.0.6-pre1 1,625 3/5/2015
1.0.5 1,817 3/3/2015
1.0.5-pre1 1,838 2/28/2015
1.0.4 2,379 2/18/2015
1.0.4-pre4 1,737 2/16/2015
1.0.3 1,857 2/10/2015
1.0.2 1,916 2/9/2015
1.0.1 2,232 2/9/2015
1.0.0 2,238 2/9/2015

With MR.Gestures you can handle all the touch gestures in your MAUI apps. Version 5.0.0 makes it free of charge.