CommunityToolkit / CommunityToolkit/Maui

[Proposal] Add possibility to configure animation behavior TouchBehavior

Open
#2,433 1 comment 4 reactions 0 assignees View on GitHub
new proposal
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.