Package	com.greensock.plugins
Class	public class BezierPlugin
Inheritance	BezierPlugin TweenPlugin Object

• "thru" (the default) - the plugin figures out how to draw the Bezier naturally through the supplied values using a proprietary algorithm. The values you provide in the array are essentially treated as anchors on the Bezier and the plugin calculates the control points. The target's current/starting values are used as the initial anchor. You can define a curviness special property that allows you to adjust the tension on the Bezier where 0 has no curviness (straight lines), 1 is normal curviness, 2 is twice the normal curviness, etc. Since "thru" is the default Bezier type, you don't need to define a type at all if this is the one you want.
• "soft" - the values that you provide in the array act almost like magnets that attract the curve towards them, but the Bezier doesn't typically travel through them. They are treated as control points on a Quadratic Bezier and the plugin creates the necessary intermediate anchors. The target's current/starting values are used as the initial anchor.
• "quadratic" - allows you to define standard Quadratic Bezier data (Quadratic Beziers have 1 control point between each anchor). The array should start with the first anchor, then control point, then anchor, control point, etc. for as many iterations as you want, but obviously make sure that it starts and ends with anchors.
• "cubic" - allows you to define standard Cubic Bezier data (Cubic Beziers have 2 control points between each anchor). The array should start with the first anchor, then 2 control points, then anchor, 2 control points, anchor, etc. for as many iterations as you want, but obviously make sure that it starts and ends with anchors.

While it is most common to use x and y (or left and top) properties for Bezier tweens, you can use any properties (even ones that are function-based getters/setters).

Inside the bezier object, you must define at least a values property, and there are several other optional special properties that the BezierPlugin will recognize. Here is a list of them all:

• values : Array [REQUIRED] - the array of your Bezier values as generic objects. Each object in the array should have matching property names (like "x" and "y"). For example, the array might look like: [{x:100, y:250}, {x:300, y:0}, {x:500, y:400}]
• type : String (default:"thru") - Either "thru", "soft", "quadratic", or "cubic" as described above, indicating how the values should be interpreted.
• timeResolution : Number (default:6) - due to the nature of Beziers, plotting the progression of an object on the path over time can make it appear to speed up or slow down based on the placement of the control points and the length of each successive segment on the path, so BezierPlugin implements a technique that reduces or eliminates that variance, but it involves breaking the segments down into a certain number of pieces which is what timeResolution controls. The greater the number, the more accurate the time remapping but there is a processing price to pay for greater precision. The default value of 6 is typically fine, but if you notice slight pace changes on the path you can increase the timeResolution value. Or, if you want to prioritize speed you could reduce the number. If you use a timeResolution value of 0, no length measurements will take place internally which delivers maximum processing speed, but you may notice changes in speed during the animation.
• curviness : Number (default:1) (only applies to type:"thru") - allows you to adjust the tension on the Bezier where 0 has no curviness (straight lines), 1 is normal curviness, 2 is twice the normal curviness, etc. Use any number, not just integers
• autoRotate : Boolean, Number, or Array (default:false) - to automatically rotate the target according to its position on the Bezier path, you can use the autoRotate feature. If your Bezier is affecting the "x" and "y" (or "left" and "top") properties of your target and you don't need to offset the rotation by a certain amount more than normal, then you can simply set autoRotate:true. Or if you want to offset the rotation by a certain amount (in degrees), you can define a number like autoRotate:90 (adding 90 degrees in this example). Or for more advanced controls, you can define autoRotate as an array. In order to adjust a rotation property accurately, the plugin needs 5 pieces of information:
  1. Position property 1 (typically "x" or "left")
  2. Position property 2 (typically "y" or "top")
  3. Rotational property (typically "rotation")
  4. Number of degrees (or radians) to add to the new rotation (optional - makes it easy to orient your target properly)
  5. Boolean value indicating whether or not the rotational property should be defined in radians rather than degrees (default is false which results in degrees)
  The autoRotate property should be an Array containing these values, like ["x","y","rotation",90*Math.PI/180,true]. And if you need to affect multiple rotational properties (like in 3D tweens where the Bezier is going through x,y,z points which could affect rotationX, rotationY, and rotationZ), you can use an array of arrays, like [["x","y","rotationZ",0,false], ["z","x","rotationY",0,false], ["z","y","rotationX",0,false]]. Note: 3D CSS animations aren't supported yet, but you if you're using a canvas-based framework that recognizes 3D properties, it should certainly be compatible with BezierPlugin.
• correlate : String (default:"x,y,z,left,top,right,bottom,marginLeft,marginTop,marginRight,marginBottom,paddingLeft,paddingTop,paddingRight,paddingBottom") (only applies to type:"thru") - a comma-delimited list of property names whose relative distances should be correlated when calculating the Bezier that travels through the points. Since x, y, z, left, top, etc. are all spacial, it is almost always good to correlate them, but properties like scaleX, scaleY, etc. don't typically need to be correlated. It is rarely necessary to alter the default correlate value, so there's typically no need to even define one at all (let the plugin use its defaults).

IMPORTANT: if you are trying to do a bezier tween of css-related properties, make sure you utilize the CSSPlugin and put your bezier data inside the css object. BezierPlugin is not just for css-related properties - it can handle virtually any property of any object.

//tween the "left" and "top" css properties through the supplied values (notice we put bezier inside the css object and we're passing the array directly to the bezier rather than creating an object with "values" because we're accepting the defaults)
TweenMax.to(document.getElementById("myDiv"), 5, {css:{bezier:[{left:100, top:250}, {left:300, top:0}, {left:500, top:400}]}, ease:Power1.easeInOut});
 
//if we want to customize things, like the curviness and setting autoRotate:true, we need to define the bezier as an object instead, and pass our array as the "values" property
TweenMax.to(document.getElementById("myDiv"), 5, {css:{bezier:{curviness:1.25, values:[{x:100, y:250}, {x:300, y:0}, {x:500, y:400}], autoRotate:true}, backgroundColor:"#f00"}, ease:Power1.easeInOut});

//let's define the type as "soft" instead of using the default "thru"
TweenMax.to(document.getElementById("myDiv"), 5, {css:{bezier:{type:"soft", values:[{x:100, y:250}, {x:300, y:0}, {x:500, y:400}], autoRotate:true}}, ease:Power1.easeInOut});
 
//now we'll do a cubic Bezier and make our target auto rotate but add 45 degrees to the rotation
TweenMax.to(document.getElementById("myDiv"), 5, {css:{bezier:{type:"cubic", values:[{x:100, y:250}, {x:150, y:100}, {x:300, y:500}, {x:500, y:400}], autoRotate:["x","y","rotation",45,false]}}, ease:Power1.easeInOut});

//NON-CSS, generic x/y property tween: animate obj through the points in the array (notice we're passing the array directly to the bezier rather than creating an object with "values" because we're accepting the defaults)
TweenMax.to(obj, 5, {bezier:[{x:100, y:250}, {x:300, y:0}, {x:500, y:400}], ease:Power1.easeInOut});

You can tap into BezierPlugin's Bezier drawing algorithm by passing its bezierThrough() method your array of points/objects and it will spit back and object with all the necessary data, either in Cubic Bezier form or in Quadratic Bezier form so that you could, for example, draw the path using the canvas's drawing API. It also has some useful static cubicToQuadratic() and quadraticToCubic() conversion methods.

Copyright 2008-2012, GreenSock. All rights reserved. This work is subject to the terms in http://www.greensock.com/terms_of_use.html or for Club GreenSock members, the software agreement that was issued with the membership.