CommunityToolkit / CommunityToolkit/Maui
[Proposal] Add possibility to configure animation behavior TouchBehavior
- Dominant language
- C#
- Stars
- 2.7k
- Forks
- 500
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 7
Description
### Feature name
Implement `TouchBehavior.AnimationShouldFinish`
### Link to discussion
https://github.com/CommunityToolkit/Maui/issues/2063
### Progress tracker
- [ ] Android Implementation
- [ ] iOS Implementation
- [ ] MacCatalyst Implementation
- [ ] Windows Implementation
- [ ] Tizen Implementation
- [ ] Unit Tests
- [ ] Samples
- [ ] Documentation
### Summary
As reported by @albilaga in #2063: in some cases the animation of the `TouchBehavior` is prematurely ended and a `TaskCanceledException` is thrown. While initially reported as a bug, we as a team think this is by design, but we should consider adding an option to be able to influence this behavior to give the end-user full control over the desired behavior.
### Motivation
@albilaga in #2063:
> Touch behavior when set `DefaultAnimationDuration` and user just tap the element, it will just abort the animation and throw `TaskCanceledException` even though the animation is not finished. I am not sure if this is expected behavior. Because from user perspective if I just tap it, it should show and finish the animation within the duration of `DefaultAnimationDuration`. Here it is in current implementation even though I increase the `DefaultAnimationDuration` to be 500
https://github.com/user-attachments/assets/cd4f37a4-55b4-4515-a46b-4866f9de4077
@albilaga also kindly opened a [PR with a fix](https://github.com/CommunityToolkit/Maui/pull/2101), however, this would be a breaking change as it changes the current behavior of cancelling the animation as it was designed.
However, we can see that it is desirable for people to keep the animation going, even in this scenario. That would look like this:
https://github.com/user-attachments/assets/3553c111-770c-4681-8499-5e154c51a5ce
As discussed in the monthly .NET MAUI Community Toolkit [Standup of January 2025](https://www.youtube.com/live/Luj_Vm_KgSE?si=DKLx_WNJGYFUh0sJ&t=1064), we would like to add the option to make this behavior configurable.
### Detailed Design
`TouchBehavior` will gain an additional property, for now I came up with `AnimationShouldFinish`, an alternative could be `AnimationShouldAlwaysFinish` but that becomes a bit lengthy. I think `AnimationShouldFinish` with clear API documentation on it should be sufficient.
The change proposed by @albilaga gets us a long way there, but we need to take into account this new property to determine the desired behavior from the developer and act accordingly. For reference, this was the code that was proposed in the existing PR:
```csharp
// TODO: AnimationShouldFinish should probably be part of this condition
if (touchBehavior.DefaultAnimationDuration > 0 && touchStatus == TouchStatus.Completed)
{
await Task.Delay(touchBehavior.DefaultAnimationDuration, token);
}
else
{
await AbortAnimations(touchBehavior, token);
}
```
### Usage Syntax
```markdown
### XAML usage
### C# usage
var touchBehavior = new TouchBehavior
{
AnimationShouldFinish = true,
DefaultAnimationDuration = 500,
DefaultAnimationEasing = Easing.CubicInOut,
PressedOpacity = 0.8,
PressedScale = 0.9
};
// For this snippet layout is omitted
layout.Behaviors.Add(touchBehavior);
```
### Drawbacks
_No response_
### Alternatives
* Take the existing [proposed PR](https://github.com/CommunityToolkit/Maui/pull/2101) and consider it a breaking change without the possibility to revert back to the current behavior, so that doesn't seem like something we want to do
* Update the documentation as this being by design and leave it at that.
### Unresolved Questions
_No response_
Contributor guide
Research direction
Start with the TouchBehavior implementation and the Detailed Design in this issue, then review discussion #2063 and proposed PR #2101 for existing context. Check how animation cancellation currently works before assessing the Android, iOS, MacCatalyst, Windows, and Tizen requirements. Done means the configurable behavior is covered by unit tests, samples, and documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- desktop-dev, frontend, mobile-dev
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 40/100