OverwriteManager – control how (and if and when) tweens get overwritten

  • Version: 6.1, Updated 2010-12-20
  • File size added to compressed SWF: About 1kb

Description

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):
    • When: Never
    • Finds: Nothing
    • Kills: Nothing
    • Performance: Excellent
    • Good for: When you know that your tweens won’t conflict and you want maximum speed.
  • ALL_IMMEDIATE (1):
    • When: Immediately when the tween is created.
    • Finds: All tweens of the same target (regardless of timing or overlapping properties).
    • Kills: Every tween found
    • Performance: Excellent
    • 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):
    • 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)
    • Finds: Only tweens of the same target that are active (running). Tweens that haven’t started yet are immune.
    • Kills: Only individual overlapping tweening properties. If all tweening properties have been overwritten, the entire tween will be killed as well.
    • Performance: Very good when there aren’t many overlapping tweens; fair when there are.
    • 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):
    • 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)
    • Finds: Only tweens of the same target that are active (running). Tweens that haven’t started yet are immune.
    • Kills: Every tween found
    • Performance: Very good
    • 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):
    • 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)
    • Finds: All tweens of the same target (regardless of timing or overlapping properties).
    • Kills: Every tween found
    • Performance: Very good
    • 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):
    • 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)
    • 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.
    • Kills: Every tween found
    • Performance: Very good
    • 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.PREEXISTING});
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. OverwriteManager has no effect on TweenNano tweens.

FAQ

  1. I’m trying to use the AUTO overwriting mode, but it’s not working – what am I doing wrong?
    You probably just forgot to call OverwriteManager.init() in your SWF. You only need to do that once by the way. And be sure you’re using the latest version of tweening classes and that you imported the OverwriteManager class too, either with import com.greensock.OverwriteManager; or import com.greensock.*;
  2. What if I set the mode to AUTO, but I have a tween that I’d like to use a different mode for – can I do that?
    Of course. Just use the overwrite property in that tween, like:

    TweenMax.to(mc, 1, {x:100, overwrite:3}); //uses the CONCURRENT mode for this tween even if the OverwriteManager's mode is something different.
    		
  3. Is there a big performance hit when using the AUTO mode?
    Not really. Maybe if you’re starting hundreds of simultaneous tweens with overlapping properties, but you’d probably never notice any difference whatsoever in typical use. If you want the absolute best speed, stick with the ALL_IMMEDIATE or NONE modes.
  4. Where do I get the OverwriteManager class?
    It’s included in all of the tweening downloads. Just click the “Download AS2″ or “Download AS3″ button.

Need help?

Feel free to post your question on the forums. You’ll increase your chances of getting a prompt answer if you provide a brief explanation and include a simplified FLA file (and any class files) that clearly demonstrates the problem.

Donate
Author: Jack Doyle
Copyright 2010, GreenSock (This work is subject to the terms here.)

Comments (17) RSS

Posted by brandy on August 29, 2008

fantastic, thanks!

Posted by AmerSoft on September 2, 2008

You are really wonderful … you keep getting our respect… THANK YOU MAN

Posted by Og2t on September 2, 2008

This is great Jack! I had some many headaches with overwriting different properties on the same object without stopping/resetting others – that should solve it all now! Thanks!

Posted by John Webber on September 2, 2008

My fingers were sore from writing overwrite:false so often. Thanks buddy!

Posted by Chris Kelley on September 5, 2008

Outstanding – I just loaded up the site to double check the documentation on the old overwrite:false stuff and look what you’ve gone and done! Saved me a big headache, -again-.

Thanks, keep up the good work.
Chris

Posted by @ndre on September 5, 2008

Looks like a very welcome addition. Only thing I’m a bit sceptic about after reading the post, is the default setting. If I understand it correctly, the ALL mode is the way that TweenMax (since this is the only class where it is included by default, my concern only applies here) used to work before?

Then, since the default mode is AUTO now, backwards compability is not 100%. If I replace the old classes with the new ones, it could potentially create unwanted results when recompiling my previous projects because properties that I expected to be overwritten when creating a new tween, isn’t…

Or did I misunderstand? :-)

Posted by jack on September 5, 2008

@ndre, you are correct – since AUTO is now the default, there is a possibility that your old stuff won’t work exactly the same way. I weighed the decision to make the default mode AUTO and I realized backwards compatibility might be an issue at the default setting, but I decided to go with AUTO because:

1) It is the most intuitive and prevents confusion. I’ve gotten lots of “bug” reports that weren’t bugs at all – it was just that people expected auto overwriting and didn’t understand the old default behavior of overwriting ALL.

2) If you want to replicate the old default “ALL” mode, it’s super-easy. Simply call OverwriteManager.init(OverwriteManager.ALL); That’s it.

Basically, the benefits seemed to outweigh the risks. If anyone else wants to disagree or share their opinion, let me know. In the end, I think people expect (and are happiest with) the AUTO mode by default. Keep in mind you can control overwriting on an individual basis too – you don’t need to control it with the global OverwriteManager mode setting.

Posted by @ndre on September 5, 2008

Ok, I mostly wanted to get confirmed that it worked the way I thought. I agree that the AUTO mode is the most intuitive, I remember being confused about the overwriting when I first started using TweenMax/Lite. :-)

As long as I know about it, option 2) is no sweat at all. :-)

Posted by Shadow_SB on September 6, 2008

Hi. I’m wondering about consequences of using NONE mode in cases that AUTO was made for… I suppose that this is not good idea but since NONE mode is more efficient it sounds seductive… Generally I don’t use thousands of simultenous tweens, but I do use TweenLite in cpu-stressful projects where performance matters

Posted by jack on September 6, 2008

Shadow_SB, if you’re careful with the way you write your code, feel free to use the NONE mode. You can always use the overwrite special property in individual tweens to accomplish whatever you want. You might also want to do some testing of your own to see how NONE compares with AUTO because you may be very surprised how efficient AUTO mode is. Frankly, I noticed very little difference even when running hundreds of tweens simultaneously. But if you want absolutely maximum performance, NONE or ALL is best. In most projects, however, given the almost imperceptible performance difference and increased convenience, I suspect most developers will appreciate AUTO. The nice thing is that OverwriteManager gives you lots of options.

Posted by chris on October 4, 2008

wow…
you did an amazing job :) thx.. i donate 20 dolars

Posted by RickM on February 24, 2010

Jack, this is awesome. I’ve been trying for days to get a slow, smooth zoom effect, and I did it in seconds thanks to you.

Posted by viaria on October 12, 2010

jack,
i just love you man. you are the best man who makes his job well, i have ever seen yet.

Posted by outs on February 16, 2011

Hi Jack, I noticed that if you define a default overwriting mode for a parent swf, and load child swfs into it that have no default defined, the children swf will take on the parents default. Is this meant to be the correct behavior?

It caused a lot of headache as when I was developing and testing my child swf, everything was working fine, until I tested it from a load within my parent, and the child swf would no longer run some of my tweens. Googling “bug with child swfs and tweenmax” returns no results, until I eventually realized that a default overwrite setting will affect all the children swfs as well.

Thanks!!

Posted by Jack on February 17, 2011

Actually, outs, that depends on the LoaderContext you use when subloading. If you segregate the subloaded swf into its own ApplicationDomain, it won’t use the parent’s classes/settings like that. That’s not a bug or anything – it’s just how Flash works.

Posted by Jason King on January 8, 2012

If a new TweenMax overwrites all the tweens of an existing TweenMax and the old TweenMax has an OnComplete param, does the OnComplete get called?

Posted by Jack on January 8, 2012

Jason, If all of the tweening properties have been overwritten, the tween is considered dead and the onComplete does not get called. This is by design – it is normally what most developers prefer.

To download the code, you must agree to the following license:

"NO CHARGE" NON-EXCLUSIVE SOFTWARE LICENSE AGREEMENT
-----------------------------------------------------------------------------
PLAIN ENGLISH SUMMARY:

  1. You may use the code at no charge in commercial or non-commercial apps, web sites, games, components, and other software as long as end users are not charged a fee of any kind to use your product or gain access to any part of it. If your client pays you a one-time fee to create the site/product, that's perfectly fine and qualifies under the "no charge" license. If end users are charged a usage/access/license fee, please sign up for a "Business Green" Club GreenSock membership which comes with a comprehensive commercial license. See http://www.greensock.com/club/ for details.
  2. Use at your own risk. No warranties are offered.
  3. Please respect the copyright.

-----------------------------------------------------------------------------

LEGALESE:

This is a legal agreement between you (either an individual or a single entity) and GreenSock, Inc. ("GREENSOCK") for the proprietary GreenSock code known as TweenLite, TweenMax, TweenNano, TimelineLite, TimelineMax, and other copyrighted code that is available for download at http://www.greensock.com (this code and documentation, as well as any updates which may at GREENSOCK's sole discretion be provided to you from time to time, are referred to in this Agreement as "PROGRAM"). By downloading, copying, or otherwise using the PROGRAM, you agree to the terms and conditions of this Agreement. If you do not agree to the terms and conditions of this Agreement, please do not download or use the PROGRAM.

I. LICENSE
A. Subject to the terms and conditions of this Agreement, GREENSOCK hereby grants you a non-exclusive, worldwide, non-transferable right to use the PROGRAM in apps, web sites, games, components and other software applications ("Developed Works") for which the end user is NOT charged any fees. If you would like to use the code in a commercially licensed Developed Work for which end users are charged a fee (either for usage or access), simply sign up for the appropriate "Business Green" Club GreenSock membership at http://www.greensock.com/club/.

II. LIMITATION OF LICENSE AND RESTRICTIONS
A. You agree that you will not sell, rent, or license the PROGRAM's source code or any derivative works thereof to any third party without the prior written consent of GREENSOCK. Distribution of the PROGRAM as part of your Developed Work is acceptable so long as it is used exclusively as a part of your Developed Work. You agree not to modify or delete GREENSOCK'S existing copyright notices located in the source code.

B. You may use, duplicate, and distribute the compiled object code as embedded in Developed Works created by you, either for your own use or for distribution to a third party so long as end users of the Developed Work are not charged a fee for usage of or access to any portion of the Developed Work. Please see http://www.greensock.com/licensing/ for descriptions of Developed Works that qualify for the "No Charge" license.

C. You may make modifications to the source code exclusively for your own use in order to perform bug fixes or other minor edits required to operate the PROGRAM as originally intended.

III. CONSIDERATION
A. The license rights granted to you under this Agreement are at no charge, but only in the following circumstances: If on your own behalf or on behalf of a third party you incorporate the PROGRAM into a web site, app, game, program or any component thereof (collectively, "Developed Work"), which in the case of a web site, must be accessible to internet users without payment of a fee of any kind, and in the case of a software application, game, program or component, neither you nor anyone to whom you distribute the Developed Work charges a user a fee of any kind to use such Developed Work or application, game, program or component into which such Developed Work is embedded. The foregoing shall apply regardless of whether you are paid to create such Developed Work.

B. In the event your intended use of the PROGRAM does not meet the criteria for the "no charge" license rights set forth in the immediately preceding paragraph, then you are not licensed to use the PROGRAM under this Agreement and must license the PROGRAM under GREENSOCK'S separate fee-based Software License Agreement which is granted to "Business Green" Club GreenSock members (see http://www.greensock.com/club/ for details).

C. You may make modifications to the source code exclusively for your own use in order to perform bug fixes or other minor edits required to operate the PROGRAM as originally intended.

IV. TITLE AND OWNERSHIP
A. The PROGRAM is licensed, not sold, and is protected by copyright laws and international treaty provisions. You acknowledge that no title to the intellectual property in the PROGRAM is transferred to you. You further acknowledge that title and full ownership rights to the PROGRAM, including all intellectual property rights therein, will remain the exclusive property of GREENSOCK and you will not acquire any rights to the PROGRAM except as expressly set forth in this Agreement. You agree that any copies of the PROGRAM you make will contain the same proprietary notices which appear on and in the PROGRAM. You agree that GREENSOCK may identify you as a licensee unless you make a written request otherwise. GREENSOCK hereby grants to you the right to disclose that your product, game, software application, component, or other Developed Work makes use of GREENSOCK code (for example, "Powered by TweenLite").

V. DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY
A. THE PROGRAM IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. GREENSOCK DOES NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE PROGRAM WILL MEET YOUR REQUIREMENTS OR THAT OPERATION WILL BE UNINTERRUPTED OR ERROR FREE. GREENSOCK shall not be liable for special, indirect, incidental, or consequential damages with respect to any claim on account of or arising from this Agreement or use of the PROGRAM, even if GREENSOCK has been or is hereafter advised of the possibility of such damages. Because some states do not allow certain exclusions or limitations on implied warranties or of liability for consequential or incidental damages, the above exclusions may not apply to you. In no event, however, will GREENSOCK be liable to you, under any theory of recovery, in an amount in excess of $250. Notwithstanding anything else in this agreement, you agree to indemnify GREENSOCK, its assignees, and licensees, and hold each of them harmless from and against any and all claims, losses, damages, and expenses, including legal fees arising out of or resulting from any negligent act or omission by you.

B. GREENSOCK may, at its sole discretion, provide support services related to the PROGRAM, but has no obligation to do so.

VI. TERMINATION
If you at any time fail to abide by the terms of this Agreement, GREENSOCK shall have the right to immediately terminate the license granted herein and pursue any other legal or equitable remedies available.

VII. MISCELLANEOUS
A. This Agreement shall be construed in accordance with the laws of the State of Illinois. In the event of any dispute between you and GREENSOCK with respect to this Agreement, we both agree that if we cannot resolve the dispute in good faith discussion, either of us may submit the dispute for resolution to arbitration with the American Arbitration Association before a single arbitrator using the AAA Rules for Commercial Arbitration. The arbitrator's decision is final and can be enforced in any court with jurisdiction over such matters.

B. This agreement represents the complete and exclusive statement of the agreement between GREENSOCK and you and supersedes all prior agreements, proposals, representations and other communications, verbal or written, between them with respect to use of the program. This agreement may be modified only with the mutual written approval of authorized representatives of the parties.

C. The terms and conditions of this Agreement shall prevail notwithstanding any different, conflicting, or additional terms or conditions which may appear in any purchase order or other document submitted by you. You agree that such additional or inconsistent terms are deemed rejected by GREENSOCK.

D. GREENSOCK and you agree that any xerographically or electronically reproduced copy of this Agreement shall have the same legal force and effect as any copy bearing original signatures of the parties.

Copyright 2006-2013, GreenSock, Inc. Updated 2012-08-28

I'd like to learn how to get bonus plugins, update notifications, SVN access, and more.
To continue, you must agree to the following license: