MR.Gestures
5.0.0
dotnet add package MR.Gestures --version 5.0.0
NuGet\Install-Package MR.Gestures -Version 5.0.0
<PackageReference Include="MR.Gestures" Version="5.0.0" />
paket add MR.Gestures --version 5.0.0
#r "nuget: MR.Gestures, 5.0.0"
// 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
- install the NuGet package to your MAUI project,
- initialize it with a call to
ConfigureMRGestures()
in yourMauiProgram
- and then use the elements from
MR.Gestures
instead ofMicrosoft.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 Handlers folder. |
|
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 | Versions 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. |
-
net8.0
- Microsoft.Maui.Controls (>= 8.0.7)
- Microsoft.Maui.Controls.Compatibility (>= 8.0.7)
-
net8.0-android34.0
- Microsoft.Maui.Controls (>= 8.0.7)
- Microsoft.Maui.Controls.Compatibility (>= 8.0.7)
-
net8.0-ios17.2
- Microsoft.Maui.Controls (>= 8.0.7)
- Microsoft.Maui.Controls.Compatibility (>= 8.0.7)
-
net8.0-maccatalyst17.2
- Microsoft.Maui.Controls (>= 8.0.7)
- Microsoft.Maui.Controls.Compatibility (>= 8.0.7)
-
net8.0-windows10.0.19041
- Microsoft.Maui.Controls (>= 8.0.7)
- Microsoft.Maui.Controls.Compatibility (>= 8.0.7)
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 | 7,649 | 4/29/2024 |
4.0.1 | 3,323 | 1/19/2024 |
4.0.0 | 8,217 | 10/19/2023 |
3.0.0 | 35,093 | 7/20/2022 |
3.0.0-pre1 | 372 | 5/6/2022 |
2.2.1 | 13,225 | 3/14/2022 |
2.2.0 | 2,038 | 2/8/2022 |
2.1.3 | 192,035 | 6/25/2020 |
2.1.2 | 11,267 | 4/2/2020 |
2.1.1 | 19,860 | 11/19/2019 |
2.1.0 | 59,508 | 11/2/2018 |
2.0.0 | 14,777 | 7/26/2018 |
1.5.4 | 37,950 | 5/19/2018 |
1.5.3 | 14,059 | 2/8/2018 |
1.5.2 | 4,476 | 1/5/2018 |
1.5.0 | 17,567 | 10/27/2017 |
1.4.3-pre1 | 2,664 | 5/29/2017 |
1.4.2.2 | 27,184 | 6/29/2017 |
1.4.2 | 20,390 | 3/30/2017 |
1.4.1 | 22,582 | 12/14/2016 |
1.4.0 | 16,750 | 11/22/2016 |
1.3.5 | 20,892 | 7/12/2016 |
1.3.4 | 11,166 | 5/27/2016 |
1.3.3 | 8,060 | 5/7/2016 |
1.3.2 | 8,719 | 2/29/2016 |
1.3.1 | 2,901 | 12/14/2015 |
1.3.0 | 2,158 | 12/10/2015 |
1.3.0-pre1 | 1,616 | 11/26/2015 |
1.2.5 | 2,232 | 11/17/2015 |
1.2.4 | 2,332 | 10/7/2015 |
1.2.3 | 2,947 | 9/18/2015 |
1.2.2 | 2,487 | 8/30/2015 |
1.2.1 | 2,375 | 7/21/2015 |
1.2.0 | 2,589 | 7/17/2015 |
1.2.0-pre1 | 2,023 | 4/28/2015 |
1.1.0 | 2,735 | 4/8/2015 |
1.0.8 | 2,105 | 3/17/2015 |
1.0.7 | 1,771 | 3/13/2015 |
1.0.6 | 1,785 | 3/10/2015 |
1.0.6-pre1 | 1,660 | 3/5/2015 |
1.0.5 | 1,852 | 3/3/2015 |
1.0.5-pre1 | 1,890 | 2/28/2015 |
1.0.4 | 2,418 | 2/18/2015 |
1.0.4-pre4 | 1,767 | 2/16/2015 |
1.0.3 | 1,903 | 2/10/2015 |
1.0.2 | 1,951 | 2/9/2015 |
1.0.1 | 2,286 | 2/9/2015 |
1.0.0 | 2,284 | 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.