Banner with Code

AnimateForms

Documentation version: v1.3.2-alpha

Need older documentation? | What's next in v1.4.0a?


Preproduction Warning

While this library is mostly stable, I don't recommend the use of it in production. You have been warned.

Examples & Demos

Example snippets are included in this documentation. A basic demo app is available on GitHub.

Pro Tips

New to AnimateForms? No worries! Check out our quickstart guide to get yourself up and running.


Included Classes

Animate.cs

View Docs

An instantiable class to facilitate with animating WinForms controls.

Easings.cs

View Docs

Static class with all easing functions from gizma.com.

Helpers.cs

View Docs

Static class with functions to assist with using the API.


Options.cs

View Docs

Instantiable options class to assist with using the API.

Timeline.cs

View Docs

Instantiable queue of animations. Can be reused.


Outline

Introduction Animate.cs Function Move MoveRelative Recolor Resize
Easings.cs AllEasings Implemented
Helpers.cs CollectionToArray HSV HSVtoRGB RGBtoHSV SortCollectionByName
Options.cs
Timeline.cs Add Remove Execute

Introduction

AnimateForms is built around a single instantiable Animate class to call animations, with each animation (method, e.g. Resize) having a single "simple" form with "advanced" overloads as an option.


A method's "simple" form consists of the parameters Control c, Function easing, int duration, as well as any method-specific parameters needed, like Move's parameter Point moveTo. A method's "advanced" form consists of an Options object as a parameter, and any method-specific parameters. The Options object is a flexible tool for calling animations and specifying more parameters, like Delay, and even specifying arrays of Controls or easings to use. See the Options documentation for more info.


This documentation's included examples assume you have declared an Animate class named a.

Animate.cs Members

Class Information

Instantiable

To start using the animate functions, first declare an animator:

private Animate a = new Animate();

Then, any animated method is run as such:

await a.Method(parameters);


ProTip #1: By specifying await, the method is run synchronously and will not allow code to continue before the method has finished executing. Instead, a discard can be used to run asynchronously:

_ = a.Method(parameters);

ProTip #2: Animate classes will block two animations of the same type on the same control (unless otherwise noted in documentation). This prevents jittery graphics as two animations try to happen at once. As such, only one Animate class should ever be declared in your code.

Function (delegate)

Input: float t, b, c, d

Output: int

Defines an easing function that takes an input time t (current frame), start value b, change in value c, and duration of animation d and returns an integer defining what the current position should be. In AnimateForms, duration and current time are both always in milliseconds.


ProTip #1: You can use this delegate to define your own custom easing function, and plug it into any method for use.

ProTip #2: The Easings class defines many preset static easing functions that can be used as a parameter for methods that need this delegate.


Example: Animate.Function f = Easings.Linear;

Move

Input: Control control, Function easing, int duration, Point moveTo

Output: bool

Moves input control to point moveTo, using the specified duration and easing function. Returns true if animation completed and false if either location is the same or another animation is already in progress.


See Also:

Animate.Function

Options


Examples:

_ = a.Move(control, Easings.Linear, 1000, new Point(200, 20));

_ = a.Move(new Options(), new Point(200, 20));


Overloads:

Options o, Point moveTo

Applies animation using an Options object. See the Options documentation for possible modifiers.


Options o, Point moveTo, Point offset

Applies animation using an Options object. See the Options documentation for possible modifiers. If multiple controls are specified in the options, an offset will be applied per control (stacking them).

MoveRelative

Input: Control control, Function easing, int duration, Point offset

Output: bool

Similar to the standard Move animation, however, the offset recursively applies to the current control's location rather than setting it directly. As such, AnimateForms will not block multiple instances of this method at the same time. This creates an effect similar to applying a vector force to a control, except the control will always be offset by the amounts entered.


ProTip: Negative values can be entered in a Point object, and will make MoveRelative move the control up or left instead of down or right.


See Also:

Animate.Function

Options


Examples:

_ = a.MoveRelative(control, Easings.Linear, 1000, new Point(200, -20));

_ = a.MoveRelative(new Options(), new Point(200, -20));


Overloads:

Options o, Point offset

Applies animation using an Options object. See the Options documentation for possible modifiers.

Recolor

Input: Control control, Function easing, int duration, Color colorTo, [bool backColor = true]

Output: bool

Recolors input control to the specified ARGB color colorTo, using the specified duration and easing function. Returns true if animation completed and false if colorTo is equal to current color, or if another Recolor is running on the same control already. backColor can be used to determine whether the BackColor or the ForeColor property of the control is changed. This function supports using an HSV color object in place of an ARGB color.


Note: Limitations currently means transitioning opacities appears flickery and not great.


See Also:

Animate.Function

Options


Examples:

_ = a.Recolor(control, Easings.Linear, 1000, Color.Blue);

_ = a.Resize(new Options(), Color.Blue, false);


Overloads:

Input: Control control, Function easing, int duration, Helpers.HSV hsv, [bool backColor = true]

Applies animation using an HSV color object. This is provided by the Helpers class and results in a different look to the transition.


Options o, Color color, [bool backColor = true]

Applies animation using an Options object. See the Options documentation for possible modifiers.


Options o, Color[] colors, [bool backColor = true]

Applies animation using an Options object, cycling through an array of colors for each control. See the Options documentation for possible modifiers.


Options o, Helpers.HSV color, [bool backColor = true]

Applies animation using an HSV color and an Options object. This is provided by the Helpers class and results in a different look to the transition.


Options o, Helpers.HSV colors, [bool backColor = true]

Applies animation using an Options object, cycling through an array of HSV colors for each control. See the Options documentation for possible modifiers.


Resize

Input: Control control, Function easing, int duration, Size sizeTo

Output: bool

Resizes input control to input sizeTo, using the specified duration and easing function. Returns true if animation completed and false if sizeTo is equal to current size or another Resize is currently being run on the control.


See Also:

Animate.Function

Options


Examples:

_ = a.Resize(control, Easings.Linear, 1000, new Point(200, 200));

_ = a.Resize(new Options(), new Size(200, 200));


Overloads:

Options o, Size sizeTo

Applies animation using an Options object. See the Options documentation for possible modifiers.

Easings.cs Members

AllEasings (static)

Output: Function[]

A static Function[] of every easing provided, in case an array of every single easing was needed.


See Also: Animate.Function


ProTip: Options objects can take multiple easings and multiple input controls, and supported animations will cycle through easings per control.

Implemented Easings (static)

All easings found on Gizma have been implemented as static functions according to the delegate Animate.Function and are listed below with their abbreviations that they appear with in the Easings class. Each easing type will have an In, Out, and an InOut variant (except Linear).


See Also:

Animate.Function

https://easings.net (for visual reference)


Linear - Easings.Linear

Quadratic - Easings.QuadXX

Cubic - Easings.CubicXX

Quartic - Easings.QuartXX

Quintic - Easings.QuintXX

Circular - Easings.CircXX

Exponential - Easings.ExpXX

Sinusoidal - Easings.SinXX

Helpers.cs Members

CollectionToArray (static)

Input: Control.ControlCollection controlCollection

Output: Control[]

Converts a ControlCollection that results from calling parentControl.Controls to a control array for use in the animation functions.


ProTip: ControlCollections seem to be organized randomly, and you should only use this function when the resulting order of the array doesn't matter.

HSV (struct)

Parameters: double Hue, Saturation, Value

Holds an HSV color value for use by the Recolor method or one of the RGBtoHSV / HSVtoRGB helper functions. Has a constructor so it can be called inline cleanly.


Examples:

var hsv = new Helpers.HSV(180, 0.5f, 0.5f);

var hsv = new Helpers.HSV { Hue = 180, Saturation = 1, Value = 1 };

HSVtoRGB (static)

Input: HSV hsv

Output: Color

Converts an HSV object into a System.Drawing.Color RGB color.

RGBtoHSV (static)

Input: Color color

Output: HSV

Converts an RGB System.Drawing.Color color into an HSV object. If an alpha is provided, it will be ignored.

SortCollectionByName (static)

Input: Control.ControlCollection controlCollection

Output: Control[]

Converts a ControlCollection that results from calling parentControl.Controls to a control array, which is sorted by the control's Name property in alphabetical order.

Options.cs Members

Options

Parameters: Control control, Function easing, int duration

Optional Parameters: Control[] controls*, Function[] easings*, int delay, int interval

Non-Constructor Paramters: int endDelay

An options object to allow greater control over some animation functions. It can be created by using a constructor with parameters or by setting each element individually. Currently, all animations will accept an options object and will process all parameters set in one, since the options are universal.


See Also: Animate.Function


Easing: Easing function to use. Default = Linear.

Duration: Duration of animation, in milliseconds. Default = 1000ms.

Delay: Delay before animation starts.** Default = 0ms.

EndDelay: Delay after animation ends.** Default = 0ms.

Interval: Time between animations executing in bulk animation commands. Default = 0ms.


*Single control and single functions that get passed in as parameters get parsed into an array by the Options object anyway.

**If this is specified and the animation returns or will return false, it will still wait for this amount of time.


Timeline.cs Members

Class Information

Instantiable

Timelines are instantiable objects that can store a list of animations to run later. Instantiate with:

private readonly Timeline t = new Timeline();


Then, add animations with the following:

t.Add(() => a.Method(...));


Timelines can queue anything that returns a Task<bool>. As such, you can write your own custom functions to run in them.


When you wish to execute the timeline, use the following. Timelines can be reused, and are useful if there is a sequence of animations that need to be called repeatedly.

await t.Execute();


ProTip #1: Like other animate functions, a discard _ = t.Execute(); can be used to run the timeline without blocking code.

Add

Input: Func<Task<bool>> func, [bool shouldAwait = true]

Adds an animation to the timeline. Use a lambda to provide the function to add it. The animation added can be removed using the Remove method and the index of the animation added. Should await means the animation should run using an await tag - if this is set false, it will run using a discard _ = instead causing it to happen at the same time as the next animation in queue. This can cause issues as if the animations are of the same type, the second will be rejected.


ProTip: You can add your own function to a timeline so long as it returns Task<bool>.


Examples:

t.Add(() => a.Move(moveOptions, new Point(0, 0)));


Remove

Input: int index

Calls RemoveAt(int index) on the private List of functions within the Timeline object. May throw an ArgumentOutOfBounds exception.


Examples:

t.Remove(3);

t.Remove(0, 3);


Overloads:

int index, int count

Calls RemoveRange on the list instead, with index and count like normal.


Execute

Input: [bool discardAfterRun = false]

Runs every action added to the Timeline object. It will await every single call. If discardAfterRun is set to true, after an animation is played, it will be removed from the Timeline object, effectively resetting the Timeline object.


Examples:

t.Execute();