LoaderKit.WinUI 1.0.0-rc.0

LoaderKit for Windows

Loading indicators described as data and rendered natively with Microsoft.UI.Composition, for WinUI 3 and the Windows App SDK. Every indicator is a JSON spec shared with the Android and Apple engines, so the same name or spec looks and moves the same on every platform. Full guide with live examples: https://maitrungduc1410.github.io/loader-kit/platforms/windows

Install

dotnet add package LoaderKit.WinUI

LoaderKit.WinUI brings LoaderKit.Core with it. It supports Windows 10 version 1809 (build 17763) and later.

XAML

<Page
    xmlns:lk="using:LoaderKit.WinUI">

    <StackPanel Spacing="16">
        
        <lk:LoaderKitIndicator />

        <lk:LoaderKitIndicator Indicator="BallSpinFadeLoader" Color="DodgerBlue" Width="64" Height="64" />

        <lk:LoaderKitIndicator Indicator="SquareSpin" Speed="0.5" IsAnimating="{x:Bind ViewModel.IsBusy, Mode=OneWay}" />
    </StackPanel>
</Page>

C#

using LoaderKit;
using LoaderKit.WinUI;
using Microsoft.UI;

var indicator = new LoaderKitIndicator
{
    Indicator = "BallPulse",
    Params = new Dictionary<string, double> { ["count"] = 5, ["minScale"] = 0.5 },
    Colors = new[] { Colors.Tomato, Colors.Gold, Colors.MediumSeaGreen },
    Speed = 1.5,
};

indicator.IsAnimating = false;   // freezes; with HidesWhenStopped (default true) it also hides
indicator.CycleProgress = 0.25;  // draws a still frame a quarter into the animation cycle
indicator.CycleProgress = null;  // the clock resumes from where it was

foreach (var name in BuiltinIndicators.Names) Console.WriteLine(name);

Changing Indicator, Spec, IndicatorSpec or Params restarts the animation. Changing colors, speed or size does not. When a spec cannot be used the control draws nothing, sets SpecError and raises SpecFailed; it never throws from a property setter.

Built-in indicators

The 33 indicators of BuiltinIndicators.Names:

Custom specs

Experimental. Writing your own spec is experimental: until the schema is declared stable, it may change in a minor release. The built-in indicators are not affected, since they ship with the matching engine.

A spec lists elements placed in a unit box, a shape, and tracks that animate element properties over one cycle; several groups of elements can be combined with parts. The schema is documented in SPEC.md.

const string json = """
    {
      "schemaVersion": 1,
      "name": "ThreeBars",
      "duration": 0.9,
      "params": { "low": 0.4 },
      "layout": { "type": "row", "count": 3, "gap": 0.15 },
      "shape": { "type": "line" },
      "stagger": { "each": 0.15 },
      "tracks": [
        { "property": "scaleY", "keyTimes": [0, 0.5, 1], "values": [1, { "$param": "low" }, 1], "easing": "easeInOut" }
      ]
    }
    """;

indicator.Spec = json;

// Or parse it yourself to see every problem at once.
if (!IndicatorSpec.TryParse(json, out var spec, out var errors))
{
    foreach (var error in errors) Debug.WriteLine(error);   // e.g. "tracks[0].keyTimes must be non-decreasing"
}
else
{
    indicator.IndicatorSpec = spec;
}

Specs can also be built in code:

var pulse = new IndicatorSpec("Pulse", duration: 1, new IndicatorPart(new SingleLayout(), new CircleShape())
{
    Tracks = new[]
    {
        new Track(AnimatableProperty.Scale, new double[] { 0, 1 }, new Num[] { 0, 1 }) { Easing = Easing.EaseOut },
        new Track(AnimatableProperty.Opacity, new double[] { 0, 1 }, new Num[] { 1, 0 }),
    },
});

var problems = pulse.Validate();   // empty when valid

// Several groups: element indices, and so colors, continue from one part to the next.
var orbit = new IndicatorSpec("Orbit", duration: 1, new[]
{
    new IndicatorPart(new SingleLayout(Size: 0.3), new CircleShape())
    {
        Tracks = new[] { new Track(AnimatableProperty.Scale, new double[] { 0, 0.5, 1 }, new Num[] { 1, 0.8, 1 }) },
    },
    new IndicatorPart(new SingleLayout(Size: 0.15, Y: 0.1), new CircleShape())
    {
        GroupTracks = new[] { new Track(AnimatableProperty.Rotate, new double[] { 0, 1 }, new Num[] { 0, 2 * Math.PI }) },
    },
});

In XAML, put JSON in a resource or escape the leading brace (Spec="{}{ ... }"), because { starts a markup extension.

Without the control

LoaderKit.Core has no UI dependency. Use it to draw indicators with another renderer:

var prepared = new PreparedIndicator(BuiltinIndicators.Get("BallPulse"));
var states = new ElementState[prepared.ElementCount];

prepared.Evaluate(t: 0.3, states);   // positions, sizes, scales, opacity, rotations, trims and group transform
var matrix = ElementTransform.Create(states[0], prepared.Perspective, boxSize: 40);   // group transform included
var shape = prepared.Parts[states[0].Part].Shape;   // the shape with its defaults filled in

IndicatorPlayback implements the shared playback rules (clock, speed, stop, cycle progress, reduce motion).

Building

dotnet test windows/LoaderKit.Core.Tests -c Release   # any OS; runs the shared test vectors
dotnet pack windows/LoaderKit.Core -c Release
dotnet pack windows/LoaderKit.WinUI -c Release        # Windows only

License

MIT