com.greensock.OverwriteManager

Package	com.greensock
Class	public class OverwriteManager

OverwriteManager resolves conflicts between tweens and controls if (and how) existing tweens of the same target are overwritten. Think of it as a referee or traffic cop for tweens. For example, let's say you have a button with ROLL_OVER and ROLL_OUT handlers that tween an object's alpha and the user rolls their mouse over/out/over/out quickly. Most likely, you'd want each new tween to overwrite the other immediately so that you don't end up with multiple tweens vying for control of the alpha property. That describes the ALL_IMMEDIATE mode which is the default mode of TweenLite when it is not used in conjunction with TweenMax, TimelineLite, or TimelineMax. This keeps things small and fast. However, it isn't ideal for setting up sequences because as soon as you create subsequent tweens of the same target in the sequence, the previous one gets overwritten. And what if you have a tween that is controling 3 properties and then you create another tween that only controls one of those properties? You may want the first tween to continue tweening the other 2 (non-overlapping) properties. This describes the AUTO mode which is the default whenever TweenMax, TimelineLite, or TimelineMax is used in your swf. OverwriteManager offers quite a few other modes to choose from in fact:

NONE (0):
1. When: Never
2. Finds: Nothing
3. Kills: Nothing
4. Performance: Excellent
5. Good for: When you know that your tweens won't conflict and you want maximum speed.
ALL_IMMEDIATE (1):
1. When: Immediately when the tween is created.
2. Finds: All tweens of the same target (regardless of timing or overlapping properties).
3. Kills: Every tween found
4. Performance: Excellent
5. Good for: When you want the tween to take priority over all other tweens of the same target, like on button rollovers/rollouts. However, this mode is bad for setting up sequences.
This is the default mode for TweenLite unless TweenMax, TimelineLite, or TimelineMax are used in the SWF (in which case AUTO is the default mode).
AUTO (2):
1. When: The first time the tween renders (you can invalidate() a tween to force it to re-init and run its overwriting routine again next time it renders)
2. Finds: Only tweens of the same target that are active (running). Tweens that haven't started yet are immune.
3. Kills: Only individual overlapping tweening properties. If all tweening properties have been overwritten, the entire tween will be killed as well.
4. Performance: Very good when there aren't many overlapping tweens; fair when there are.
5. Good for: Virtually all situations. This mode does the best job overall of handling overwriting in an intuitive way and is excellent for sequencing.
This is the default mode when TweenMax, TimelineLite, or TimelineMax is used in your swf (those classes automatically init() OverwriteManager in AUTO mode unless you have already initted OverwriteManager manually).
CONCURRENT (3):
1. When: The first time the tween renders (you can invalidate() a tween to force it to re-init and run its overwriting routine again next time it renders)
2. Finds: Only tweens of the same target that are active (running). Tweens that haven't started yet are immune.
3. Kills: Every tween found
4. Performance: Very good
5. Good for: When you want the target object to only be controled by one tween at a time. Good for sequencing although AUTO mode is typically better because it will only kill individual overlapping properties instead of entire tweens.
ALL_ONSTART (4):
1. When: The first time the tween renders (you can invalidate() a tween to force it to re-init and run its overwriting routine again next time it renders)
2. Finds: All tweens of the same target (regardless of timing or overlapping properties).
3. Kills: Every tween found
4. Performance: Very good
5. Good for: When you want a tween to take priority and wipe out all other tweens of the same target even if they start later. This mode is rarely used.
PREEXISTING (5):
1. When: The first time the tween renders (you can invalidate() a tween to force it to re-init and run its overwriting routine again next time it renders)
2. Finds: Only the tweens of the same target that were created before this tween was created (regardless of timing or overlapping properties). Virtually identical to ALL_IMMEDIATE except that PREEXISTING doesn't run its overwriting routines until it renders for the first time, meaning that if it has a delay, other tweens won't be overwritten until the delay expires.
3. Kills: Every tween found
4. Performance: Very good
5. Good for: When the order in which your code runs plays a critical role, like when tweens that you create later should always take precidence over previously created ones regardless of when they're scheduled to run. If ALL_IMMEDIATE is great except that you want to wait on overwriting until the tween begins, PREEXISTING is perfect.

With the exception of ALL_IMMEDIATE (which performs overwriting immediatly when the tween is created), all overwriting occurs when a tween renders for the first time. So if your tween has a delay of 1 second, it will not overwrite any tweens until that point.

You can define a default overwriting mode for all tweens using the OverwriteManager.init() method, like:


 
   OverwriteManager.init(OverwriteManager.AUTO);

If you want to override the default mode in a particular tween, just use the overwrite special property. You can use the static constant or the corresponding number. The following two lines produce the same results:


 
   TweenMax.to(mc, 1, {x:100, overwrite:OverwriteManager.PREXISTING});

   TweenMax.to(mc, 1, {x:100, overwrite:5});

OverwriteManager is a separate, optional class for TweenLite primarily because of file size concerns. Without initting OverwriteManager, TweenLite can only recognize modes 0 and 1 (NONE and ALL_IMMEDIATE). However, TweenMax, TimelineLite, and TimelineMax automatically init() OverwriteManager in AUTO mode unless you have already initted OverwriteManager manually. You do not need to take any additional steps to use AUTO mode if you're using any of those classes somewhere in your project. Keep in mind too that setting the default OverwriteManager mode will affect TweenLite and TweenMax tweens.

EXAMPLES:

To start OverwriteManager in AUTO mode (the default) and then do a simple TweenLite tween, simply do:


   
   import com.greensock.OverwriteManager;

   import com.greensock.TweenLite;


   
   OverwriteManager.init(OverwriteManager.AUTO);

   TweenLite.to(mc, 2, {x:300});

You can also define overwrite behavior in individual tweens, like so:


  
   import com.greensock.OverwriteManager;

   import com.greensock.TweenLite;


   
   OverwriteManager.init(2);

   TweenLite.to(mc, 2, {x:"300", y:"100"});

   TweenLite.to(mc, 1, {alpha:0.5, overwrite:1}); //or use the constant OverwriteManager.ALL_IMMEDIATE

   TweenLite.to(mc, 3, {x:200, rotation:30, overwrite:2}); //or use the constant OverwriteManager.AUTO

OverwriteManager's mode can be changed anytime after init() is called, like.


   
   OverwriteManager.mode = OverwriteManager.CONCURRENT;

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

	Property	Defined by
		mode : int [static] The default overwrite mode for all TweenLite and TweenMax instances	OverwriteManager

	Method	Defined by
		init(defaultMode:int = 2):int [static] Initializes OverwriteManager and sets the default management mode.	OverwriteManager

	Constant	Defined by
		ALL_IMMEDIATE : int = 1 [static] Overwrites all existing tweens of the same target immediately when the tween is created	OverwriteManager
		ALL_ONSTART : int = 4 [static] Overwrites all tweens of the same target (regardless of overlapping properties or timing) when the tween renders for the first time as opposed to ALL_IMMEDIATE which performs overwriting immediately when the tween is created.	OverwriteManager
		AUTO : int = 2 [static] Only overwrites individual overlapping tweening properties in other tweens of the same target.	OverwriteManager
		CONCURRENT : int = 3 [static] Overwrites tweens of the same target that are active when the tween renders for the first time.	OverwriteManager
		NONE : int = 0 [static] Won't overwrite any other tweens	OverwriteManager
		PREEXISTING : int = 5 [static] Overwrites tweens of the same target that existed before this tween regardless of their start/end time or active state or overlapping properties.	OverwriteManager

Property detail

mode

property

public static var mode:int

The default overwrite mode for all TweenLite and TweenMax instances

Method detail

init

()

method

public static function init(defaultMode:int = 2):int

Initializes OverwriteManager and sets the default management mode. Options include:

NONE (0):
1. When: Never
2. Finds: Nothing
3. Kills: Nothing
4. Performance: Excellent
5. Good for: When you know that your tweens won't conflict and you want maximum speed.
ALL_IMMEDIATE (1):
1. When: Immediately when the tween is created.
2. Finds: All tweens of the same target (regardless of timing or overlapping properties).
3. Kills: Every tween found
4. Performance: Excellent
5. Good for: When you want the tween to take priority over all other tweens of the same target, like on button rollovers/rollouts. However, this mode is bad for setting up sequences.
This is the default mode for TweenLite unless TweenMax, TimelineLite, or TimelineMax are used in the SWF (in which case AUTO is the default mode).
AUTO (2):
1. When: The first time the tween renders (you can invalidate() a tween to force it to re-init and run its overwriting routine again next time it renders)
2. Finds: Only tweens of the same target that are active (running). Tweens that haven't started yet are immune.
3. Kills: Only individual overlapping tweening properties. If all tweening properties have been overwritten, the entire tween will be killed as well.
4. Performance: Very good when there aren't many overlapping tweens; fair when there are.
5. Good for: Virtually all situations. This mode does the best job overall of handling overwriting in an intuitive way and is excellent for sequencing.
This is the default mode when TweenMax, TimelineLite, or TimelineMax is used in your swf (those classes automatically init() OverwriteManager in AUTO mode unless you have already initted OverwriteManager manually).
CONCURRENT (3):
1. When: The first time the tween renders (you can invalidate() a tween to force it to re-init and run its overwriting routine again next time it renders)
2. Finds: Only tweens of the same target that are active (running). Tweens that haven't started yet are immune.
3. Kills: Every tween found
4. Performance: Very good
5. Good for: When you want the target object to only be controled by one tween at a time. Good for sequencing although AUTO mode is typically better because it will only kill individual overlapping properties instead of entire tweens.
ALL_ONSTART (4):
1. When: The first time the tween renders (you can invalidate() a tween to force it to re-init and run its overwriting routine again next time it renders)
2. Finds: All tweens of the same target (regardless of timing or overlapping properties).
3. Kills: Every tween found
4. Performance: Very good
5. Good for: When you want a tween to take priority and wipe out all other tweens of the same target even if they start later. This mode is rarely used.
PREEXISTING (5):
1. When: The first time the tween renders (you can invalidate() a tween to force it to re-init and run its overwriting routine again next time it renders)
2. Finds: Only the tweens of the same target that were created before this tween was created (regardless of timing or overlapping properties). Virtually identical to ALL_IMMEDIATE except that PREEXISTING doesn't run its overwriting routines until it renders for the first time, meaning that if it has a delay, other tweens won't be overwritten until the delay expires.
3. Kills: Every tween found
4. Performance: Very good
5. Good for: When the order in which your code runs plays a critical role, like when tweens that you create later should always take precidence over previously created ones regardless of when they're scheduled to run. If ALL_IMMEDIATE is great except that you want to wait on overwriting until the tween begins, PREEXISTING is perfect.

Parameters

defaultMode:int (default = 2) — The default mode that OverwriteManager should use.

Returns

int

Constant detail

ALL_IMMEDIATE

constant

public static const ALL_IMMEDIATE:int = 1

Overwrites all existing tweens of the same target immediately when the tween is created

ALL_ONSTART

constant

public static const ALL_ONSTART:int = 4

Overwrites all tweens of the same target (regardless of overlapping properties or timing) when the tween renders for the first time as opposed to ALL_IMMEDIATE which performs overwriting immediately when the tween is created.

AUTO

constant

public static const AUTO:int = 2

Only overwrites individual overlapping tweening properties in other tweens of the same target. TweenMax, TimelineLite, and TimelineMax automatically init() OverwriteManager in this mode if you haven't already called OverwriteManager.init().

CONCURRENT

constant

public static const CONCURRENT:int = 3

Overwrites tweens of the same target that are active when the tween renders for the first time.

NONE

constant

public static const NONE:int = 0

Won't overwrite any other tweens

PREEXISTING

constant

public static const PREEXISTING:int = 5

Overwrites tweens of the same target that existed before this tween regardless of their start/end time or active state or overlapping properties.

API Documentation	All Packages \| All Classes \| Index \| Frames No Frames
Class OverwriteManager	Properties \| Methods \| Constants