API Documentation | All Packages | All Classes | Index | Frames No Frames |
Class OverwriteManager

Package | com.greensock
Class | public final 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 2011, 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.

Public Properties

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

Public Methods

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

Public Constants

| 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.