Animation effects

• Introduction
• Example use
• CSS animation vs canvas animation
  • CSS animations
• Combining effects
• Available Effects
• Things to note

Introduction

The animation and visual effects code is available in RGraph from August 2011. It greatly simplifies the process of animating your graphs or using visual effects.

The old way of using effects:

<script>
    bar = new RGraph.Bar('cvs', [3,6,5])
        .set('text.accessible', false)
        .set('margin.left', 50)
        .set('xaxis.labels', ['John','Fred','Lucy'])
    RGraph.Effects.Bar.Grow(bar)
</script>

The new way of using effects:

<script>
    new RGraph.Bar({
        id: 'cvs',
        data: [3,6,5],
        options: {
            marginLeft: 50,
            xaxisLabels: ['John','Fred','Lucy']
        }
    }).grow();  
</script>

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.common.effects.js" ></script>
<script src="RGraph.line.js" ></script>

<!-- Only needed for some effects (eg generic effects, scatter chart trace etc) -->
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js" ></script>

<script>
    new RGraph.Line({
        id: 'cvs',
        data: [
            [14,13,16,18,14,12,11,14,19,18,17,18],
            [11,12,14,12,11,13,13,15,14,15,13,14]
        ],
        options: {
            xaxisLabels: ['Jane','Geoff','Lou','Pob','Verity','Baz','Hue','Olga','Pete','Lou','Kev','Fred'],
            marginTop: 35,
            marginLeft: 40,
            marginRight: 5,
            marginBottom: 10
        }
    }).fadeIn(); // Was .draw();
</script>

CSS animation vs canvas animation

css animation (which the generic jquery effects are) 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, so does not incur redraws. As such you may find that choosing a css effect instead of a canvas effect is smoother. Also, you may wish to use the CSS3 animations library if you don't need to support older browsers (or you could use one effect for modern browsers and another effect for older browsers).

An alternative to the widely known and understood setTimeout function is the newer requestAnimationFrame. This is a function that has been optimised for animation compared to the older 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 fall-back though so that if the function isn't available the older setTimeout will be used.

CSS3 animations

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 and fadeIn effects.

<script>
    bar = new RGraph.Bar({
        id: 'cvs',
        data: [30, 32, 33, 30, 27, 30, 29, 27, 21, 21, 21,19],
        options: {
            yaxisScaleUnitsPre: '$',
            title: 'Sales in the last 8 months',
            titleVpos: 0.5,
            colors: ['Gradient(#fdd:red)'],
            marginLeft: 40,
            marginRight: 15,
            marginTop: 40,
            marginBottom: 50,
            shadow: true,
            shadowColor: '#bbb',
            shadowBlur: 3,
            backgroundColor: 'white',
            backgroundGridVlinesCount: 12,
            grouping: 'stacked',
            xaxisLabels: ['January', '\r\nFebruary', 'March', '\r\nApril', 'May', '\r\nJune', 'July', '\r\nAugust', 'September','\r\nOctober','November','\r\nDecember'],
            colorsStroke: 'rgba(0,0,0,0)',
            xaxis: false,
            titleItalic: true
        }
    });

    function showCombination(obj)
    {
        obj.fadeIn().grow();
    }
</script>

<button onclick="showCombination(bar)">Show Combining animations example</button>

Available effects

The effects that are available are listed on each chart's documentation page and you can also see all of the effects easily by looking at the demos that are bundled with RGraph in the download archive. You can also use the jquery animate function to animate the canvas tag and its css properties.

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 removeChild 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 jquery wrap function first (which wraps a div around the canvas or the RGraph wrap function (which essentially does the same thing):

   var div = RGraph.Effects.wrap(canvas);

   The function replaces the canvas with a div which has the same dimensions meaning your page structure won't change.
2. Because canvas animations may need to redraw the entire chart, they can be slower than css animations and depend on a variety of things - eg the speed of the user's PC and the work necessary to redraw the canvas.
   
   Note: If you're using a chart with a background grid along with a canvas effect you can increase the frame rate by turning off the background grid - the background grid has shown itself to be a drain on performance.