GreenSock JavaScript API Docs | All Packages | All Classes | Index | Frames No Frames |
TweenPlugin

Package | com.greensock.plugins
Class | public class TweenPlugin
Inheritance | TweenPlugin Object
Subclasses | BezierPlugin, ColorPropsPlugin, CSSPlugin, CSSRulePlugin, EaselPlugin, RaphaelPlugin, RoundPropsPlugin, ScrollToPlugin

TweenPlugin is the base class for all TweenLite and TweenMax plugins, but generally isn't used directly.

USAGE:

To create your own plugin, extend TweenPlugin and override whichever methods you need (typically `_onInitTween()` and `setRatio()`). To make things easier, we have included a file named `TEMPLATE_Plugin.js` in the plugins directory that serves as a jumping-off point and it has some comments in the code. `_onInitTween()` is called when the tween renders for the first time and `setRatio()` is called on every update and passes a ratio parameter which is typically a value between 0 and 1, and it changes according to the ease). There are a few key concepts to keep in mind:

1. Pass the TweenPlugin constructor a comma-delimited list of property names that the plugin should overwrite, the first of which should be the property name that the plugin intercepts. For example, the ScrollToPlugin handles any tweens of `"scrollTo"` and it also overwrites other concurrent tweens that are handling the "scrollTo" but you may have a ScalePlugin that handles both "scaleX" and "scaleY" properties, thus the comma-delimited list would look like `"scale,scaleX,scaleY"`. The first name in the list must be unique - two plugins cannot handle the same primary property.
2. When a tween that uses your plugin initializes its tween values (normally when it renders for the first time), a new instance of your plugin will be created and its `_onInitTween()` method is called. That's where you'll want to record any initial values and prepare for the tween. `_onInitTween()` should return a Boolean value that essentially indicates whether or not the plugin initted successfully. If you return false, TweenLite/Max will just use a normal tween for the value, ignoring the plugin for that particular tween. For example, maybe your tween only works with DOM elements, so if the target isn't one you could return `false`
3. The `setRatio()` method will be called on every frame during the course of the tween and it will be passed a single parameter that's a multiplier (typically between 0 and 1, according to the ease) describing the total amount of change from the beginning of the tween (0). It is normally zero at the beginning of the tween and 1 at the end, and inbetween it could be any value based on the ease applied (for example, an `ElasticOut` ease would cause the value to shoot past 1 and back again before the end of the tween). So if the tween uses the `Linear.ease`, when it's halfway finished, `setRatio(0.5)` would be called
4. The `_overwriteProps` is an array that should contain the properties that your plugin should overwrite in `"auto"` overwrite mode. For example, an `autoAlpha` plugin could control the `"visible"` and `"alpha"` properties of an object, so if another tween is created that controls the `alpha` of the target object, your plugin's `_kill()` method will be called which should handle killing the `"alpha"` part of the tween. It is your responsibility to populate (and depopulate) the `_overwriteProps` Array. Failure to do so properly can cause odd overwriting behavior.
5. There's a `_roundProps()` method that gets called by the `RoundPropsPlugin` if the user requests that certain properties get rounded to the nearest integer. If you use `_addTween()` method to add property tweens, rounding will happen automatically (if necessary), but if you don't use `_addTween()` and prefer to manually calculate tween values in your `setRatio()` method, just remember to override the `_roundProps()` method if that makes sense in your plugin (some plugins wouldn't need to accommodate rounding, like color plugins, in which case you can ignore the method altogether).
6. If you need to run a function when the tween gets disabled, add an `_onDisable()` method (named exactly that) to your plugin. It will automatically be called when the tween gets disabled (typically when it finishes and is removed from its parent timeline). Same for `_onEnable()` if you need to run code when a tween is enabled. These methods should return a Boolean value indicating whether or not they changed any properties on the target becaues if so (`true`), it helps notify any initting tweens of the same target to re-init. It is very rare that an `_onDisable()` or `_onEnable()` method is necessary, but it can be useful for things like MotionBlurPlugin which must do some very advanced things, hiding the target, changing its alpha to almost 0, etc. only while the tween occurs. If another alpha tween of that same target overwrites an existing motionBlur of the same target, the alpha would be at the wrong value normally, but the if the `_onDisable()` returns `true`, it would force the new tween to re-init AFTER the alpha was fixed inside the `_onDisable()`. Again, this is VERY rare.
7. Please use the same naming convention as the rest of the plugins, like MySpecialPropertyNamePlugin.
8. If you are handling more than one property in your plugin (like RoundPropsPlugin or ShortRotationPlugin), and you're not using `_addTween()` to create property tweens internally, make sure you override the `_kill()` method which will be passed a `vars` parameter with properties that need to be killed (typically for overwriting).

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.

Thu Dec 20 2012, 04:30 PM -06:00