Where to Find Up-to-date yFiles Information

This page is from the outdated yFiles for Java 2.13 documentation. You can find the most up-to-date documentation for all yFiles products on the yFiles documentation overview page.

Please see the following links for more information about the yFiles product family of diagramming programming libraries and corresponding yFiles products for modern web apps, for cross-platform Java(FX) applications, and for applications for the Microsoft .NET environment.

More about the yFiles product family Close X

Animations for Graph Elements

The yFiles graph visualization library enables high-quality animations and visual effects for graph elements, more precisely their visual representations. Node realizers, edge realizers, but also drawables can be subject for arbitrary effects. Predefined generic animations and effects are, for example:

These effects and animations build upon the general animation framework defined in package y.anim, which enables processing of animations both in parallel and in sequence, allows repetitions of animations, and also pausing between animations.

Animation Framework

Package y.anim contains the classes that constitute a general animation framework. Class AnimationPlayer is the central instance that governs an animation process. It is given a so-called animation object, an implementation of interface AnimationObject, which encapsulates an actual animation respectively a compound of animations.

Effectively, an animation object provides a sequence of so-called "frames" that represent the animation's state as it evolves over time. AnimationPlayer progresses the overall animation process by continuously triggering the given animation object to calculate a single new frame that corresponds to the supplied (strictly monotonic) increasing time value. Whenever a new frame has been calculated, the animation player notifies all registered animation listeners, i.e., implementations of interface AnimationListener, to update their associated view so that the new frame is displayed.

AnimationPlayer also triggers initialization of an AnimationObject before the animation process and any necessary cleanup thereafter by calling appropriate methods. Figure 6.67, “Animation framework central classes” shows the role of class AnimationPlayer.

Figure 6.67. Animation framework central classes

Animation framework central classes.

Setup for processing a given animation object and having the progress of the (compound) animation displayed in a view is demonstrated in Example 6.52, “Playing a (compound) animation”.

Example 6.52. Playing a (compound) animation

void startAnimation(AnimationListener al, AnimationObject ao)
{
  // Create a new AnimationPlayer that processes the given (compound) animation. 
  AnimationPlayer player = new AnimationPlayer();
  // Register the given animation listener that is to display the (compound) 
  // animation. Usually, Graph2DView or Graph2DViewRepaintManager are provided 
  // to this end. 
  player.addAnimationListener(al);
  // Play the given (compound) animation. 
  player.animate(ao);
}

An animation listener is responsible for updating its associated view that hosts an animation. It triggers a repainting of the view each time the animation progresses, i.e., each time a new frame has been calculated. Predefined implementations for interface AnimationListener are classes Graph2DView and Graph2DViewRepaintManager, both from package y.view.

When using Graph2DView directly as an animation listener, the entire viewport is repainted to display the frames of an animation. Graph2DViewRepaintManager, in contrast, allows fine-grained control over the repaint area. It provides registration methods for realizers and drawables to advertise their participation in an upcoming animation. Subsequently, Graph2DViewRepaintManager invokes repaints on only the union of bounds of these realizers and drawables, which results in performance benefits especially for animations that are confined to a small region.

Animation objects are the actual provider of an animation. Their task is to generate a sequence of frames that represent the animation's state as it evolves over time. An animation's time is defined to run in the range 0.0 to 1.0 from animation start to animation end.

To create animation objects, the factory classes AnimationFactory and ViewAnimationFactory can be used. The former class returns animation objects that primarily address structural concerns, more precisely, it returns animation objects that can be used to define animations that:

  • can be processed concurrently
  • can be processed sequentially
  • are processed repeatedly
  • do nothing, i.e., that effectively introduce a pause

To achieve concurrent and sequential processing of a set of animations, interface CompositeAnimationObject provides the necessary methods to add or remove single animation objects to form compound animations. The following methods from class AnimationFactory can be used to define the structure of an animation process that is composed of multiple animation objects:

Class AnimationFactory also provides a set of animation objects that can be used as "decorators" for other animations, namely these are ease in and ease out effects. An ease in effect applies a configurable acceleration at the beginning of a given animation, likewise, an ease out effect applies a configurable deceleration at the end. Example 6.53, “Layout morphing using ease in and ease out effects” shows how both ease in and ease out effects can be used to smooth the morphing between two graph layouts.

Example 6.53. Layout morphing using ease in and ease out effects

void morphLayoutUsingEaseInEaseOutDecoration(Graph2DView view, GraphLayout gl)
{
  // Create a regular LayoutMorpher and subsequently "decorate" it using ease 
  // in and ease out effects. 
  LayoutMorpher plainLM = new LayoutMorpher(view, gl);
  AnimationObject easedLM = AnimationFactory.createEasedAnimation(plainLM);
  
  // Play the animation, i.e., perform smooth layout morphing. 
  AnimationPlayer player = new AnimationPlayer();
  player.setFps(240);
  player.addAnimationListener(view);
  player.animate(easedLM);
}

Class ViewAnimationFactory, in contrast, can be used to return a variety of high-quality animations and visual effects for graph elements, more precisely their visual representations. Figure 6.68, “Classes that create animation objects” shows the classes that are involved in creating animation objects.

Figure 6.68. Classes that create animation objects

Classes that create animation objects.

By default, ViewAnimationFactory is configured to return animations that trade animation quality for speed. Using the following methods and constants, the quality for animations and effects can conveniently be controlled:

static final AnimationQuality DEFAULT
static final AnimationQuality HIGH_QUALITY
static final AnimationQuality HIGH_PERFORMANCE
Description Animation quality constants.
AnimationQuality getQuality()
void setQuality(AnimationQuality quality)
Description Getter/setter methods to control the quality of animations and effects.

Example 6.54, “Creating animations that repeat” shows how both classes AnimationFactory and ViewAnimationFactory can be used to create an animation object that combines structural aspect (repetition) and visual effect (blinking).

Example 6.54. Creating animations that repeat

AnimationObject createRepeatedBlinking(NodeRealizer nr, 
                                       Graph2DViewRepaintManager rm, int times)
{
  // Create the view animation factory and register the given repaint manager 
  // as the responsible animation listener. 
  ViewAnimationFactory vaf = new ViewAnimationFactory(rm);
  // The node realizer is automatically added to the repaint manager's list of 
  // objects to update. 
  // Note that the "blink" animation itself lasts 100 milliseconds. 
  AnimationObject blink = vaf.blink(nr, 100);
  
  // Return an animation object that repeats the "blink" animation for the 
  // specified number of times. 
  return AnimationFactory.createRepetition(blink, times, true);
}

Tutorial Demo Code

The tutorial demo applications

demonstrate usage of the animation framework and also many of the effects provided by factory class ViewAnimationFactory. AnimatedStructuralChangesDemo.java shows how to highlight structural changes of a graph.