Animation Style Type Parameters

You are viewing documentation for an older version. For current documentation - click here.

One of the best things about FusionCharts XT is the animated charting sequences that users get to relish. By default, FusionCharts XT animates only the dataplot (columns, bars, lines etc.). However, FusionCharts XT does not limit your imaginations just there.

The live chart shown below shows a very basic animation on the columns. In case you missed it you can reload the animation clicking on the button below saying - "Click here to animate the chart above".

The chart is supposed to load here. If you are unable to see the chart here and can see this message, please check Basic Troubleshooting page.

Note: In JavaScript charts, customized animation styles are not available.

Using the Animation Style Type, you can virtually animate each and every Object on the chart. You can define custom animations and apply them to various objects of the chart.

Each chart object has a list of supported animation properties that can be set through Animation Style Type. Before we get to the parameters supported by the animation style type, let us quickly glance through the properties of chart objects that we can animate using Animation Style Type.

The animation style type helps you animate the following properties of chart objects:

Property	Description
_x	Helps animate the x position of the given chart object.
_y	Helps animate the y position of the given chart object.
_xScale	Using this property, you can animate the x-scale (horizontal scale) of the given chart object.
_yScale	Like xScale, this animates the y-scale.
_alpha	Helps alpha transition (transparency fading) animation effect.
_rotation	Helps you animate the pies and doughnuts in circular motion.

Not all parameters can be applied to all chart objects. For example, text fields cannot be x-scaled or y-scaled nor does the rotation effect apply to them. Similarly, the horizontal div lines do not support y-scaling and x-shifting. The list of animation parameters for each chart object is given in the Chart Specification sheet of the respective chart.

Multiple animations in combination or multiple animations in sequence can also be applied to any chart object. For example, you can opt to y-scale and alpha-fade the data plot (combination animation) or you might go for x-scale first and then y-scale (sequential animation).

Let us now get to the attributes that Animation Style Type exposes to help us control the functionalities:

Attribute	Description
param	This attribute lets you specify the property of chart object which you want to animate, for example, _x, _y, _xscale etc.
start	The start value of animation, for example, if you are animating the dataplot for fade in alpha effect, the start value of alpha will be 0.
duration	Using this, you can control the duration of animation in seconds.
easing	This attribute lets you specify the pattern of animation easing. Valid values are "elastic", "bounce", "regular", "strong" or "none".

For the Animation Style Type, except Easing, all the above attributes are mandatory.

Before getting to detailed explanations, let us quickly cruise through a quick animation sample. Let us try and animate our canvas so that it scales up after the chart is loaded.

To do so, we first need to define our custom style. Since scaling up involves simultaneous increment of both _xScale and _yScale, we'll now need to define two animation styles and then apply them to Canvas Object. The style definition goes as under:

XML
JSON

<styles>
    <definition>
        <style name='MyXScaleAnim' type='ANIMATION' duration='1' start='0' param="_xscale" />
        <style name='MyYScaleAnim' type='ANIMATION' duration='1' start='0' param="_yscale" /> 
    </definition>
   ... More XML Here ...
</styles>

"styles":{
      "definition":[{ "name":"MyXScaleAnim", "type":"ANIMATION", "duration":"1", "start":"0", "param":"_xscale" },
                    { "name":"MyYScaleAnim", "type":"ANIMATION", "duration":"1", "start":"0", "param":"_yscale" }]
        
   ... More JSON Here ...
    }

In the above code, we name the two styles as MyXScaleAnim and MyYScaleAnim with their param (animation parameter) as _xscale and _yscale respectively. We set start value as 0, we want the canvas to scale up from 0 to 100 (remember that scales are always from 0-100 in FusionCharts XT). We also specify the duration as 1 for the animation sequence.

To apply this animation style to canvas, the following code is used:

XML
JSON

<styles>
... More XML Here ....
     <application>
         <apply toObject='Canvas' styles='MyXScaleAnim,MyYScaleAnim' />
     </application>
</styles>

 "styles":{
... More JSON Here ...
      "application":[{ "toobject":"Canvas", "styles":"MyXScaleAnim,MyYScaleAnim" }]
    }

If you run the above code against a Single-series axis chart, you will see that the canvas scales up from 0 size to full size, before the data is animated and rendered. Bingo! Exactly what we needed! Let us move on to the attributes in details now.

The param attribute specifies the property of chart object, which is to be animated. As earlier discussed, it can take one of the following values, depending on the chart object:

_x
_y
_xScale
_yScale
_alpha
_rotation

We reiterate that not all chart Objects support all the above properties. Please refer to the Chart Specification Sheet for the given chart to get the list of supporter animation parameters for each chart object.

In our above example, where we were scaling the canvas from 0 to 100, we had set the start value of animation to 0, as we want the canvas to scale from 0 to 100. You always need to set a start value for any animation style. The end value is decided by FusionCharts XT based on the chart object and animation parameter.

For example, if you want to animate the y position of div lines from 0 to their final position (which is within the canvas), you need to set start position to 0. But since you do not know the end position of individual div line, it's automatically set by FusionCharts XT.

Similarly, if you want to animate the div lines y position for a chart, whose height is 500 pixels, from bottom to the respective final position, you'll need to set start position as 500. The end position again will be decided by FusionCharts XT.

Often, you might want to specify the start x/y position for the animation as the start/center/end position of the canvas or chart. For example, if you want to animate the y property of div lines from canvas top to their respective final position, you will need to experiment with a lot of y values before you can finally get the start y position of canvas. This is because the canvas start position is dynamically calculated at run-time and it depends on a lot of factors like captions, sub captions, chart padding, margins etc.

FusionCharts XT uses Macros to bail you out of this trouble. Macros are pre-defined variables which assume values at run time. For example, $canvasStartY represents the start y position of the canvas, and it assumes a value at run-time only. So, if you need to animate your div lines' y position from canvas start Y to their final actual positions, all you need to do is:

XML
JSON

<style name='DivYAnim' type='ANIMATION' duration='1' start='$canvasStartY' param="_y" />

 "definition":[{ "name":"DivYAnim", "type":"ANIMATION", "duration":"1", "start":"$canvasStartY", "param":"_y" }]

FusionCharts XT, at run-time, will automatically calculate and assign the value for this macro and you will see the animation sequence starting from start Y Position of canvas. So, now even if you resize the chart or opt to show or hide captions or change margins, you never need to keep a tab on the y position of canvas. FusionCharts XT does that for you.

FusionCharts XT supports the following Macro values for Animation Style Type:

$chartStartX	Chart Start X Position. It is 0 if you are loading the chart in an HTML page. However, if you are loading the chart in another Flash movie, it will take the given X Position.
$chartStartY	Chart Start Y Position. It is 0 if you are loading the chart in an HTML page. However, if you are loading the chart in another Flash movie, it will take the given Y Position.
$chartWidth	Width of the chart.
$chartHeight	Height of the chart.
$chartEndX	End X Position of the chart. Same as width of chart if you are loading the chart in an HTML page.
$chartEndY	End Y Position of the chart. Same as height of chart if you are loading the chart in an HTML page.
$chartCenterX	Center X Position of the chart.
$chartCenterY	Center Y Position of the chart.
$canvasStartX	Canvas Start X Position (from left), that is, x co-ordinate of left side of the canvas.
$canvasStartY	Canvas Start Y Position (from top), that is, y co-ordinate of the top of canvas.
$canvasWidth	Width of canvas.
$canvasHeight	Height of canvas.
$canvasEndX	End X Position of Canvas, that is, x co-ordinate of right side of canvas.
$canvasEndY	End Y Position of Canvas, that is, y co-ordinate of bottom of canvas.
$canvasCenterX	Center X Position of canvas.
$canvasCenterY	Center Y Position of canvas.

Macro names are case-sensitive. As such, you need to make sure that you are providing the macro names in proper case, that is, $canvasstarty will not work and it will log an error in debug window. You will need to correctly specify it as $canvasStartY.

More Example using Macros:

XML
JSON

<style name='LabelsAnim' type='ANIMATION' duration='1' start='$canvasCenterX' param="_x" />
<style name='YValuesAnim' type='ANIMATION' duration='1' start='$canvasCenterY' param="_y" />

 "definition":[{ "name":"LabelsAnim", "type":"ANIMATION", "duration":"1", "start":"$canvasCenterX", "param":"_x" },
               { "name":"YValuesAnim", "type":"ANIMATION", "duration":"1", "start":"$canvasCenterY", "param":"_y" }]

You can also add numeric (integer) values to pre-defined macros to offset the animation when using macros. For example, if you wanted to animate the div lines from 10 pixels above canvas starting Y position, you could use:

XML
JSON

<style name='DivYAnim' type='ANIMATION' duration='1' start='$canvasStartY-10' param="_y" />

 "definition":[{ "name":"DivYAnim", "type":"ANIMATION", "duration":"1", "start":"$canvasStartY-10", "param":"_y" }]

Or, if you wanted to animate from 10 pixels below canvas start position, you could use:

XML
JSON

<style name='DivYAnim' type='ANIMATION' duration='1' start='$canvasStartY+10' param="_y" />

 "definition":[{ "name":"DivYAnim", "type":"ANIMATION", "duration":"1", "start":"$canvasStartY+10", "param":"_y" }]

Currently, FusionCharts XT allows only + (addition) and - (subtraction) operation in Macro expressions.

Easing refers to gradual acceleration or deceleration during an animation. For example, a chart object might gradually increase its speed near the beginning of an animation, but slow down right at the end of the animation before it arrives at a full stop. There are many different equations for the acceleration and deceleration, which change the easing animation accordingly. Easing helps your animations appear more realistic.

FusionCharts XT supports the following easing methods:

Methods	Description
Elastic	Adds an elastic effect that falls outside the transition range at one or both ends. The amount of elasticity is unaffected by the duration.
Bounce	Adds a bouncing effect within the transition range at one or both ends. The number of bounces relates to the duration—longer durations produce more bounces.
Strong	Adds slower movement at one or both ends. This effect is similar to Regular easing, but it is more pronounced.
Regular	Adds slower movement at one or both ends. This feature enables you to add a speeding-up effect, a slowing-down effect, or both.
None	Adds an equal movement from start to end without effects, slowing, or speeding up. This transition is also referred to as a linear transition.

For any of the above easing method, FusionCharts XT provides the easing effect at the end of the transition. For example, if you animate the columns from 0 _yscale to 100 _yscale, you will see that the columns animated very fast in the start (they grow up very soon) but the animation at the end part is slow.

You can use any of the above easing methods for any animation style that you define.