MR.Gestures

http://www.mrgestures.com
Admin
MR.Gestures is a comprehensive gesture handling library for .NET MAUI and Xamarin.Forms that...
Tokens:7,779
Snippets:62
Trust Score:8.2
Update:6 months ago
Show doc for...
Tokens:
Raw
### Define LongPressed Event Handler

Source: http://www.mrgestures.com

Example of a code-behind method to handle the LongPressed event.

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

--------------------------------

### Configure MR.Gestures in MauiProgram.cs

Source: http://www.mrgestures.com

Initialize the library in the MAUI application builder.

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

        return builder.Build();
    }
```

--------------------------------

### MR.Gestures.Settings

Source: http://www.mrgestures.com

Global static settings for configuring gesture sensitivity and thresholds.

```APIDOC
## MR.Gestures.Settings

### Description
Static configuration properties that apply to all platforms for gesture detection.

### Properties
- **MsUntilTapped** (int) - Default: 250. Milliseconds to wait for a second tap to trigger DoubleTapped.
- **MinimumDeltaDistance** (int) - Default: 2. Minimum distance for Panning event.
- **MinimumDeltaScale** (double) - Default: 0.01. Minimum scale change for Pinching event.
- **MinimumDeltaAngle** (double) - Default: 0.5. Minimum angle change for Rotating event.
- **MinimumDistanceForScale** (double) - Default: 10.0. Minimum distance for DeltaScale calculation.
- **MinimumMouseDeltaDistance** (int) - Default: 2. Minimum distance for MouseMoved event.
```

--------------------------------

### Configure MR.Gestures in .NET MAUI

Source: http://www.mrgestures.com

Initialize MR.Gestures in your .NET MAUI application by calling ConfigureMRGestures in MauiProgram.cs. You can optionally pass your license key here.

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

    return builder.Build();
}
```

--------------------------------

### Bind Commands in Code

Source: http://www.mrgestures.com

Programmatically bind commands to gesture events.

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

--------------------------------

### Bind Commands in XAML

Source: http://www.mrgestures.com

Use MVVM commands to handle gestures directly in the ViewModel.

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

--------------------------------

### Configure App Name on WPF

Source: http://www.mrgestures.com

Set the application name on WPF by using the AssemblyTitle or AssemblyProduct attribute in the Properties/AssemblyInfo.cs file.

```csharp
[assembly: AssemblyTitle("<your app name>")]
```

--------------------------------

### Configure MR.Gestures License Key on UWP

Source: http://www.mrgestures.com

Set the MR.Gestures license key for Universal Windows Platform in App.xaml.cs within the OnLaunched method. Ensure MR.Gestures.ContentPage.Assembly is included in Forms.Init for .NET Native compilation.

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

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

--------------------------------

### Platform Specific Settings

Source: http://www.mrgestures.com

Platform-dependent configuration settings for gesture thresholds.

```APIDOC
## Platform Specific Settings

### MR.Gestures.Android.Settings
- **SwipeVelocityThreshold** (double) - Default: 0.1. Velocity threshold for Swipe (0.0 to 1.0).

### MR.Gestures.iOS.Settings
- **SwipeVelocityThreshold** (double) - Default: 800. Velocity threshold for Swipe.

### MR.Gestures.UWP.Settings
- **SwipeVelocityThreshold** (double) - Default: 1. Velocity threshold for Swipe in pixels/ms.

### MR.Gestures.WPF.Settings
- **SwipeVelocityThreshold** (double) - Default: 100. Velocity threshold for Swipe.
- **LongPressDuration** (int) - Default: 1000. Milliseconds for long press detection.
```

--------------------------------

### TapEventArgs

Source: http://www.mrgestures.com

EventArgs for Tapping, Tapped, and DoubleTapped gestures.

```APIDOC
## TapEventArgs

### Description
Raised by Tapping, Tapped and DoubleTapped gestures.

### Properties
- **NumberOfTaps** (int) - The number of taps in a short period of time (~250ms).
- **Cancelled** (bool) - Android and iOS sometimes cancel a touch gesture. In this case a *ed event is raised with `Cancelled` set to `true`.
- **Handled** (bool) - This flag is meant to be used for event bubbling, but it does not work yet.
- **NumberOfTouches** (int) - The number of fingers on the screen.
- **Sender** (IGestureAwareControl) - The element which raised this event.
- **Sources** (TouchSource[]) - Returns the type of the coordinate in the same position in `Touches`. This can be `Touchdisplay`, `LeftMouseButton`, `RightMouseButton`, `MiddleMouseButton`, `Touchpad`, `XButton1`, `XButton2`, `Pen`, `MousePointer` or `Unknown`.
- **Touches** (Point[]) - Returns the position of the fingers on the screen.
- **ViewPosition** (Rectangle) - The absolute position and size of the `Sender` on the screen (window on desktop).
```

--------------------------------

### Configure MR.Gestures License Key on WPF

Source: http://www.mrgestures.com

Set the MR.Gestures license key for WPF in MainWindow.xaml.cs within the MainWindow constructor. Ensure MR.Gestures.ContentPage.Assembly is included in Forms.Init.

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

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

--------------------------------

### Handle Gestures in Code

Source: http://www.mrgestures.com

Attach gesture events to elements using lambda expressions or method references.

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

```csharp
    box1.LongPressed += Red_LongPressed;
```

--------------------------------

### Configure MR.Gestures License Key on macOS

Source: http://www.mrgestures.com

Set the MR.Gestures license key for macOS in AppDelegate.cs within the DidFinishLaunching method.

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

--------------------------------

### Configure MR.Gestures License Key on iOS

Source: http://www.mrgestures.com

Set the MR.Gestures license key for iOS in AppDelegate.cs within the FinishedLaunching method.

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

--------------------------------

### PanEventArgs

Source: http://www.mrgestures.com

EventArgs for Panning and Panned gestures.

```APIDOC
## PanEventArgs

### Description
Raised by Panning and Panned gestures.

### Properties
- **DeltaDistance** (Point) - The distance in X/Y that the finger was moved since this event was raised the last time.
- **TotalDistance** (Point) - The distance in X/Y that the finger was moved since the pan gesture began.
- **Velocity** (Point) - The velocity of the finger in X/Y.
- **Cancelled** (bool) - Android and iOS sometimes cancel a touch gesture. In this case a *ed event is raised with `Cancelled` set to `true`.
- **Handled** (bool) - This flag is meant to be used for event bubbling, but it does not work yet.
- **NumberOfTouches** (int) - The number of fingers on the screen.
- **Sender** (IGestureAwareControl) - The element which raised this event.
- **Sources** (TouchSource[]) - Returns the type of the coordinate in the same position in `Touches`. This can be `Touchdisplay`, `LeftMouseButton`, `RightMouseButton`, `MiddleMouseButton`, `Touchpad`, `XButton1`, `XButton2`, `Pen`, `MousePointer` or `Unknown`.
- **Touches** (Point[]) - Returns the position of the fingers on the screen.
- **ViewPosition** (Rectangle) - The absolute position and size of the `Sender` on the screen (window on desktop).
```

--------------------------------

### MR.Gestures.MacOS.Settings Properties

Source: http://www.mrgestures.com

Configuration properties for gesture recognition on macOS.

```APIDOC
## MR.Gestures.MacOS.Settings

### Description
Settings for MR.Gestures on macOS.

### Properties

#### SwipeVelocityThreshold
- **Type**: Number
- **Default**: 200
- **Description**: The velocity (NSPanGestureRecognizer.VelocityInView) of a lifted finger in X or Y direction must be at least this value to count as Swipe. Set it to a higher value if you want the user to move faster.

#### TrackpadCoordinateRatio
- **Type**: Number
- **Default**: 5
- **Description**: The Touches coordinates are usually only in the range 0 to device size. These values are quite small if you want to pan something around the whole screen. With TrackpadCoordinateRatio you can get bigger values for the Touches coordinates. Set it to a higher value to get bigger values for Touches.

### 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.  
```

--------------------------------

### PinchEventArgs

Source: http://www.mrgestures.com

Properties for Pinching and Pinched events.

```APIDOC
## PinchEventArgs

### Description
Contains data for Pinching and Pinched events, tracking finger distance and scaling.

### Properties
- **Center** (Point) - The center of the fingers on the screen.
- **DeltaScale** (double) - The relative distance between the two fingers compared to the last event.
- **DeltaScaleX** (double) - The relative horizontal distance compared to the last event.
- **DeltaScaleY** (double) - The relative vertical distance compared to the last event.
- **Distance** (double) - The distance between the first two fingers.
- **DistanceX** (double) - The horizontal distance between the first two fingers.
- **DistanceY** (double) - The vertical distance between the first two fingers.
- **TotalScale** (double) - The relative distance compared to when the gesture started.
- **TotalScaleX** (double) - The relative horizontal distance compared to when the gesture started.
- **TotalScaleY** (double) - The relative vertical distance compared to when the gesture started.
- **Cancelled** (bool) - Indicates if the gesture was cancelled.
- **Handled** (bool) - Flag for event bubbling.
- **NumberOfTouches** (int) - The number of fingers on the screen.
- **Sender** (IGestureAwareControl) - The element which raised this event.
- **Sources** (TouchSource[]) - The type of the coordinate (e.g., Touchdisplay, MousePointer).
- **Touches** (Point[]) - The position of the fingers on the screen.
- **ViewPosition** (Rectangle) - The absolute position and size of the sender.
```

--------------------------------

### LongPressEventArgs

Source: http://www.mrgestures.com

EventArgs for LongPressing and LongPressed gestures.

```APIDOC
## LongPressEventArgs

### Description
Raised by LongPressing and LongPressed gestures.

### Properties
- **Duration** (long) - Duration of long press in milliseconds.
- **NumberOfTaps** (int) - The number of taps in a short period of time (~250ms).
- **Cancelled** (bool) - Android and iOS sometimes cancel a touch gesture. In this case a *ed event is raised with `Cancelled` set to `true`.
- **Handled** (bool) - This flag is meant to be used for event bubbling, but it does not work yet.
- **NumberOfTouches** (int) - The number of fingers on the screen.
- **Sender** (IGestureAwareControl) - The element which raised this event.
- **Sources** (TouchSource[]) - Returns the type of the coordinate in the same position in `Touches`. This can be `Touchdisplay`, `LeftMouseButton`, `RightMouseButton`, `MiddleMouseButton`, `Touchpad`, `XButton1`, `XButton2`, `Pen`, `MousePointer` or `Unknown`.
- **Touches** (Point[]) - Returns the position of the fingers on the screen.
- **ViewPosition** (Rectangle) - The absolute position and size of the `Sender` on the screen (window on desktop).
```

--------------------------------

### Configure MR.Gestures License Key on Android

Source: http://www.mrgestures.com

Set the MR.Gestures license key for Android in MainActivity.cs within the OnCreate method, after calling Xamarin.Forms.Forms.Init().

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

--------------------------------

### SwipeEventArgs

Source: http://www.mrgestures.com

EventArgs for Swiped gestures.

```APIDOC
## SwipeEventArgs

### Description
Raised by Swiped gestures.

### Properties
- **Direction** (Direction) - The direction in which the finger moved when it was lifted from the screen. This is one of `Left`, `Right`, `Up`, `Down` or `NotClear`.
- **DeltaDistance** (Point) - The distance in X/Y that the finger was moved since the last `Panning` event.
- **TotalDistance** (Point) - The distance in X/Y that the finger was moved since the pan gesture began.
```

--------------------------------

### DownUpEventArgs

Source: http://www.mrgestures.com

EventArgs for Down and Up gestures.

```APIDOC
## DownUpEventArgs

### Description
Raised by Down and Up gestures.

### Properties
- **TriggeringTouches** (int[]) - The indexes of the fingers which were lowered/raised. Their locations are in `Touches`.
- **Cancelled** (bool) - Android and iOS sometimes cancel a touch gesture. In this case a *ed event is raised with `Cancelled` set to `true`.
- **Handled** (bool) - This flag is meant to be used for event bubbling, but it does not work yet.
- **NumberOfTouches** (int) - The number of fingers on the screen.
- **Sender** (IGestureAwareControl) - The element which raised this event.
- **Sources** (TouchSource[]) - Returns the type of the coordinate in the same position in `Touches`. This can be `Touchdisplay`, `LeftMouseButton`, `RightMouseButton`, `MiddleMouseButton`, `Touchpad`, `XButton1`, `XButton2`, `Pen`, `MousePointer` or `Unknown`.
- **Touches** (Point[]) - Returns the position of the fingers relative to `ViewPosition` (and in `Up` the last position before they were lifted).
- **ViewPosition** (Rectangle) - The absolute position and size of the `Sender` on the screen (window on desktop).
```

--------------------------------

### MouseEventArgs

Source: http://www.mrgestures.com

Properties for MouseEntered, MouseMoved, and MouseExited events.

```APIDOC
## MouseEventArgs

### Description
Contains data for mouse-related events, tracking movement and velocity.

### Properties
- **DeltaDistance** (Point) - The distance in X/Y moved since the last event.
- **TotalDistance** (Point) - The distance in X/Y moved since entering the view area.
- **Velocity** (Point) - The velocity of the mouse in X/Y.
- **Cancelled** (bool) - True if the mouse pointer is removed (e.g., iOS battery saving).
- **Handled** (bool) - Flag for event bubbling.
- **NumberOfTouches** (int) - Always 1 for mouse pointers.
```

--------------------------------

### MR.Gestures Event Handling

Source: http://www.mrgestures.com

This section details the events available in MR.Gestures for detecting user interactions. Events ending in '-ing' indicate a gesture is in progress, while events ending in '-ed' signify a completed gesture.

```APIDOC
## MR.Gestures Events

MR.Gestures allows you to handle eighteen different events to detect user interactions.

### Event Table

| Event | Description |
|---|---|
| Down | One or more fingers came down onto the touch screen. |
| Up | One or more fingers were lifted from the screen. |
| Tapping | A finger came down and up again, but it is not sure yet if this may become a multi-tap. |
| Tapped | There was no second tap within 250ms, so this was a single tap gesture. |
| DoubleTapped | There have been two Tapping events within 250ms and no more came. |
| LongPressing | A finger came down on the screen and did not move. The finger is still down. |
| LongPressed | The finger was released and the gesture is finished. |
| Panning | A finger came down and is moving on the screen. This is also called a dragging gesture. |
| Panned | The finger left the screen while it was moved slowly or not at all. |
| Swiped | The finger left the screen while it was moved fast. On Android and Windows Phone this is also called a flick. |
| Pinching | Two fingers hit the screen and are moving towards or away from each other. |
| Pinched | The fingers left the screen. |
| Rotating | Two fingers hit the screen and are rotating on the screen. |
| Rotated | The fingers left the screen. |
| MouseEntered | The mouse pointer entered the area over the view. |
| MouseMoved | The mouse pointer moved over the view. |
| MouseExited | The mouse pointer was moved away from the view. |
| ScrollWheelChanged | The scroll wheel was used while the mouse was over the views area. |

### Event Timing

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

--------------------------------

### Handling Panning with a Container Element

Source: http://www.mrgestures.com

When manipulating translation or scale properties during a gesture, listen to events on a container element and modify child properties to avoid gesture calculation issues.

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

--------------------------------

### RotateEventArgs

Source: http://www.mrgestures.com

Properties for Rotating and Rotated events.

```APIDOC
## RotateEventArgs

### Description
Contains data for Rotating and Rotated events, tracking rotation angles.

### Properties
- **Angle** (double) - The current angle of the line between the first and second finger.
- **Center** (Point) - The center of the fingers on the screen.
- **DeltaAngle** (double) - The angle rotated compared to the last event.
- **TotalAngle** (double) - The angle rotated compared to the start of the gesture.
- **Cancelled** (bool) - Indicates if the gesture was cancelled.
- **Handled** (bool) - Flag for event bubbling.
- **NumberOfTouches** (int) - The number of fingers on the screen.
- **Sender** (IGestureAwareControl) - The element which raised this event.
- **Sources** (TouchSource[]) - The type of the coordinate.
- **Touches** (Point[]) - The position of the fingers on the screen.
- **ViewPosition** (Rectangle) - The absolute position and size of the sender.
```

--------------------------------

### Incorrect Panning Handling

Source: http://www.mrgestures.com

Directly applying panning gestures to an element while manipulating its translation properties can lead to incorrect gesture calculations.

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

--------------------------------

### ScrollWheelEventArgs

Source: http://www.mrgestures.com

Details the properties available when a ScrollWheelChanged event is raised.

```APIDOC
## ScrollWheelEventArgs

### Description
Provides data for the ScrollWheelChanged event, including scroll delta and touch information.

### Properties
- **ScrollDelta** (Point) - Determines the direction in which the mouse wheel has been moved.
- **Cancelled** (bool) - Indicates if the event can be cancelled (always false).
- **Handled** (bool) - Flag for event bubbling.
- **NumberOfTouches** (int) - Always 1 for mouse pointers.
- **Sender** (IGestureAwareControl) - The element which raised this event.
- **Sources** (TouchSource[]) - Returns MousePointer.
- **Touches** (Point[]) - Position of the mouse pointer in the window.
- **ViewPosition** (Rectangle) - Absolute position and size of the Sender on the screen.
```
Tokens:
Raw