# Animation and visual effects

- Introduction
- Example use
- CSS animation vs <canvas> animation
- Combining effects
- The .Animate() function
- Available Effects

  - Line chart FoldToCenter
  - Line chart Trace
  - Rose chart Grow
  - Rose chart Explode
  - Rose chart Implode
  - Odometer Grow
  - Meter chart Grow
  - HBar chart Grow
  - Gauge chart Grow
  - Radar chart Grow
  - Waterfall chart Grow
  - Fade in
  - Fade out
  - Expand
  - Snap
  - Reveal
  - Conceal
  - Horizontal blinds (open)
  - Horizontal blinds (close)
  - Vertical blinds (open)
  - Vertical blinds (open)
  - Pie chart Grow
  - Pie chart Implode
  - Pie chart RoundRobin
  - Pie chart Wave
  - Bar chart Grow
  - Bar chart Wave
  - Gantt chart Grow
  - Fuel chart Grow
  - Slide out
  - Slide in
  - Line chart Unfold
  - Line chart UnfoldFromCenter
- An animated (interactive) Pie chart
- Things to note

### Introduction

The animation and visual effects code is new to OfficeExcel 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="OfficeExcel.common.core.js" ></script>
    <script src="OfficeExcel.line.js" ></script>
    <script src="OfficeExcel.common.effects.js" ></script>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js" ></script>

    <script>
        var myLine = new OfficeExcel.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();
        OfficeExcel.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. OfficeExcel 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)
        {
            OfficeExcel.Effects.Fade.In(obj);
            OfficeExcel.Effects.jQuery.Reveal(obj);
            OfficeExcel.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 OfficeExcel 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 OfficeExcel 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();
    OfficeExcel.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 OfficeExcel property.

#### Fade in

A simple fade in effect where the canvas is initially drawn with an opacity of zero, increasing to one.

    OfficeExcel.Effects.Fade.In(obj);

#### Fade out

A simple fade out effect to accompany the fade in, where the canvas initially has an opacity of one, decreasing to zero.

    OfficeExcel.Effects.Fade.Out(obj);

#### Expand

This effect starts initially with the canvases CSS width and height set to 0 and over a period of half a second increases them to 100%.

    OfficeExcel.Effects.jQuery.Expand(obj);

#### Snap

This effect is similar to the tooltip effect "snap" in that it "snaps" to the correct position, moving in from the top left.

    OfficeExcel.Effects.jQuery.Snap(obj);

#### Reveal

This effect starts with the the canvas covered and is slowly revealed from the center outwards. The canvas is at all times the same size (ie it's not resizd as with the Expand effect).

    OfficeExcel.Effects.jQuery.Reveal(obj);

#### Conceal

This effect is a reversal of the above Reveal effect - it gradually covers the canvas with DIVs. Combining it with the above Reveal effect can make an effective transition.

    OfficeExcel.Effects.jQuery.Conceal(obj);

#### Horizontal Blinds (open)

This effect gradually reveals the canvas by "opening some horizontal blinds", which are positioned over the canvas.

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

#### Horizontal Blinds (close)

This effect gradually conceals the canvas by "closing some horizontal blinds", which are positioned over the canvas.

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

#### Vertical Blinds (open)

This effect gradually reveals the canvas by "opening some vertical blinds", which are positioned over the canvas.

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

#### Vertical Blinds (Close)

This effect gradually conceals the canvas by "closing some vertical blinds", which are positioned over the canvas.

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

#### Pie chart Grow

This effect gradually increases the radius of the Pie chart, expanding out from the centre.

    OfficeExcel.Effects.Pie.Grow(obj);

#### Pie chart Implode

This effect gradually decreases the explosion of the chart - gradually bringing it together. Combined with the RoundRobin effect (documented below) produces a nice combination, as seen on the frony page of this website.

    OfficeExcel.Effects.Pie.Implode(obj);

#### Pie chart RoundRobin

This effect gradually increase both the circular size of the Pie chart and also the radius. Combining this effect with the implode effect produces a nice effect.

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

#### Pie chart Wave

This effect is vaguely similar to the RoundRobin effect, and slowly shrinks the segments to the correct size.

    OfficeExcel.Effects.Pie.Wave(obj);

#### Bar chart Grow

This effect gradually increases the size of the bars on the bar chart until they are at full size.

    OfficeExcel.Effects.Bar.Grow(obj);

#### Bar chart Wave

This effect gradually increases the values of the Bar chart in a wave motion until they are correct.

Note:

Some features of OfficeExcel that use extra processing (eg the 3D effect) will cause this effect to have a slow frame rate.

    OfficeExcel.Effects.Bar.Wave(obj);

#### Bar chart Wave2

This effect is much the same as the previous, except that this effect uses the Javascript 1.8.5 .bind() method, so is slower in browsers that don't support it natively.

Note:

Some features of OfficeExcel that use extra processing (eg the 3D effect) will cause this effect to have a slow frame rate.

    OfficeExcel.Effects.Bar.Wave2(obj);

#### Fuel chart Grow

This effect gradually increases the indicated value until it reaches the correct value.

    OfficeExcel.Effects.Fuel.Grow(obj);

Note: In some browsers (particularly Chrome 15) the icon causes the canvas to flicker. To stop this you must get rid of the image, which you can do by setting chart.icon to null.

#### Slide out

This effect slides the whole canvas out. One potential use would be to slide the canvas out and then slide another canvas with a different chart in. You can specify that the canvas slides out to by using the second argument as shown below.

    OfficeExcel.Effects.jQuery.Slide.Out(obj, {'to': 'bottom'});

#### Slide in

This effect slides the whole canvas in. As mentioned above you could this effect with the Slinde Out effect to create a slideshow.

    OfficeExcel.Effects.jQuery.Slide.In(obj, {'from': 'right'});

#### Unfold

This effect "unfolds" the line from the origin, gradually increasing the X (and/or Y) values. There's also an example of a combined Bar/Line chart with the Bar chart Grow, the Fade and the Line chart Unfold effects on the combined charts page.

    OfficeExcel.Effects.Line.Unfold(obj);

#### UnfoldFromCenter

This effect "unfolds" the line from the center, gradually increasing or decreasing the Y values as appropriate.

    OfficeExcel.Effects.Line.UnfoldFromCenter(obj);

#### FoldTocenter

This effect "folds" the line to the center, gradually increasing or decreasing the Y values as appropriate. In effect the opposite of the "unfold" effect.

    OfficeExcel.Effects.Line.FoldToCenter(obj);

#### Line chart Trace

This effect gradually traces the line across the chart - slowly revealing it in full. Not all Line chart options work with this effect.

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

#### Rose chart Grow

This effect gradually increases the radius and the radius of each segment. It is not available with non-equi-angular Rose charts.

    OfficeExcel.Effects.Rose.Grow(obj);

#### Rose chart Explode

This effect gradually increases the chart.exploded property of the Rose chart. Combining it with the Implode effect could make an effective transition to a new chart.

    OfficeExcel.Effects.Rose.Explode(obj, {'frames': 60});

#### Rose chart Implode

This effect gradually decreases the exploded factor of the chart. Combined with the above Exploded effect could make an effective transition to a new chart.

    OfficeExcel.Effects.Rose.Implode(obj, {frames: 60});

#### Odometer Grow

This effect gradually increase the value of the Odometer until it reaches the desired value. The second argument is not used, but the third can be a Javascript function and will be called when the animation is finished.

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

Warning: Note that disabling tickmarks can significantly increase the Grow animation frame rate (particularly in Chrome 15). You can do this with obj.Set('chart.tickmarks', false);, optionally replacing them with coloured bands (as above) with obj.Set('chart.tickmarks.highlighted', true);.

#### Meter Grow

This effect gradually increases the value of the Meter until it reaches the desired value. You can optionally specify an object map as the second argument of which the only option is frames - allowing to specify the number of frames in the animation. More frames = longer animation. The animation is set to use a frame rate of roughly 60 frames a second.

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

#### HBar Grow

This effect gradually increase the values of the HBar until it reaches the desired value.

    OfficeExcel.Effects.HBar.Grow(obj);

#### Gauge Grow

This effect gradually increases the indicated value until it is correct. It's also shown on the Gauge chart example page. By constantly updating the Gauge (with some AJAX for example) you could make a control panel of sorts.

    OfficeExcel.Effects.Gauge.Grow(obj);

#### Radar Grow

This effect gradually increases the magnitude of the Radar chart, growing outwards from the center. Multiple data sets are supported.

    OfficeExcel.Effects.Radar.Grow(obj);

#### Waterfall Grow

This effect gradually Grows the waterfall chart in both X and Y respects.

    OfficeExcel.Effects.Waterfall.Grow(obj);

#### Gantt Grow

This effect gradually Grows the Gantt chart in the respect of the X size of the bars.

    OfficeExcel.Effects.Gantt.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 .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 OfficeExcel API function OfficeExcel.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.