[Proposal] Add possibility to configure animation behavior TouchBehavior

[jfversluis]

Feature name

Implement TouchBehavior.AnimationShouldFinish

Link to discussion

#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

CleanShot.2024-07-26.at.15.49.25.mp4

@albilaga also kindly opened a PR with a fix, 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:

CleanShot.2024-07-26.at.15.54.48.mp4

As discussed in the monthly .NET MAUI Community Toolkit Standup of January 2025, 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:

// 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

### XAML usage


<mct:TouchBehavior
   AnimationShouldFinish="True"
   DefaultAnimationDuration="500"
   DefaultAnimationEasing="{x:Static Easing.CubicInOut}"
   PressedBackgroundColor="LightGray"
   PressedOpacity="0.8"
   PressedScale="0.9" />


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