Skip to content

Commit ff3fe29

Browse files
davidortinaudavidortinau
authored
[NET10] Deprecate ClickGestureRecognizer (#2985)
* docs(gestures): .NET 10 migration note — deprecate ClickGestureRecognizer; promote Tap/Pointer; update ms.date; add repo copilot-instructions * docs(gestures): fix moniker closing tags to '::: moniker-end' in tap.md
1 parent 720651f commit ff3fe29

File tree

2 files changed

+121
-2
lines changed

2 files changed

+121
-2
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Working notes for .NET MAUI .NET 10 docs updates
2+
3+
These notes capture our lightweight process and guardrails while submitting focused pull requests against `main` for .NET 10 changes.
4+
5+
Last updated: 2025-08-18
6+
7+
## Branching and PRs
8+
9+
- Create small, topic-focused branches directly off `main` (for example: `pr01-pop-ups-async-from-main`, `pr02-mediapicker-multiselect-from-main`, `pr03-gestures-tap-click-deprecation`).
10+
- Open PRs directly to `main` with clear scope and migration context. Avoid staging branches.
11+
- Keep changes minimal: only the pages/includes required for the topic.
12+
13+
## Monikers and versioning
14+
15+
- Preserve existing content for <= .NET 9 and add >= .NET 10 content using DocFX monikers:
16+
17+
```md
18+
::: moniker range="<=net-maui-9.0"
19+
... existing <= 9 content ...
20+
::: moniker-end
21+
22+
::: moniker range=">=net-maui-10.0"
23+
... new .NET 10 content ...
24+
::: moniker-end
25+
```
26+
27+
- Use includes when appropriate to keep duplication low, but don’t over-abstract if a single page change is small and clear.
28+
29+
## Preview drift and verification
30+
31+
Changes must be verified against the .NET MAUI source for .NET 10 to avoid preview drift:
32+
33+
1. Check APIs on the `dotnet/maui` `net10.0` branch.
34+
- Repository: https://github.com/dotnet/maui
35+
- Browse `src/Controls/src/Core` and handlers/platform folders as needed.
36+
2. Cross-check against API docs/xrefs where available.
37+
3. Confirm platform notes (Android/iOS/Mac Catalyst/Windows) reflect real behavior.
38+
39+
Examples already verified:
40+
41+
- Pop-ups (.NET 10): `DisplayAlertAsync`, `DisplayActionSheetAsync` replace non-`Async` APIs.
42+
- Media picker (.NET 10): `PickPhotosAsync` / `PickVideosAsync` returning `List<FileResult>`; options like `SelectionLimit`, `MaximumWidth/Height`, `CompressionQuality`, etc.
43+
44+
## Quality gates before submitting a PR
45+
46+
- Lint the markdown visually in the diff for:
47+
- Valid xrefs and relative links.
48+
- Correct admonitions and moniker blocks are balanced.
49+
- Code fences have a language hint and compile logically.
50+
- Keep `ms.date` current on pages you materially change.
51+
- Make sure headings form a sensible outline and anchors aren’t unintentionally renamed.
52+
53+
## PR description checklist
54+
55+
- Summarize the .NET 10 change and motivation.
56+
- Call out migration guidance and any breaking changes.
57+
- List files changed and a quick test of samples where relevant.
58+
- Note platform-specific behaviors/limitations.
59+
- Link to upstream MAUI PRs or source lines used for verification when helpful.
60+
61+
## Known .NET 10 changes we’ve documented
62+
63+
- Pop-ups: `DisplayAlertAsync` / `DisplayActionSheetAsync` (PR01).
64+
- Media picker: multi-select `PickPhotosAsync` / `PickVideosAsync` (PR02).
65+
- Gestures: deprecate `ClickGestureRecognizer`; promote `TapGestureRecognizer` and `PointerGestureRecognizer` (PR03).

‎docs/fundamentals/gestures/tap.md‎

Lines changed: 56 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,19 @@
11
---
22
title: "Recognize a tap gesture"
33
description: "This article explains how to recognize a tap gesture in a .NET MAUI app."
4-
ms.date: 10/03/2022
4+
ms.date: 08/18/2025
55
---
66

77
# Recognize a tap gesture
88

9-
A .NET Multi-platform App UI (.NET MAUI) tap gesture recognizer is used for tap detection and is implemented with the <xref:Microsoft.Maui.Controls.TapGestureRecognizer> class. This class defines the following properties:
9+
A .NET Multi-platform App UI (.NET MAUI) tap gesture recognizer is used for tap detection and is implemented with the <xref:Microsoft.Maui.Controls.TapGestureRecognizer> class.
10+
11+
::: moniker range=">=net-maui-10.0"
12+
> [!IMPORTANT]
13+
> In .NET 10, <xref:Microsoft.Maui.Controls.ClickGestureRecognizer> is deprecated. Use <xref:Microsoft.Maui.Controls.TapGestureRecognizer> for tap/click interactions, and <xref:Microsoft.Maui.Controls.PointerGestureRecognizer> for pointer hover/move/press scenarios. The <xref:Microsoft.Maui.Controls.TapGestureRecognizer> supports primary and secondary buttons via the <xref:Microsoft.Maui.Controls.TapGestureRecognizer.Buttons> property and can be used to handle single and double tap gestures.
14+
::: moniker-end
15+
16+
This class defines the following properties:
1017

1118
- <xref:Microsoft.Maui.Controls.TapGestureRecognizer.Buttons>, of type <xref:Microsoft.Maui.Controls.ButtonsMask>, which defines whether the primary or secondary mouse button, or both, triggers the gesture on Android, Mac Catalyst, and Windows. For more information, see [Define the button masks](#define-the-button-mask).
1219
- <xref:Microsoft.Maui.Controls.TapGestureRecognizer.Command>, of type <xref:System.Windows.Input.ICommand>, which is executed when a tap is recognized.
@@ -56,6 +63,53 @@ image.GestureRecognizers.Add(tapGestureRecognizer);
5663

5764
By default the <xref:Microsoft.Maui.Controls.Image> will respond to single taps. When the <xref:Microsoft.Maui.Controls.TapGestureRecognizer.NumberOfTapsRequired> property is set to greater than one, the event handler will only be executed if the taps occur within a set period of time. If the second (or subsequent) taps don't occur within that period, they're effectively ignored.
5865

66+
::: moniker range=">=net-maui-10.0"
67+
68+
## Migrate from ClickGestureRecognizer (>= .NET 10)
69+
70+
In previous versions, mouse click interactions could be handled with <xref:Microsoft.Maui.Controls.ClickGestureRecognizer>. In .NET 10, this recognizer is deprecated. Migrate to <xref:Microsoft.Maui.Controls.TapGestureRecognizer> for click/tap interactions, and use <xref:Microsoft.Maui.Controls.PointerGestureRecognizer> for pointer enter/exit/move/press/release scenarios.
71+
72+
The following example shows how to migrate from `ClickGestureRecognizer` to `TapGestureRecognizer` while maintaining support for primary/secondary buttons:
73+
74+
```xaml
75+
<!-- Before (.NET 9 and earlier) -->
76+
<Image Source="dotnet_bot.png">
77+
<Image.GestureRecognizers>
78+
<ClickGestureRecognizer Clicked="OnClicked"
79+
NumberOfClicksRequired="1"
80+
Buttons="Primary,Secondary" />
81+
</Image.GestureRecognizers>
82+
</Image>
83+
84+
<!-- After (.NET 10) -->
85+
<Image Source="dotnet_bot.png">
86+
<Image.GestureRecognizers>
87+
<TapGestureRecognizer Tapped="OnTapped"
88+
NumberOfTapsRequired="1"
89+
Buttons="Primary,Secondary" />
90+
</Image.GestureRecognizers>
91+
</Image>
92+
```
93+
94+
In code-behind, handle the <xref:Microsoft.Maui.Controls.TapGestureRecognizer.Tapped> event and inspect <xref:Microsoft.Maui.Controls.TappedEventArgs.Buttons> to distinguish the mouse button:
95+
96+
```csharp
97+
void OnTapped(object sender, TappedEventArgs e)
98+
{
99+
if (e.Buttons == ButtonsMask.Secondary)
100+
{
101+
// Handle secondary/right click
102+
}
103+
else
104+
{
105+
// Handle primary/left click
106+
}
107+
}
108+
```
109+
110+
If you need pointer hover or press/release details (without a completed tap), use <xref:Microsoft.Maui.Controls.PointerGestureRecognizer> and its events such as `PointerEntered`, `PointerMoved`, `PointerPressed`, and `PointerReleased`. For more information, see [Recognize a pointer gesture](pointer.md).
111+
::: moniker-end
112+
59113
## Define the button mask
60114

61115
A <xref:Microsoft.Maui.Controls.TapGestureRecognizer> object has a <xref:Microsoft.Maui.Controls.TapGestureRecognizer.Buttons> property, of type <xref:Microsoft.Maui.Controls.ButtonsMask>, that defines whether the primary or secondary mouse button, or both, triggers the gesture on Android, Mac Catalyst, and Windows. The <xref:Microsoft.Maui.Controls.ButtonsMask> enumeration defines the following members:

0 commit comments

Comments
 (0)