Banner with Code

Quickstart

Overview

Quickstart guide version: v1.1.0-alpha

Compatible up to: v1.3.2-alpha


This guide covers, from scratch, making a new .NET Framework Windows Forms app and using AnimateForms in it. We will make a simple WinForms app that animates showing some information when the user clicks a button. Totally useless, but a good way to get to know how to use AnimateForms.

Creating your Project

In case you haven't yet, go ahead and create a new Windows Forms application in Visual Studio. We will be using the .NET Framework variant since AnimateForms isn't supported on .NET Core WinForms yet, and our target framework version will be the .NET Framework 4.7.2. Earlier frameworks have not been tested, but any later framework can also be used.

New Project Window

Placing Basic GUI

For this project, we will need to include a Button control, a Panel control, and three Label controls placed within the Panel so that they are children of it. We will not rename any controls, and will leave the defaults (button1, panel1, etc) for this guide. For the purposes of visibility, I recolored the panel and resized elements so they would fit better on this page.


The button control will serve as our toggle show/hide info, the panel will house our info (labels), and we will apply animations to both the panel and labels.

Basic GUI Layout

Installing AnimateForms

Installing AnimateForms can be done in multiple ways, but I recommend doing it through the NuGet Package Manager, either through the console or the GUI. After installing, add the using statement to the Form1.cs code file.


Package Manager console: PM> Install-Package AnimateForms -Version 1.1.0-alpha


Package Manager GUI:

1) Tools > NuGet Package Manager > Manage NuGet Packages for Solution

2) Click Browse tab

3) Search for "AnimateForms" and check "Include prerelease"

4) Install package for this project


Downloading the DLL:

1) Download the ZIP with the DLL here.

2) In Visual Studio, right click "References" in the Solution Explorer for the project.

3) Right click and click "Add reference"

4) Click the "Browse" tab and browse locally for the DLL.

5) Add the DLL.

Nuget Install

Adding the Animations

AnimateForms features a simple and easy to use API. In this guide, we will cover just the Resize method and some of the options it provides. The documentation for the rest of the methods the library provides is available here.


Let's add a boolean to our code first. This determines what animation to play based on whether the panel is shown or hidden.


private bool panelShown = true;


Then, we need a new Animate class to call the animations. Declare the following:


private readonly Animate a = new Animate();


This Animate class serves as an intermediary, ensuring less naming collisions between libraries, and also providing a few functions like preventing two animations of the same type acting on a single control at once. This prevents graphical glitches and unforeseen behaviour. Now, let's add our event handlers.


The button control will serve as our toggle. Double click it in the designer to create a new event handler for when it is clicked. Then, we want to make it an async method. Don't worry, making a WinForms event handler async won't break anything, as long as the return is still void.


private async void Button1_Click(object sender, EventArgs e) { }


In this method, we want to check the state of the boolean, apply the animation, the toggle the boolean end. We can use a simple if else statement. If the panel is shown, we want to run the following snippet of code:

await a.Resize(panel1, Easings.QuadInOut, 1000, new Size(0, 0));

This resizes the panel to be 0 pixels high and 0 pixels wide, essentially invisible and non-interactable. Optionally, you could also disable the panel after the await call has completed to prevent tab cycling to it. The duration of this is 1 second (1000ms) and uses the easing QuadInOut.


If the panel is not shown, run the same command, but use the expanded size, something like (300, 300).


At the end of the method, do panelShown = !panelShown; to keep things correct.

More Methods

After the previous step, you have a working animation. You can click run to try it out for yourself. However, we will also cover using the options object and bulk animations in this guide.


AnimateForms is capable of applying animations to arrays of Controls through an Options object - as such, it is possible to execute an animation on a Control's child controls through the use of a helper function. With this, we will animate the label controls in our application.


Let's start by adding the following to the if (panelShown) block. All of this code can simply be mirrored to the other side for the reverse animation. Before the previous await a.Resize(...) call, we can add another await a.Resize(...) directly after it. Await prevents the code from continuing before the function has returned a value, and so we know these two animations will play sequentially.


AnimateForms animation methods are broken up into two categories - a basic variant taking the minimum amount of options, which we have been using so far, and a variant (sometimes multiple depending on method) that uses an Options object. The full documentation for it is here. Let's make a new Options object with Options o = new Options();. You can see the defaults it sets in the documentation. We can stick with the defaults, unless you want to change them. You can change them by declaring the Options object with new Options { Parameter = value, ... } or using a preset constructor provided. However, we must specify a Control[] to use. Options objects can also take single controls.


We want to plug in a Control[], but panel1.Controls returns a ControlCollection. We can use one of AnimateForms' helper functions to convert that into a sorted Control[] easily. Simply plug in Helpers.SortCollectionByName(panel1.Controls) as a parameter into the Options constructor, or set o.Controls = Helpers.SortCollectionByName(panel1.Controls).


What if we wanted to stagger the animations, or use different easings per control? This can very easily be done by modifying our Options object later in the code or initializing it with the different parameters. See the documentation for all options. The Options class will give you control over delay, interval, targeting, easing(s), and more.


Let's just say we want to show and hide the labels by having them change their size, like the panel, but also have them stagger their animations by 100ms. We can create a new Options object, apply target, override the easing with your easing of choice, duration, delay (which we will set to 0), and interval of 100. This ends up looking like this:

await a.Resize(new Options(Helpers.SortCollectionByName(panel1.Controls), Easings.SinInOut, 1000, 0, 100));


After mirroring that to the show panel side of the if statement (changing the new sizes appropriately), the WinForms app now should behave as expected.

Additional Tips

We've only shown the use of await a.Method(...) in this guide. In the event you cannot use a bulk animation call and need to animate several elements at the same time in the same code block, you can use a discard _ = a.Method(...) for each method you want to run alongside eachother, with the last one having an await instead.