Method Summary

Usage:

MANDATORY: Return true or false based on whether the extension should be activated or immediately deleted, for instance if the target is the wrong type. (Use FuseKitCommon.output to throw any related error messages.)

MANDATORY: Tween property MUST exist or be written into the target and MUST be set to the datatype being tweened, such as a valid number (or in some cases an object or array).

Storing the property being tweened is necessary for any extension with more than one property. It is not necessary to store a hard reference to the target object, since all interface methods receive a temporary reference to the target in their arguments.

Tween end-value is passed for special cases like type-checking, normally you may ignore it.

Other events: You may also choose to add an onTweenStart event handler to your extension class, again you do not need to add a listener. Whereas addTween is called just prior to a tween being added to the engine, the onTweenStart event is fired as animation begins, after any delay passed by the user. However do not use an onTweenEnd event, use destroy for final actions, because FuseFX uses onTweenEnd to destroy extension instances.

You do not need to worry about removing conflicting tween properties on the target; this is automated based on the information you provide in defineProperties.

Parameters:

target		The tween target object (not necessary to store a hard reference!)
prop		The tween property which has been pre-verified as one of this extension's keys.
endval		The tween end-value passed by the user (for special cases like type checking)

Usage:

In this hypothetical example an extension called GnarlyFX generates FXProperty instances for each new property. The first parameter is the extension class, the second is the property string, and the third is a comma-delimited conflicts string.

public static var HUE:String = 'hueFX';
public static var BEZIER:String = 'quadBezierFX';
public static var VOLUME:String = 'volumeFX';
 
public function defineProperties() : Array {
	var a:Array = [];
	a.push( new FXProperty(GnarlyFX, HUE, FuseKitCommon.ALLCOLOR) );
	a.push( new FXProperty(GnarlyFX, BEZIER, '_x,_y') );
	a.push( new FXProperty(GnarlyFX, VOLUME, null) );
	return a;
}

Tweenable keys

• We recommend ending keys with "FX" which reminds users of the active extension and helps avoid the following conflicts:
  1. An unrelated property with the same name might exist in the target.
  2. Conflicts might occur with reserved Fuse Kit properties. For example, both "_brightness" and "brightness" are reserved, and will always be tweened by ZigoEngine as Flash-7-Color transforms. (See docs: ZigoEngine.doTween, Fuse constructor)
• Tweenable-property keys should simple but must clearly indicate what they do. A Fuse containing a property called sizeFX would be too vague (size of what?) and somewhat rudely takes over that property from any other extensions, whereas the string textSizeFX allows the developer reading the Fuse action to determine that font size will be affected.
• Keys should not be standard properties like _x or _y. Instead, define differing property names and list _x as a conflict. Your onTweenUpdate handler can then set _x on the target. You cannot redefine a property like _x because ZigoEngine locks the tween over time to its path, so you can't use onTweenUpdate to move the target to a new position. If you truly need an extension to handle pre-existing properties, for instance if you want to extend position tweening and still have bezier tweens work, follow the example class ScreenWrap.
• Each property may have an accompanying 'constant': a public static variable that defines the tweenable string. These do not define the extension's keys though. They are simply an optional convenience for the user. The real keys are the strings the constants point to, and are set in the FXProperty instances. Constants can be simple, since they are directly associated with an extension class whose name is also descriptive.

Conflicts

• Tween engines must avoid "overlapping" tweens, that is two tween properties that try to affect the same change on a target at once.
• In authoring a tweening extension, it is extremely important that you carefully identify where such conflicts might arise. For example, a Flash 8 or higher ColorTransform should pass the constant FuseKitCommon.ALLCOLOR for the conflict string, so the engine will stop processing any regular color-transforms. A Matrix-based extension that positions a clip using translation should set conflicts to "_x,_y". Don't rush this step. Your product needs to meet the expectations of the Kit.
• FuseFX uses the conflict data you provide to automate two processes: First, it removes conflicting tweens from the target when an extension is successfully instantiated. Second, it monitors all tweens added to the engine and kills active extension tweens when the user tweens a conflicting property.

Returns:

An Array of FXProperty instances.

See also:

FXProperty

Usage:

Do not delete or remove the target object during destroy! You are only cleaning up this instance.

Delete any external object references and remove any additional listeners you may have manually added during the extension's lifespan. (Again, do NOT add a listener to the target for onTweenUpdate, FuseFX does this for you.)

If the property was written into the target in addTween and the user doesn't expect it to be a persistent property, it is good practice to delete it from the target here. (In some cases it may be difficult to recreate the final setting on a next tween, in which case you could leave it, then only overwrite it in addTween if it doesn't exist.)

Parameters:

target

The original tween target, which may be missing. Passed in the three primary methods so you can avoid storing a hard reference to tween targets.

Usage:

Do NOT add a listener to the target, FuseFX does this for you.

Parameters:

o

Event object sent by engine containing {target:Object, props:Array}