RGraph: HTML5 Javascript charts library - Animation and visual effects

• Introduction
• Example use
• CSS animation vs <canvas> animation
• Combining effects
• The .Animate() function
• Available Effects
  • Fade in
  • Fade out
  • Expand
  • Snap
  • Reveal
  • Horizontal blinds (open)
  • Horizontal blinds (close)
  • Vertical blinds (open)
  • Vertical blinds (open)
  • Pie chart Grow
  • Pie chart Implode
  • Pie chart RoundRobin
  • Bar chart Grow
  • Fuel chart Grow
  • Slide out
  • Slide in
  • Line chart Unfold
  • Line chart UnfoldFromCenter
  • Line chart FoldToCenter
  • Line chart Trace
  • Rose chart Grow
  • Odometer Grow
  • Meter chart Grow
  • HBar chart Grow
  • Gauge chart Grow
  • Radar chart Grow
  • Waterfall chart Grow
• An animated (interactive) Pie chart
• Things to note

Introduction

The animation and visual effects code is new to RGraph as of August 2011. It greatly simplifies the process of animating your graphs or using visual effects.

Example use

To use the effects you simply change your call to the .Draw() method to the appropriate effect function, like this:

<script src="RGraph.common.core.js" ></script>
<script src="RGraph.line.js" ></script>
<script src="RGraph.common.effects.js" ></script>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js" ></script>

<script>
    var myLine = new RGraph.Line('myLine', [14,13,16,18,14,12,11,14,19,18,17,18], [11,12,14,12,11,13,13,15,14,15,13,14]);
    myLine.Set('chart.labels', ['Jane','Geoff','Lou','Pob','Verity','Baz','Hue','Olga','Pete','Lou','Kev','Fred']);
    myLine.Set('chart.gutter.top', 35);
    myLine.Set('chart.gutter.left', 40  );
    myLine.Set('chart.gutter.right', 5);
    myLine.Set('chart.gutter.bottom', 10);
    
    // myLine.Draw();
    RGraph.Effects.Fade.In(myLine);
</script>

CSS animation vs <canvas> animation

CSS animation (which jQuery does) can be smoother than canvas animation (ie changing the CSS properties vs redrawing the canvas). This is because CSS animation (ie changing the CSS properties) does not have the side effect of clearing the canvas, and so does not incur a redraw.

An alternative to the widely known and understood setTimeout() function is the newer requestAnimationFrame(). This is a function which has been optimised for animation compared to the standard setTimeout() function. Some of the animation functions use this over the setTimeout() function and going forward newer animation functions will use it. RGraph has a fallback though so that if the function isn't available the older setTimeout() will be used.

Combining effects

Some of the animation effects (ie those that work on separate aspects of the chart) can be combined. As an example the Fade in/out can be combined with most other animation effects, allowing you to add a fade effect to the other animation types. An example of this is below - this chart uses the Grow, Fade and Reveal effects.

<script>
    function ShowCombination(obj)
    {
        RGraph.Effects.Fade.In(obj);
        RGraph.Effects.jQuery.Reveal(obj);
        RGraph.Effects.Bar.Grow(obj);
    }
</script>
<button onclick="ShowCombination(myBar)">Show Combining animations example</button>

There's another example of combined effects on the combined charts page.

The .Animate() function

The .Animate() function function is similar to the jQuery .Animate() function. You can pass it a map of RGraph properties and their TARGET values and the .Animate() function will move the properties towards those values. In this way you can animate a variety of RGraph properties. The .Animate() function takes two or three arguments:

• The graph object
• A map of the target chart properties
• (Optional) A function object which is called when the animation is complete (it is passed the chart object)

An example of it use is below. It should be used instead of calling the .Draw() method:

function myCallback (obj)
{
    alert('A sample callback using the alert() function');
}

// myBar.Draw();
RGraph.Effects.Animate(myBar, {'chart.hmargin': 5, 'chart.gutter.left': 50}, myCallback);

Available effects

These are the effects available. You can achieve more effects by using the .Animate() function, which allows you to animate any numeric RGraph property.

RGraph.Effects.Fade.In(obj);

RGraph.Effects.Fade.Out(obj);

RGraph.Effects.jQuery.Expand(obj);

RGraph.Effects.jQuery.Snap(obj);

RGraph.Effects.jQuery.Reveal(obj);

RGraph.Effects.jQuery.Blinds.Open(obj);

RGraph.Effects.jQuery.HBlinds.Close(obj);

RGraph.Effects.jQuery.VBlinds.Open(obj);

RGraph.Effects.jQuery.VBlinds.Close(obj);

RGraph.Effects.Pie.Grow(obj);

RGraph.Effects.Pie.Implode(obj);
//RGraph.Effects.Pie.RoundRobin(obj);

RGraph.Effects.Pie.RoundRobin(obj);
//RGraph.Effects.Pie.Implode(obj);

RGraph.Effects.Bar.Grow(obj);

RGraph.Effects.Fuel.Grow(obj);

RGraph.Effects.jQuery.Slide.Out(obj, {'direction': 'bottom'});

RGraph.Effects.jQuery.Slide.In(obj, {'direction': 'right'});

RGraph.Effects.Line.Unfold(obj);

RGraph.Effects.Line.UnfoldFromCenter(obj);

RGraph.Effects.Line.FoldToCenter(obj);

RGraph.Effects.Line.jQuery.Trace(myLine14);

RGraph.Effects.Rose.Grow(obj);

RGraph.Effects.Odo.Grow(obj, null, myFunc);

RGraph.Effects.Meter.Grow(obj, {'frames': 90});

RGraph.Effects.HBar.Grow(obj);

RGraph.Effects.Gauge.Grow(obj);

RGraph.Effects.Radar.Grow(obj);

RGraph.Effects.Waterfall.Grow(obj);

Things to note

1. With Fade in/out effects remember that just because you can't see the canvas (ie the opacity is 0) doesn't mean that you can't interact with it, so tooltip hotspots will still be active. If you want to get rid of the canvas entirely you need to remove it from the DOM. You can do this with the standard.removeNode function:

   obj.canvas.parentNode.removeChild(obj.canvas);

   This will leave a hole in the page though and will cause the page layout to change. If this is an issue you may want to use the RGraph API function RGraph.Effects.ReplaceCanvasWithDIV(canvas). As the name suggests, this function replaces the canvas with a DIV which has the same dimensions meaning your page structure won't change.
2. It should be noted that in order to prevent the canvas being constantly drawn on, it is cleared at the start of the animation.
3. In the jQuery animations here, the Google hosted jQuery is used:

   <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js"></script>

4. Because canvas based animations may need to redraw the entire chart, they can be slower than CSS based animations and depend on a variety of things - eg the speed of the users PC and the work necessary to redraw the canvas.