Installation

Include the package in your Portable Code.

Install-Package Xamarin.X247Grad.Animation -Version 1.0.0

Principle

The animation library provides animation definions that are playable on visual elements. These can be defined programatically, but are intended to be placed with the Page or App XAML.

An animation set defines the stops the animation will run through. An animation stop defines it's length and what properties will be set. Those properties are then interpolated by the library from the state they are in, either at the start of the animation or at their state after a previous animation stop.

Animation stops use Xamarin's own setters. That way, code completion may be used if the IDE supports it. As the animation set does not know the context of which type of visual element will be provided, bindable properties need to be prefixed by their type.

Usage

To use AnimationSets, AnimationSet and AnimationStop, include the namespace in your page.

<ContentPage
  xmlns:animation="clr-namespace:Xamarin.X247Grad.Animation;assembly=Xamarin.X247Grad.Animation">
</ContentPage>

You can then define the animation set as part of a resource dictionary. Animation sets define a default constructor, which allows you to give them a backing field by providing x:Name. Zero length animation stops will immediately set the values without interpolating. This can be used to initialize a state if the current value should not be used. To define an animation set, add a AnimationSet element.

<ResourceDictionary>
  <animation:AnimationSet x:Name="Animation" x:Key="Animation">
    <animation:AnimationStop Length="0">
      <Setter Property="Label.ScaleY">0</Setter>
    </animation:AnimationStop>
    <animation:AnimationStop Length="2000">
      <Setter Property="Label.ScaleY">1</Setter>
    </animation:AnimationStop>
  </animation:AnimationSet>
</ResourceDictionary>

The definition can then be played on any referable XAML element.

/// <summary>
/// Plays the animation defined in the XAML file at resource dictionary level.
/// </summary>
private async void PlayAnimation(object sender, EventArgs e) =>
  await Animation.Play(Label);

When using a resource dictionary, the animation should be retrieved accordingly.

For the full example see SimpleAnimation.xaml and SimpleAnimation.xaml.cs.

Attaching with behavior

An animation can also directly be attached to the target element. This uses a visual element's behaviors to determine the target and to co-locate the animation with the element.

To use the attached animation, include the behaviors namespace as well.

<ContentPage
  xmlns:animation="clr-namespace:Xamarin.X247Grad.Animation;assembly=Xamarin.X247Grad.Animation"
  xmlns:behaviors="clr-namespace:Xamarin.X247Grad.Animation.Behaviors;assembly=Xamarin.X247Grad.Animation">
</ContentPage>

To define the animation, add the AttachAnimation behavior to the element. The behavior also provides a default constructor and can be named for referral.

<Label Text="Hello, world!">
  <Label.Behaviors>
    <behaviors:AttachAnimation x:Name="AttachAnimation">
      <animation:AnimationSet>
        <animation:AnimationStop Length="0">
          <Setter Property="Label.ScaleY">0</Setter>
        </animation:AnimationStop>
        <animation:AnimationStop Length="2000">
          <Setter Property="Label.ScaleY">1</Setter>
        </animation:AnimationStop>
      </animation:AnimationSet>
    </behaviors:AttachAnimation>
  </Label.Behaviors>
</Label>

The attached animation can then be played without providing the visual element as follows.

/// <summary>
/// Plays the animation defined in the XAML file as a behavior.
/// </summary>
private async void PlayAnimation(object sender, EventArgs e) =>
  await AttachAnimation.Play();

For the full example see AttachedAnimation.xaml and AttachedAnimation.xaml.cs.

Parallel animations

Animations can be played in parallel on an element, making it easier to define multiple movements and changes without unwrapping all changes to their interpolated states. To do so, use the AnimationSets element and fill it with the animations that run in parallel.

<ResourceDictionary>
  <animation:AnimationSets x:Name="Animations" x:Key="Animations">
    <animation:AnimationSet>
      <animation:AnimationStop Length="0">
        <Setter Property="Label.TextColor">Black</Setter>
      </animation:AnimationStop>
      <animation:AnimationStop Length="1000" />
      <animation:AnimationStop Length="2000">
        <Setter Property="Label.TextColor">Red</Setter>
      </animation:AnimationStop>
    </animation:AnimationSet>

    <animation:AnimationSet>
      <animation:AnimationStop Length="0">
        <Setter Property="Label.TranslationX">-800</Setter>
      </animation:AnimationStop>
      <animation:AnimationStop Length="1750">
        <Setter Property="Label.TranslationX">0</Setter>
      </animation:AnimationStop>
    </animation:AnimationSet>
  </animation:AnimationSets>
</ResourceDictionary>

This animation can then be played the same way a single animation set would be played. For attached animations, both AnimationSet and AnimationSets can be used.

For the full example see ParallelAnimation.xaml and ParallelAnimation.xaml.cs.

Target names

The TargetName of a setter can be used to refer to elements under the visual element an animation is played on. In the context of the visual element, the appropriate visual element with the requested name is resolved, the setter is then interpolated on that element instead of the root element.