Class Animation

GoDiagram®
v10.0.8
by Northwoods Software®

Animations are used to animate GraphObject and Diagram properties.

Inheritance

object

Animation

Namespace: Northwoods.Go

Assembly: Northwoods.GoDiagram.WinForms.dll

Syntax

public class Animation

Remarks

This class is useful for creating manual animations. If you wish to animate particular properties on a GraphObject every time their value changes, you may want to use AnimationTriggers instead, which automatically create and start Animations.

The DefaultAnimation is an instance of this class, and carries out the default animations in GoDiagram: Model load, layout, expand and collapse, and so on. See the Introduction Page on Animations for more detail on the different kinds of animations.

Manual animations are set up by creating an instance of this class, and calling Add(object, string, object, object, bool) at least once, then calling Start(). The method Add(object, string, object, object, bool) specifies which objects and which animation effects/properties to animate, plus start and end values for the property. As objects are added to an Animation, the Animation infers which Diagram and AnimationManager is relevant.

Animations are started by calling Start(), and stopped when the Duration is reached, or when Stop() is called, or stopped when StopAnimation(bool) is called with true as its argument.

Animations can continue indefinitely if RunCount is set to int.MaxValue. Animations can act upon temporary copies of an object that will get destroyed by calling AddTemporaryPart(Part, Diagram). This is useful when crafting cosmetic animations of parts that are about to be deleted: Since the part will no longer exist, you can instead animate a temporary part disappearing.

A simple example usage is this:

var node = myDiagram.Nodes.FirstOrDefault();
var shape = node.FindElement("SHAPE") as Shape;  // assumes this Node contains a Shape with .Name = "SHAPE"
var animation = new Animation();
// Animate this Node from its current position to (400, 500)
animation.Add(node, "Position", node.Position, new Point(400, 500));
// Animate the fill of the Shape within the Node, from its current color to blue
animation.Add(shape, "Fill", shape.Fill, "blue");
// Both of these effects will animate simultaneously when Start() is called:
animation.Start();

See the Introduction Page on Animations and the Custom Animations sample for more example usage of the Animation class.

Unlike the DefaultAnimation, Animations can be started any time, and do not stop automatically when a new transaction begins.

Constructors

Animation()

Constructs an Animation with default property values.

Declaration

public Animation()

Properties

Duration

Gets or sets the duration for animations, in milliseconds.

Declaration

public int Duration { get; set; }

Property Value

Type	Description
int

Remarks

The default value is -1, which means it inherits the default value from the Duration, which defaults to 600 milliseconds.

The value must be an int greater than or equal to 1, or -1. Setting this property does not raise any events.

Easing

Gets or sets the easing function this Animation will use to modify default properties.

Declaration

public EasingFunction Easing { get; set; }

Property Value

Type	Description
EasingFunction

Remarks

Pre-defined animatable values are processed by passing scalars into this easing function.

The default value is EaseInOutQuad(double, double, double, int).

The value can be an arbitrary easing function, or one of the six provided: EaseLinear(double, double, double, int), EaseInOutQuad(double, double, double, int), EaseInQuad(double, double, double, int), EaseOutQuad(double, double, double, int), EaseInExpo(double, double, double, int), EaseOutExpo(double, double, double, int).

Finished

Gets or sets the function to execute when the user Animation finishes.

Declaration

public Action<Animation> Finished { get; set; }

Property Value

Type	Description
Action<Animation>

Remarks

By default this property is null.

IsAnimating

This read-only property is true when the Animation is currently running.

Declaration

public bool IsAnimating { get; }

Property Value

Type	Description
bool

Remarks

This value cannot be set, but Animation can be stopped by calling Stop().

IsViewportUnconstrained

Gets or sets whether this Animation should allow an unconstrained viewport during the runtime of the animation.

Declaration

public bool IsViewportUnconstrained { get; set; }

Property Value

Type	Description
bool

Remarks

This temporarily sets the ScrollMode to Infinite, and restores the value at the end of the animation. This is done so that animating objects can move out of the viewport temporarily during the animation and not trigger scrollbars.

This may be useful to set for animations that have objects or the Diagram bounds animate from outside the viewport into the view. The default value is true.

Reversible

Gets or sets whether this Animation will repeat its animation in reverse at the end of the duration.

Declaration

public bool Reversible { get; set; }

Property Value

Type	Description
bool

Remarks

The default value is false.

A reversible Animation, if stopped early, will end at its original state. Setting this to true doubles the effective Duration of the Animation.

This property should not be set on the DefaultAnimation

RunCount

Gets or sets whether this Animation should be repeat, and how many times.

Declaration

public int RunCount { get; set; }

Property Value

Type	Description
int

Remarks

The default is 1, which means the animation does not repeat.

This can be set to any non-zero positive integer, or int.MaxValue. Setting this to int.MaxValue will repeat an animation forever.

This property should not be set on the DefaultAnimation

See Also

Reversible

Methods

Add(object, string, object, object, bool)

Add an object (GraphObject or Diagram) and effect name, with specified start and end values, to this Animation.

Declaration

public Animation Add(object obj, string effectName, object startValue, object endValue, bool cosmetic = false)

Parameters

Type	Name	Description
object	obj	GraphObject or Diagram to animate.
string	effectName	Animation effect name, such as "Scale" to change GraphObject.Scale.
object	startValue	The starting value for the animated property. Often this is the current value of the property.
object	endValue	The ending value for the animated property. Even if the animation is just cosmetic, this must be a valid value for the property. For instance, for Scale, you cannot animate to 0, as this is an invalid scale value. Instead you would animate to a very small (but still valid) value, such as 0.001.
bool	cosmetic	Determines if the animation should revert the property value to the start value at the end of animation. Default false. This is commonly used when animating opacity or scale of "disappearing" nodes during collapse. Even though the node may appear to go to scale 0.001, the programmer usually wants the scale to reflect its prior value, once hidden.

Returns

Type	Description
Animation	this Animation

Remarks

By default the supported properties are, for GraphObjects:

• "Position"
• "Location" (on Parts)
• "Scale"
• "Opacity"
• "Angle"
• "DesiredSize"
• "Width"
• "Height"
• "Background"
• "Fill" (on Shapes)
• "StrokeWidth" (on Shapes)
• "StrokeDashOffset" (on Shapes)
• "Stroke" (on Shapes, TextBlocks)

For Diagrams:

• "Position"
• "Scale"
• "Opacity"

More properties can be supported by defining new effects with DefineAnimationEffect(string, AnimationFunction).

AddTemporaryPart(Part, Diagram)

Add a temporary Part to this animation.

Declaration

public Animation AddTemporaryPart(Part part, Diagram diagram)

Parameters

Type	Name	Description
Part	part	A part to add to the Diagram at the start of the animation and remove at the end. This is typically either a copied Part already in the Diagram, to animate its deletion, or a Part created programmatically to be used for some effect.
Diagram	diagram	The Diagram to add the temporary part to, and remove it from, at the start and end of animation, respectively.

Returns

Type	Description
Animation	this Animation

Remarks

This part will be added to the Diagram when the animation is started, and removed from the Diagram when the animation completes. This is intended to be used with Add(object, string, object, object, bool), to animate properties of this Part or its elements.

The temporary part added is typically either a Copy() of an existing Part, which is to be deleted and requires a copy for animated effects, or else a wholly new temporary Part, constructed in memory for the purpose of creating some effect.

EaseInExpo(double, double, double, int)

Built-in static function for computing interpolated values. Can be used as a value for Easing.

Declaration

public static double EaseInExpo(double currentTime, double startValue, double byValue, int duration)

Parameters

Type	Name	Description
double	currentTime
double	startValue
double	byValue
int	duration

Returns

Type	Description
double

EaseInOutQuad(double, double, double, int)

Built-in static function for computing interpolated values. Can be used as a value for Easing. This is the default value for Easing.

Declaration

public static double EaseInOutQuad(double currentTime, double startValue, double byValue, int duration)

Parameters

Type	Name	Description
double	currentTime
double	startValue
double	byValue
int	duration

Returns

Type	Description
double

EaseInQuad(double, double, double, int)

Built-in static function for computing interpolated values. Can be used as a value for Easing.

Declaration

public static double EaseInQuad(double currentTime, double startValue, double byValue, int duration)

Parameters

Type	Name	Description
double	currentTime
double	startValue
double	byValue
int	duration

Returns

Type	Description
double

EaseLinear(double, double, double, int)

Built-in static function for computing interpolated values. Can be used as a value for Easing.

Declaration

public static double EaseLinear(double currentTime, double startValue, double byValue, int duration)

Parameters

Type	Name	Description
double	currentTime
double	startValue
double	byValue
int	duration

Returns

Type	Description
double

EaseOutExpo(double, double, double, int)

Built-in static function for computing interpolated values. Can be used as a value for Easing.

Declaration

public static double EaseOutExpo(double currentTime, double startValue, double byValue, int duration)

Parameters

Type	Name	Description
double	currentTime
double	startValue
double	byValue
int	duration

Returns

Type	Description
double

EaseOutQuad(double, double, double, int)

Built-in static function for computing interpolated values. Can be used as a value for Easing.

Declaration

public static double EaseOutQuad(double currentTime, double startValue, double byValue, int duration)

Parameters

Type	Name	Description
double	currentTime
double	startValue
double	byValue
int	duration

Returns

Type	Description
double

GetTemporaryState(object)

Gets the Hashtable associated with this GraphObject or Diagram. If no state exists, this creates and returns a new Hashtable.

Declaration

public Hashtable GetTemporaryState(object obj)

Parameters

Type	Name	Description
object	obj

Returns

Type	Description
Hashtable

Remarks

This can be used to store temporary information per animated object during the course of an animation. This state is cleared at the end of an animation.

Start()

Start this animation.

Declaration

public Animation Start()

Returns

Type	Description
Animation	this Animation

Remarks

This adds the Animation to its AnimationManager's list of active animations. The AnimationManager is inferred from the list of objects to be animated, by inspecting their Diagram.

This does nothing if there are no objects to animate.

Stop()

Stops a running Animation and updates the animating objects to their final state.

Declaration

public Animation Stop()

Returns

Type	Description
Animation	this Animation

Remarks

If an animation was about to begin, it is cancelled.