Skip to content
Open
Show file tree
Hide file tree
Changes from 6 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
72 changes: 72 additions & 0 deletions docs/windows/lottie-scenarios/async-play.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
---
title: The Asynchronous Play Method
author: sohchatt
description: Sample of the asynchronous play method for Lottie-Windows.
keywords: lottie, lottie-windows, animatedvisualplayer, bodymovin, aftereffects, windows 10, uwp, uwp community toolkit
---

# The Asynchronous Play Method

So far, we’ve ignored the return value of the AnimatedVisualPlayer’s [PlayAsync](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer.playasync) method: it returns an [IAsyncAction](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer.playasync#returns) that completes when the animation reaches [toProgress](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer.playasync#parameters) (if it isn’t also [looped](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer.playasync#parameters)), or if the play is interrupted by the [Stop](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer.stop) or [SetProgress](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer.setprogress) methods, or if another [Source](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer.source) is loaded into the player. By `await`ing the completion of PlayAsync, we can trigger application logic or playback other animation sequences in coordination with the current Lottie animation.

To demonstrate this, we use two AnimatedVisualPlayer instances with _LightBulb.json_ to create the following pattern of animation sequences:

![Async Gif](./assets/lottiedocs-async.gif)

```csharp
private async Task PlayAnimationSequencesAsync()
{
// We await the completion of the PlayAsync method to create
// the following order of animation sequences:
// 1. A Hovered, then
// 2. B Hovered, then
// 3. A Clicked, then
// 4. B Clicked, then
// 5. A Hovered & B Hovered together, then
// 6. A Clicked & B Clicked together.

PlayerABorder.BorderBrush = _highlightedBrush;
PlayerBBorder.BorderBrush = _disabledBrush;
await PlayerA.PlayAsync(s_hoveredSegment.fromProgress, s_hoveredSegment.toProgress, s_hoveredSegment.looping);

PlayerABorder.BorderBrush = _disabledBrush;
PlayerBBorder.BorderBrush = _highlightedBrush;
await PlayerB.PlayAsync(s_hoveredSegment.fromProgress, s_hoveredSegment.toProgress, s_hoveredSegment.looping);

PlayerABorder.BorderBrush = _highlightedBrush;
PlayerBBorder.BorderBrush = _disabledBrush;
await PlayerA.PlayAsync(s_clickedSegment.fromProgress, s_clickedSegment.toProgress, s_clickedSegment.looping);

PlayerABorder.BorderBrush = _disabledBrush;
PlayerBBorder.BorderBrush = _highlightedBrush;
await PlayerB.PlayAsync(s_clickedSegment.fromProgress, s_clickedSegment.toProgress, s_clickedSegment.looping);

PlayerABorder.BorderBrush = _highlightedBrush;
PlayerBBorder.BorderBrush = _highlightedBrush;
await Task.WhenAll(PlayerA.PlayAsync(s_hoveredSegment.fromProgress, s_hoveredSegment.toProgress, s_hoveredSegment.looping).AsTask(),
PlayerB.PlayAsync(s_hoveredSegment.fromProgress, s_hoveredSegment.toProgress, s_hoveredSegment.looping).AsTask());

PlayerABorder.BorderBrush = _highlightedBrush;
PlayerBBorder.BorderBrush = _highlightedBrush;
await Task.WhenAll(PlayerA.PlayAsync(s_clickedSegment.fromProgress, s_clickedSegment.toProgress, s_clickedSegment.looping).AsTask(),
PlayerB.PlayAsync(s_clickedSegment.fromProgress, s_clickedSegment.toProgress, s_clickedSegment.looping).AsTask());

PlayerABorder.BorderBrush = _disabledBrush;
PlayerBBorder.BorderBrush = _disabledBrush;
}

```

If your scenario doesn’t require you to `await` the completion of PlayAsync, you may simply start the play and not keep track of it. In order to avoid a Visual Studio CS1998 compiler warning, we intentionally ignore the IAsyncAction returned from the PlayAsync method by using a [C# 7 discard](/dotnet/csharp/discards#a-standalone-discard) as follows:

```csharp
// Play the animation once.
_ = player.PlayAsync(fromProgress: 0, toProgress: 1, looped: false);
```

## Resources

* [Source code](https://github.com/windows-toolkit/Lottie-Windows/blob/rel/7.1.0/samples/LottieSamples/Scenarios/AsyncPage.xaml.cs) for sample: the asynchronous play method
* The resulting page in the [Lottie Samples application](https://aka.ms/lottiesamples)
* [PlayAsync](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer.playasync) method
* [Help + feedback](https://github.com/windows-toolkit/Lottie-Windows/issues)
41 changes: 41 additions & 0 deletions docs/windows/lottie-scenarios/fallback.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
---
title: Handling Failure and Down-level
author: sohchatt
description: How to handle failure and down-level using the FallbackContent property in AnimatedVisualPlayer.
keywords: lottie, lottie-windows, animatedvisualplayer, bodymovin, aftereffects, windows 10, uwp, uwp community toolkit
---

# Handling Failure and Down-level

The AnimatedVisualPlayer has a [FallbackContent](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer.fallbackcontent) property that allows you to provide custom XAML to be displayed in cases where Lottie-Windows is unable to render the animation, such as:

* a Lottie source that fails to load due to a malformed JSON file, incorrect URI, etc.
* your application running on a Windows 10 OS version **prior to 1809** (10.0.17763).

The FallbackContent is of type [DataTemplate](/uwp/api/Windows.UI.Xaml.DataTemplate) — this ensures that your custom XAML tree is only instantiated when the AnimatedVisualPlayer needs to fallback.
In the example below, we use an Image as fallback for the Lottie animation:

```xaml
<!-- AnimatedVisualPlayer -->
<controls:AnimatedVisualPlayer x:Name="player">
<!-- LottieVisualSource with invalid UriSource to cause fallback -->
<lottie:LottieVisualSource x:Name="JsonSource "
UriSource="https://notarealuri.microsoft.com/notarealfile.json" />
<!-- Fallback Content: Custom XAML content that is rendered if Source fails to load, or if app runs on Windows 10 verion < 1809. -->
<controls:AnimatedVisualPlayer.FallbackContent>
<DataTemplate>
<!-- Static Image for Fallback.
Because this is in a DataTemplate, the Image is only instantiated when in the fallback case. -->
<Image Source="/Assets/LottieLogo1.png" />
</DataTemplate>
</controls:AnimatedVisualPlayer.FallbackContent>
</controls:AnimatedVisualPlayer>

```

## Resources

* [Source code](https://github.com/windows-toolkit/Lottie-Windows/blob/rel/7.1.0/samples/LottieSamples/Scenarios/FallbackPage.xaml) for sample: handling failure and down-level
* The resulting page in the [Lottie Samples application](https://aka.ms/lottiesamples)
* [FallbackContent](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer.fallbackcontent) property
* [Help + feedback](https://github.com/windows-toolkit/Lottie-Windows/issues)
69 changes: 69 additions & 0 deletions docs/windows/lottie-scenarios/getting-started-codegen.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
---
title: Using Codegen
author: sohchatt
description: How to use codegen in Lottie-Windows.
keywords: lottie, lottie-windows, animatedvisualplayer, bodymovin, aftereffects, windows 10, uwp, uwp community toolkit
---

# Using Codegen

Consuming [Bodymovin](https://aescripts.com/bodymovin/) JSON files is the standard way of displaying Lottie animations on Web, Android, and iOS. However, this approach comes with the overhead of having to parse and translate JSON in your application’s process. You can get significant performance benefits by having Lottie-Windows generate the animation code as a C# or C++ class ahead of time, which may be used instead of the [LottieVisualSource](/dotnet/api/microsoft.toolkit.uwp.ui.lottie.lottievisualsource). Both approaches, JSON and Codegen, have the same visual outcome but [different workflows and benefits](./json-codegen.md).

## Generating a C# or C++ class from JSON

To generate a C# or C++ file from JSON use the [LottieGen](https://aka.ms/lottiegen) command-line tool.

1. In your command-line interface, install the LottieGen tool from nuget:

```
dotnet tool install -g LottieGen
```

2. Generate classes in your desired language as follows:

```
LottieGen -InputFile LottieLogo1.json -Language cs
```

For additional information about additional options including optimizations, use `LottieGen -Help`.

## Using the Codegen File

1. Add the generated file, _LottieLogo1.cs_, to your project by following steps similar to those outlined previously. Ensure that the [Build Action](/visualstudio/ide/build-actions) for all codegen C# or C++ files is set to **Compile**.

2. By default, all codegen classes are generated in the _AnimatedVisuals_ namespace. Modify your Page.xaml to include the namespace:

```xaml
xmlns:animatedvisuals="using:AnimatedVisuals"
```

3. Install the [Microsoft.UI.Xaml nuget package](https://www.nuget.org/packages/Microsoft.UI.Xaml/) which contains the [AnimatedVisualPlayer](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer) element. Modify your Page.xaml to include the namespace:

```xaml
xmlns:controls="using:Microsoft.UI.Xaml.Controls"
```

4. Instantiate the [AnimatedVisualPlayer](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer) element and configure its [Source](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer.source) as follows:

```xaml
<Border Style="{StaticResource LottiePlayer}">
<!--AnimatedVisualPlayer with AutoPlay-->
<controls:AnimatedVisualPlayer x:Name="LottiePlayer">
<!--Codegen class AnimatedVisuals/LottieLogo1.cs-->
<animatedvisuals:LottieLogo1/>
</controls:AnimatedVisualPlayer>
</Border>
```

This should result in a looping Lottie animation that is visually identical to our earlier approach of using a JSON file:

![Autoplay Gif](./assets/lottiedocs-autoplay.gif)

## Resources

* [Source code](https://github.com/windows-toolkit/Lottie-Windows/blob/rel/7.1.0/samples/LottieSamples/Scenarios/CodegenPage.xaml) for sample: getting started with Codegen
* The resulting page in the [Lottie Samples application](https://aka.ms/lottiesamples)
* [LottieGen](https://aka.ms/lottiegen) CLI tool
* [Lottie Viewer](https://aka.ms/lottieviewer) application for codegen and previewing JSON files
* A comparison of [JSON verus Codegen](./json-codegen.md)
* [Help + feedback](https://github.com/windows-toolkit/Lottie-Windows/issues)
59 changes: 59 additions & 0 deletions docs/windows/lottie-scenarios/getting-started-json.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
title: Getting Started with Lottie-Windows
author: sohchatt
description: How to use LottieVisualSource to load JSON in Lottie-Windows.
keywords: lottie, lottie-windows, animatedvisualplayer, bodymovin, aftereffects, windows 10, uwp, uwp community toolkit
---

# Getting Started with Lottie-Windows

You probably have a JSON file that was exported from [Adobe AfterEffects](https://www.adobe.com/products/aftereffects.html) using the [BodyMovin](https://aescripts.com/bodymovin/) plugin. If not, you can find many from the [fantastic community](https://lottiefiles.com/) of Lottie designers and creators. Let’s bring these animations to your Windows applications with the following steps:

1. _(Optional but Recommended)_ Install the [Lottie Viewer](https://aka.ms/lottieviewer) application from the Store and validate that the JSON file — _LottieLogo1.json_ in this example — works as expected. If there are any known issues due to unsupported AfterEffects features, the warning icon may light up and provide more context.

2. Install the [Microsoft.UI.Xaml nuget package](https://www.nuget.org/packages/Microsoft.UI.Xaml/) which contains the [AnimatedVisualPlayer](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer) element. In your VisualStudio project:
* Go to the Nuget Package Manager by navigating to Project > Manage Nuget Packages.
* Check the _Include prerelease_ box and search for “Microsoft.UI.Xaml” in nuget.org.
* Install the latest prerelease version of the nuget package available.

Modify your Page.xaml to include the namespace:

```xaml
xmlns:muxc="using:Microsoft.UI.Xaml.Controls"
```

3. Install the latest [Microsoft.Toolkit.Uwp.UI.Lottie nuget package](https://www.nuget.org/packages/Microsoft.Toolkit.Uwp.UI.Lottie/) by following steps similar to those listed above. Modify your Page.xaml to include the namespace:

```xaml
xmlns:lottie="using:Microsoft.Toolkit.Uwp.UI.Lottie"
```

4. Add the JSON file to your project:
* Add _LottieLogo1.json_ to the /AnimatedVisuals folder and include by right-clicking > Add > Existing Item.
* Set its [Build Action](/visualstudio/ide/build-actions) to **Content** in the Properties window.

<img src="./assets/lottiedocs-buildaction.png" alt="BuildAction" width="300" />

5. Instantiate the [AnimatedVisualPlayer](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer) element and configure the [LottieVisualSource](/dotnet/api/microsoft.toolkit.uwp.ui.lottie.lottievisualsource) to be consumed:

```xaml
<Border>
<!--AnimatedVisualPlayer with AutoPlay-->
<muxc:AnimatedVisualPlayer x:Name="LottiePlayer">
<!--LottieVisualSource with JSON UriSource-->
<lottie:LottieVisualSource x:Name="LottieJsonSource" UriSource="ms-appx:///AnimatedVisuals/LottieLogo1.json"/>
</muxc:AnimatedVisualPlayer>
</Border>
```

Since the [AutoPlay](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer.autoplay) property is set to True by default, the result will be this looping animation:

![Autoplay Gif](./assets/lottiedocs-autoplay.gif)

## Resources

* [Source code](https://github.com/windows-toolkit/Lottie-Windows/blob/rel/7.1.0/samples/LottieSamples/Scenarios/JsonPage.xaml) for sample: getting started with a JSON file
* The resulting page in the [Lottie Samples application](https://aka.ms/lottiesamples)
* [LottieVisualSource](/dotnet/api/microsoft.toolkit.uwp.ui.lottie.lottievisualsource) API reference
* [Lottie Viewer application](https://aka.ms/lottieviewer) for previewing JSON files
* [Help + feedback](https://github.com/windows-toolkit/Lottie-Windows/issues)
19 changes: 19 additions & 0 deletions docs/windows/lottie-scenarios/json-codegen.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
title: JSON versus Codegen
author: sohchatt
description: Tradeoffs between JSON and Codegen in Lottie-Windows.
keywords: lottie, lottie-windows, animatedvisualplayer, bodymovin, aftereffects, windows 10, uwp, uwp community toolkit
---

# JSON versus Codegen

Whether you choose to use a Bodymovin JSON file with a [LottieVisualSource](/dotnet/api/microsoft.toolkit.uwp.ui.lottie.lottievisualsource) or a codegen’ed C# or C++ class depends on your application’s requirements. Both types of sources are ultimately consumed by the [AnimatedVisualPlayer](/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer) element, but with slightly different workflows. Here’s an overview of how the pieces fit in:

<img src="./assets/lottiedocs-workflow.png" alt="Workflow" width="500"/>

The tradeoffs between using JSON and Codegen are as follows:

| JSON | Codegen |
| -------- | ----------- |
| Can be loaded from a URI at run-time &mdash; this enables Lottie animations to be updated over the network, without updating the application. | Better performance: there is no need to parse and translate JSON at run-time on the application’s UI thread, and, since the resulting Windows.UI.Composition tree is generated ahead of time, it can be better optimized. |
| | Allows dynamic modification of Lottie animations by editing the generated Windows.UI.Composition Visual tree. This is useful for theming, branding, accessibility, etc. (see [related scenario sample](https://github.com/windows-toolkit/Lottie-Windows/blob/rel/7.1.0/samples/LottieSamples/Scenarios/ModifyPage.xaml)).
Loading