[Proposal] Compound Animations

[bijington]

Compound Animations

• Proposed
• Prototype: Not Started
• Implementation: Not Started
  • iOS Support
  • Android Support
  • macOS Support
  • Windows Support
• Unit Tests: Not Started
• Sample: Not Started
• Documentation: Not Started

Summary

A comprehensive set of complex animations based on https://animate.style

Motivation

To provide a feature rich set of animations that users can just use.

Detailed Design

The implementation will extend the existing AnimationBehavior and AnimationBase functionality in order to reduce any additional API footprint increase.

CompoundAnimationBase.shared.cs

public abstract class CompoundAnimationBase : AnimationBase
{
  public static readonly BindableProperty IsRepeatedProperty;

  public bool IsRepeated { get; set; }

  // Extension from AnimationBase
  public override Task Animate(View? view);

  public Task Animate(CancellationToken? cancellationToken, params View[]? views);

  protected abstract Animation CreateAnimation(params View[] views);
}

RubberBandAnimation.shared.cs

public class RubberBandAnimation : CompoundAnimationBase
{
  protected override Animation CreateAnimation(params View[] views);
}

TadaAnimation.shared.cs

public class TadaAnimation : CompoundAnimationBase
{
  protected override Animation CreateAnimation(params View[] views);
}

Usage Syntax

XAML Usage

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:xct="http://xamarin.com/schemas/2020/toolkit"
             x:Class="MyLittleApp.MainPage">

  <Label>
    <Label.Behaviors>
      <xct:AnimationBehavior EventName="Clicked">
        <xct:AnimationBehavior.AnimationType>
          <xct:RubberBandAnimation
            Easing="{x:Static Easing.Linear}"
            Duration="100" 
            IsRepeating="{Binding IsBusy}"
          />
        </xct:AnimationBehavior.AnimationType>
      </xct:AnimationBehavior>
    </Label.Behaviors>
  </Label>

</ContentPage>

C# Usage

var cancelAnimationTokenSource = new CancellationTokenSource();

var animation = RubberBandAnimation
{
    Easing = Easing.Linear,
    Duration = 100
};

await animation.Animate(cancelAnimationTokenSource.Token, myView, myView2);

Drawbacks

Alternatives

Unresolved Questions

I have left this only covering publicly exposed parts of the toolkit. Is this fine?

Dependent on #35

[TheCodeTraveler]

What are your thoughts on creating a new folder + namespace for animations? E.g. Something like this:

namespace CommunityToolkit.Maui.Animations;

In Xamarin.CommunityToolkit, all of the animation classes like CompoundAnimationBase.shared.cs, AnimationBase.shared.cs, RotateAnimation.shared.cs, etc., are in the Xamarin.CommunityToolkit.Behaviors namespace which is a bit strange. I think they ended up there because they are commonly used by the AnimationBehavior, but that Behavior is not required in order to use them, as demonstrated in the C# Usage example.

[bijington]

@brminnick I really like that separation! As you have pointed out we don't need the behavior in order to use the animations. It would also reduce the noise if someone is looking for a behavior as it wouldn't include all the animations which aren't actual behaviors.

I guess the only slight annoyance in the XAML side would be that one would have to declare 2 namespaces in order to use the AnimationBehavior and the inner Animation.

[TheCodeTraveler]

FYI - BaseAnimation is added in the Animation Behaviors PR: #185

[bijington]

Based on the discussion #203 we also discussed the idea of being able to compound existing animations together. Nothing has been fleshed out but it would be worth investigating whether we could provide the ability to combine the new XColorTo animations and potentially others in to this mechanism.

I think it would be nice to avoid having to write something like this:

var label = new Label();
await Task.WhenAll(
    label.TextColorTo(Colors.Red, 16, 1500, Easing.SinIn),
    label.BackgroundColorTo(Colors.Orange, 16, 1000, Easing.SpringIn));

And instead being able to combine the 2 together and commit as a single animation.