Field Summary

Method Summary

Usage:

// set once at beginning of program to change engine default setting.
ZigoEngine.DURATION = .5;

Usage:

// Example with a style from PennerEasing
ZigoEngine.register(PennerEasing);
ZigoEngine.EASING = 'easeInOutExpo';
 
// or - Alternate example with an mx style
import mx.transitions.easing.Elastic;
ZigoEngine.EASING = Elastic.easeOut;

Usage:

            ZigoEngine.OUTPUT_LEVEL = 2;
            
            <ul>
            <li>0 = no traces,</li> 
            <li>1 = normal errors & warnings</li>
            <li>2 = additional output</li>
            </ul> 

Usage:

// set once at beginning of program to change engine default setting.
ZigoEngine.ROUND_RESULTS = true;

Usage:

// set once at beginning of program to change engine default setting.
ZigoEngine.SKIP_LEVEL = 2;

No-duration tweens:
Tweens with a 0-second duration set the property immediately at the time of the tween call, or after any delay.
This behavior has advantages and disadvantages. It is recommended that you purposefully use 0-second tweens to set properties that are handled by the engine at any time in your program, since this will effectively stop any potentially running tweens on that property. (Trying to set a property while it is being tweened usually has no effect.) However in some dynamic programs you may want tweens that end up having no duration to also skip their delay and/or callbacks and events - this can be controlled with SKIP_LEVEL.

No-change tweens:
Tweens at times end up being generated that affect no visual change. Normally the ZigoEngine operates under its legacy behavior, which is to run such tweens regardless. This can be good (the program's sequence will continue on a schedule) or bad (the tween is essentially invisible and will fire callbacks and events on update and end, which may cause confusion). In some cases you may want to skip past tweens that don't do anything visually.

The SKIP_LEVEL default, as well as the per-tween skipLevel parameter (see doTween) enable you to control the engine's behavior in these situations more accurately:

• 0= Default.
  No-change tweens are run with their full duration, delay, and callbacks/events. No-duration tweens set the property and execute all callbacks and events immediately or after a delay.
• 1= Skip no-change tweens.
  Tweens that affect no change are discarded (both delay and duration are ignored). Callbacks/events are fired immediately. No-duration tweens ignore delay and set properties immediately.
• 2= Do not fire events or callbacks for no-change or no-duration tweens.
  No-change tween calls are entirely ignored. No-duration tweens ignore delay and set properties immediately.

To review what property tweens were successfully added, doTween returns a formatted list.

Usage:

// set once at beginning of program to change engine default setting.
ZigoEngine.TIME_MULTIPLIER = .5; // run all tweens at double-speed.

(advanced) Note that for more complex debugging of Fuse sequences you may want to set this property inline during the sequence. Example:

var testMode:Boolean = true;
function setTimeMultiplier(mult:Number):Void {
	if (testMode==true) ZigoEngine.TIME_MULTIPLIER = mult;
}
var f:Fuse = new Fuse();
f.scope = this;
// start sequence skipping through all tweens..
f.push({ func:setTimeMultiplier, args:0 });
// later in sequence return to normal speed..
f.push({ func:setTimeMultiplier, args:1 });
// etc.

Usage:

trace(ZigoEngine.VERSION); // if the version is incorrect, clear your ASO cache.

Usage:

These events are special in that they are dispatched directly by the ZigoEngine class, unlike target-events such as onTweenEnd (see: ZManager for more info).

The "onTweenAdd" event is fired when any doTween call is made, and passes the final parameters that will be sent to the internal ZManager instance in the following order:

• An array of tween targets
• An array of property strings generated by the ZManager.paramsObj method.
  Note: _scale and _size are split into movieclip properties, and duplicate properties are stripped, with the exception of overlapping _fade / _alpha and overlapping color-transform tweens.
• A corresponding array of tween end-values for each validated property
• A validated numerical tween duration in seconds
• A valid easing function
• A validated numerical delay in seconds
• A specially-formatted and validated callback object generated by the FuseKitCommon.parseCallback method.

var myListener:Object = {
    onTweenAdd:function(targets:Array, props:Array, endvals:Array, 
                        seconds:Number, ease:Function, 
                        delay:Number, callback:Object):Void {
        trace("ZigoEngine is adding a tween:");
        trace(" -targets:"+targets.join(","));
        trace(" -props:"+props.join(","));
        trace(" -endvals:"+endvals.join(","));
        trace(" -seconds:"+seconds);
        // (easing function is never undefined)
        trace(" -delay:"+delay);
        trace(" -has callback:"+Boolean(callback.start.f!=null 
                                        || callback.upd.f!=null 
                                        || callback.end.f!=null));
    }
};
ZigoEngine.addListener(myListener);

The "onTweenInterrupt" event is fired in the following situations, and passes several additional parameters including "during" which can provide a clue as to which situation caused the interruption.

• Another tween call overwrote one or more property tweens in progress. during = "add".
• A removeTween call stopped one or more tweens in progress. during = "remove".
• A target goes missing, for instance if a MovieClip was removed during a tween, or a target is deinitialized from the engine before its tweens complete. during = "update".

This ensures the event is fired even when targets go missing and are thus unable to dispatch the event. To aid in tracking targets in that situation, the internal __zigoID__ property for each target is also passed in the event object. Any initialized/tweening target contains this read-only property, making it possible to advance-query then later identify targets after they're removed. Missing targets can be further identified by the "target" parameter of the event object (normally a reference to the actual tween target), which will be sent as a string like [MISSING:"clip1_mc"].

var myListener:Object = {
	onTweenInterrupt:function(o:Object):Void {
		trace("Interruption detected:");
		trace(" -during cycle:"+o.during);
		trace(" -target:"+o.target);
		trace(" -target id:"+o.__zigoID__);
		trace(" -properties interrupted:"+(o.props).toString());
	}
};
ZigoEngine.addListener(myListener);
ZigoEngine.doTween(my_mc,"_alpha",0,2);

// click the mouse during the tween to receive the event.
function onMouseDown():Void {
	my_mc.removeMovieClip();
}
  

Parameters:

handler

the function or object that should be called

Parameters:

target

One or more targets to initialize, or nothing/null to deinitialize base prototypes (for example to undo simpleSetup)

See also:

initialize

Parameters:

targets		Tween target object or array of target objects
methodName		The shorcut as a string, such as "alphaTo", followed by parameters that follow that shortcut's format.

Returns:

A comma-delimited string of props successfully added. When multipe targets were passed, a pipe-delimited series is returned to enable verification of individual properties per target.

Parameters:

targets		Tween target object or array of target objects (All properties listed in the following parameter are tweened on all targets specified.)
props		String like "_x", comma-delimited list of properties like "_x,_y", or Array of properties like ["_x","_y"]. The engine accepts any existing property in the target including custom variables, and the following special properties: _bezier_ Object {x:,y:,controlX:,controlY:} generates a curved motion path. Relative (string) values supported for all parameters Only two properties are needed to tween a curve Example, slides right / arcs up: ZigoEngine.doTween(clip1, "_bezier_", {x:"100",controlY:"-50"}); _brightness -100=black, 0=normal, 100=white _brightOffset Burn effect. -100=black, 0=normal, 100=white _colorReset 100 = fully restores target's colors to normal. _colorTransform Generic object in Flash7 transform format: {ra:,rb:,etc.} _contrast 0=gray, 100=normal, 200=high-contrast, higher=posterized _fade Like _alpha + _visible. Typically used with 0 or 100 values. Visibility turned off when tween ends if value is under 50 Visibility turned on when any _fade tween starts _frame Tweens a target MovieClip's timeline to a frame, with easing. _invertColor 100 = Photo-negative effect _scale Sets _xscale and _yscale to the same value. _size Sets _width and _height to the same value. _tint Accepts various formats: 0x000000 and "#000000" hex formats null (full color reset) Object with tint & percent properties: {tint:Number/null/hexString, percent:Number/String}. _tintPercent Value range 0-100 When FuseFMP is registered, a large number of BitmapFilter properties are tweenable: Blur_blurX, etc. Format follows the convention short-filtername+"_"+filter property.
endvals		tween end-value or Array of corresponding end-values. A single end-value can be used with multiple properties. Accepts various formats: Number A normal absolute end-value. Tweening _x to 10 in the main timeline moves it to 10px from the left edge of the stage. String - Relative values: Passing a string version of a number like "10" or "-10" calculates end-value as relative to the start position of the tween. Examples: Tweening _x to "10" moves the clip 10px to the right of its current position. Tweening _rotation to a negative string value like "-90" affects a counter-clockwise spin. Bezier, tint, or color-transform object See _bezier_, _colorTransform, _tint properties above. Multi-value Object or Array - (Advanced) A new feature is the ability to directly tween multiple values in an Object or Array. Note that like any custom variables these objects must exist prior to tweening and have their properties set to numerical values in advance. var myObj:Object = {x:0,y:0,z:0}; ZigoEngine.doTween(this, "myObj", { x:1, y:2, z:3 }); Note also that because this parameter already accepts an Array for multiple end-values, you must wrap it in a second Array: var myArray:Array = [ 0, 0 ]; ZigoEngine.doTween(this, "myArray", [[10,20]]); Colors Array - (Advanced) Tweening a generic array of color values can help with situations like tweening the properties of a gradient fill that's redrawn on tween update. Any array whose name contains 'colors' (case is ignored) will be handled by the engine as an array of color values. Note that the internal colortransforms are not applied to any target, simply updated within the array. Example: ZigoEngine.doTween(this, "myColors", [[ 0x000000, 0xFFFFFF ]], 1, null, 0, { scope:this, updfunc:'redrawGradient' }); (advanced) Example of tweening a Matrix object to move and skew a clip (Flash 8 required): import com.mosesSupposes.fuse.*; import flash.geom.Matrix; import flash.geom.Transform; ZigoEngine.register(PennerEasing); var myMatrix:Matrix = new Matrix(); var boxTrans:Transform = new Transform(box); function applyMatrixTrans():Void { boxTrans.matrix = myMatrix; } ZigoEngine.doTween( this, "myMatrix", {a:.5, c:.5, tx:200 }, 1, 'easeOutBounce', 0, {updfunc:applyMatrixTrans});
seconds		tween duration. If nothing is passed, defaults to ZigoEngine.DURATION.
ease		Accepts a number of formats based on which features are registered: function - like mx.transitions.easing.Strong.easeInOut shortcut-string - "easeInOutQuint" or any other function name from PennerEasing Array generated by the Custom Easing Tool. (This special panel is installed into Flash when you install the Fuse Kit v2.1 or later MXP extension). Note that the CustomEasing class must be registered to use this feature. null or nothing - defaults to ZigoEngine.EASING if set, or PennerEasing.easeOutQuint, which is hardcoded in the engine as a default fallback.
delay		seconds to wait before performing the tween. Start callback and onTweenStart event are fired at end of delay.
callback		function, string, or object The kit tries to parse callbacks in many formats. Note that for callbacks to execute successfully in many cases it is crucial that a "this" scope is defined in which to locate and fire the function. Although the engine often successfully locates your callbacks, the recommended option is Callback Object, which is the most stable and flexible, demands the least parsing, and allows you to most clearly define scope, as well as providing additional tween options. Function ZigoEngine.doTween(mc,"_x",100,1,"linear",0, myCallback); Reference: myCallback String: "myCallback" Inline: function(){ ... } Delegate: mx.utils.Delegate.create(....) - adds scope Easyfunc String (Shortcuts must be registered to use this feature) ZigoEngine.doTween(mc,"_x",100,1,"linear",0, "this.myCallback(true);"); example: "trace('The tween is finished');" Supports complex scope and many datatypes for argument params: "myscope.myscope.myfunc(true,1,'hello',{paramA:1,paramB:false,[0,1],null);" You may also use easyfunc strings in callback objects (below) for start, update and end callbacks. Limitations: Easyfunc strings are not a good option for class authoring. They work well when coding in frames of the _root timeline and enhance the Shortcuts paradigm. When a callback resides in a frame of a subclip's timeline, the easyfunc string should contain an absolute path to the function. For instance if clip1 exists in the _root timeline and houses the function myCallback, use "clip1.myCallback();". A somewhat impractical workaround for class authors is to set a local reference like var t:MyClass=this; preceding an easyfunc like "t.myMethod();", which exploits scope-chain during eval. Again, Callback Objects are recommended for OO coders. Callback Object ZigoEngine.doTween(clip1,"_x","100",1,"easeOutQuad",0, {scope:this, func:"myCallback", args:true}); ZigoEngine.doTween(clip2,"_x","100",1,"easeOutQuad",0, { cycles:2 }); // yoyo back once func Function, string name of function, or Easyfunc string like "myClip.doSomething(true);" (Shortcuts must be registered to use the Easyfunc feature.) scope The "this" object in which to locate and fire the callback. Not always required but recommended if the engine cannot locate the callback or fires the wrong function. args One argument or an array of arguments to pass to the func callback. startfunc Callback fired after any delay and as tween is starting. Supports various formats - see func above. startscope Specific scope for the startfunc callback. If not defined, the scope property will be used. startargs One argument or an array of arguments to pass to the startfunc callback. updfunc Callback fired on engine pulse as the tweens in the action are updated. Accepts various formats - see func above. updscope Specific scope for the updfunc callback. If not defined, the scope property will be used. updargs One argument or an array of arguments to pass to the updfunc callback. Additional callback object parameters cycles Tweens back and forth between start and end. 0 or "LOOP" = infinite cycles, default = 1, 2 or more to specify cycles. skipLevel 0,1, or 2. An advanced behavior setting for cases where tweens fail. See SKIP_LEVEL for details. Including this paramter in a callback object overrides the engine default on a per-tween basis. extra1 Optional fifth parameter sent to easing method. Elastic easing amplitude or Back easing overshoot. extra2 Optional sixth parameter sent to easing method. Elastic easing period. roundResults Overrides the class setting ROUND_RESULTS for an individual tween. Useful for instance, if the class default is true but you need to execute a tween such as DropShadow_alpha which requires a 0-1 range. easyfunc Removed from kit. func, startfunc, updfunc parameters now accept easyfunc strings (see func above).

Returns:

A formatted string:
The engine reports which properties have been added to its active tween list by returning a comma-delimited string of just the properties that were successfully added, such as "_x" or "_x,_y". These may occasionally differ from what was tweened, such as "_width,_height" when "_size" was tweened.

If multiple targets are passed to the engine, a pipe-delimited series of properties is returned in target order, which enables granular review of whether specific properties for each target.

var results:String = ZigoEngine.doTween([clip1,clip2,clip3],"_scale",100,null,0,{skipLevel:1});
// results: "_xscale,_yscale||_xscale,_yscale"
// because clip2's scale was already set to 100 and the skipLevel is set to skip no-change tweens.

Usage:

ZigoEngine.doTween(clip1, "_x, _xscale, _alpha", ["100", 200, 0], 1, "easeInOutExpo");
// during tween, fast-forward just the slide and scale but allow the fade-out to run:
ZigoEngine.ffTween(clip1, "_x, _scale");
 
// fast-forward all tweens in multiple targets
ZigoEngine.ffTween([clip2,clip3,clip4]);

Parameters:

targs		a single target object, array of targets, or FuseKitCommon.ALL for every active target
props		a property string, array of property strings, null or nothing for all props, FuseKitCommon.ALLCOLOR for any active color transform
suppressEndEvents		if true is not passed, engine will fire 'onTweenEnd' event and any end-callbacks associated with the tween

Parameters:

targOrTransObj

target object or Flash7-style color-transform object with props like ra, etc.

Returns:

object may contain props brightness, brightOffset, contrast, invertColor, tint, tintPercent, and tintString

Parameters:

type		String "brightness", "brightOffset", "contrast", "invertColor", or "tint"
amt		Percentage, can be negative in some cases
rgb		For "tint", a color value in 0x000000 or "#000000" format

Returns:

numeric depth in _root

Parameters:

targ

target tween passed to determine if active, or FuseKitCommon.ALL for every active target

Returns:

number of active tweens, which may be paused or playing

Returns:

Number set using setUpdateInterval, or undefined if unset.

See also:

setUpdateInterval

Parameters:

target

One or more targets to initialize.

See also:

deinitialize

Parameters:

targ		a single target object to test
prop		a specific property string

Returns:

true if a matching active tween is found, which may be paused or playing

Parameters:

targ

Object to lock

Returns:

locked value

Usage:

if (ZigoEngine.isTweenPaused(clip1,"_alpha")==true) { ... }

Parameters:

targ		a single target object to test
prop		props a property string, null or nothing for any property, FuseKitCommon.ALLCOLOR for any active color transform

Returns:

paused value

Usage:

Accepts only one target at a time.

FuseKitCommon.ALL is not accepted by lockTween, because that would only affect targets currently being tweened in the engine. (In a case where you want to stop or pause all running tweens use pauseTween(FuseKitCommon.ALL) or removeTween(FuseKitCommon.ALL). The lockTween method is used to preset targets that usually are not currently being tweened in the engine. For more complex scenarios you should build an array of targets you need to affect, then use a for-loop to call the method on each one individually.

// example of how you could manage a block of targets in your program with lock/unlock
var lockableTargs:Array = [clip1,clip2,clip5];
function toggleTweenLock(setLocked:Boolean):Void {
	for (var i:String in lockableTargs) ZigoEngine.lockTween(lockableTargs[i], setLocked);
}

Parameters:

targ		Object to lock
setLocked		locked value

See also:

pauseTween, removeTween

Usage:

ZigoEngine.doTween(clip1, "_x, _xscale, _alpha", ["100", 200, 0], 1, "easeInOutExpo");
// during tween, pause just the slide and scale but allow the fade-out to run:
ZigoEngine.pauseTween(clip1, "_x, _scale");
 
// pause all engine tweens in the swf
ZigoEngine.pauseTween(FuseKitCommon.ALL);

Parameters:

targs		a single target object, array of targets, or FuseKitCommon.ALL for every active target
props		a property string, array of property strings, null or nothing for all props, FuseKitCommon.ALLCOLOR for any active color transform

Parameters:

classReference

Pass any of the following classes (all are optional): Shortcuts Enables doShortcut, 'easyfunc' callback parsing, and the option to copy / remove shortcuts on any target or prototype manually using initialize. See Shortcuts PennerEasing Enables shortcut strings like "easeOutQuad" to be used with the engine. See PennerEasing Fuse Enables Fuse for animation sequencing. Note that if animation won't be sequenced you do may simply import and use Fuse without ZigoEngine. See Fuse FuseFMP Enables shortcut strings like DropShadow_distance to be tweened in the engine. See FuseFMP FuseItem Enables Fuse-style Object Syntax to be used with the ZigoEngine.doTween. Note that Fuse does not need to be registered to use this feature. See FuseItem

Parameters:

handler

the function or object that should be called

Usage:

// stop any tweens running in clip0
ZigoEngine.removeTween(clip0);
 
ZigoEngine.doTween(clip1, "_x, _xscale, _alpha", ["100", 200, 0], 1, "easeInOutExpo");
// during tween, kill off just the slide and scale but allow the fade-out to run:
ZigoEngine.removeTween(clip1, "_x, _scale");
 
// kill all tweens in multiple targets
ZigoEngine.removeTween([clip2,clip3,clip4]);

The onTweenInterrupt event is fired by the engine when this method is used (see addListener for more info).

Parameters:

targs		a single target object, array of targets, or FuseKitCommon.ALL for every active target
props		a property string, array of property strings, null or nothing for all props, FuseKitCommon.ALLCOLOR for any active color transform

Usage:

ZigoEngine.resumeTween(clip1);
 
// resume all engine tweens in the swf
ZigoEngine.resumeTween(FuseKitCommon.ALL);

Parameters:

targs		a single target object, array of targets, or FuseKitCommon.ALL for every active target
props		a property string, array of property strings, null or nothing for all props, FuseKitCommon.ALLCOLOR for any active color transform

Usage:

ZigoEngine.doTween(clip1, "_x, _xscale, _alpha", ["100", 200, 0], 1, "easeInOutExpo");
// during tween, rewind just the slide and scale but allow the fade-out to run:
ZigoEngine.rewTween(clip1, "_x, _scale");
 
// rewind and pause all tweens in several targets
ZigoEngine.rewTween([clip2,clip3,clip4], null, true);
 
// You may not want start callbacks and/or events to re-fire on rewind.
// These can be suppressed using the 4th parameter as in this example.
var listenerObj:Object = new Object();
listenerObj.onTweenStart = function(o:Object):Void {
	trace(o.target+" start Event, props started: "+o.props);
};
ZigoEngine.initialize(clip5); // prepares clip to add a listener
clip5.addListener(listenerObj);
ZigoEngine.doTween(clip5, "_x", "100", 3, "easeInOutBack", 0,
						{startfunc:function(){trace("Start Callback!");}});
function onMouseDown() {
	// click the stage to restart the animation before it ends.
	// the events are not refired.
	ZigoEngine.rewTween(clip5, null, false, true);
}

Parameters:

targs		a single target object, array of targets, or FuseKitCommon.ALL for every active target
props		a property string, array of property strings, null or nothing for all props, FuseKitCommon.ALLCOLOR for any active color transform
pauseFlag		true to rewind-and-pause
suppressStartEvents		if true is not passed, engine will refire 'onTweenStart' event and any start callbacks associated with the tween

Parameters:

targetObj		MovieClip or target to alter
type		String "brightness", "brightOffset", "contrast", "invertColor", or "tint"
amt		Percentage, can be negative in some cases
rgb		For "tint", a color value in 0x000000 or "#000000" format

Parameters:

depth

If null or nothing passed the beacon clip is placed at depth 6789, but a depth of 0 will be more convenient if you'll be using depth management in _root.

Parameters:

time

Pulse duration in milliseconds, or null/undefined to return to an frame-based pulse.

Parameters:

shortcutsClass

It is madadory to pass the Shortcuts class during this call! You may additionally pass any of the following classes (all are optional), as in the way PennerEasing is added above. PennerEasing Enables shortcut strings like "easeOutQuad" to be used with the engine. See PennerEasing Fuse Enables Fuse for animation sequencing. Note that if animation won't be sequenced you do may simply import and use Fuse without ZigoEngine. See Fuse FuseFMP Enables shortcut strings like DropShadow_distance to be tweened in the engine. See FuseFMP FuseItem Enables Fuse-style Object Syntax to be used with the ZigoEngine.doTween. Note that Fuse does not need to be registered to use this feature. See FuseItem

Usage:

// jump to halfway through a 2-second tween
ZigoEngine.skipTweenTo(1, clip1);

Parameters:

seconds		amount of time within the tween duration to jump to (for instance, in a 1.5-second tween, .75 jumps to the halfway point).
targs		a single target object, array of targets, or FuseKitCommon.ALL for every active target
props		a property string, array of property strings, null or nothing for all props, FuseKitCommon.ALLCOLOR for any active color transform