Code Hinting and Strict Data Typing for TweenLite and TweenMax Vars

Having a hard time remembering all the special properties that you can define in your TweenLite or TweenMax “vars” parameters? I don’t blame you, especially with all the nifty plugins available. If you’d like to get the convenience of code hinting and improved debugging with strict data typing, you’ll love the new TweenLiteVars and TweenMaxVars classes. As of version 5.0, they have been completely rewritten to accommodate method chaining which greatly reduces the amount of code necessary (compared to previous versions). Here’s how the standard way of defining vars with a generic Object compares to using a TweenLiteVars instance:

//Without TweenLiteVars
TweenLite.to(mc, 1, {x:300, autoAlpha:0, onComplete:myFunction, onCompleteParams:[mc]});

//With TweenLiteVars
TweenLite.to(mc, 1, new TweenLiteVars().prop("x", 300).autoAlpha(0).onComplete(myFunction, [mc]));

Here’s what the code hinting looks like in Flash Builder:

You can also use a hybrid approach by passing a generic Object into the constructor to define whatever properties you want, like this:

//pass a generic Object to the constructor...
TweenLite.to(mc, 1, new TweenLiteVars({x:300, y:100, scaleX:1.5}).autoAlpha(0).onComplete(myFunction, [mc]));

One other benefit is that it will trace() a warning if you try using a special property without activating the corresponding plugin. For example, if you define an autoAlpha value in a TweenLiteVars instance but you didn’t activate() the plugin, you’ll see a trace() output when you test/compile the file (an Error isn’t thrown because in some very rare circumstances it is acceptable to avoid activating the plugin).

What are the trade offs?

The only significant trade off is file size; TweenLiteVars adds about 5kb to your swf. TweenMaxVars is only slightly heavier. But remember, both are completely optional so only use them if you can afford the extra kb.

FAQ

  1. I hate chaining – it’s ugly. Why did you change perfectly good classes to use this funky syntax?
    I wasn’t a fan of the chaining syntax when I first saw it either. It felt weird. But there are several key advantages that it provides which make it ideal for this particular type of class. First, it is much more concise than the old “standard” way of defining values (like vars.delay = 5) when you have many values to define. Also, it accommodates multiple parameters for a single special property which is quite useful for things like filters (blurX, blurY, quality, etc.). Plus it reduced the file size footprint of the class(es) to less than half of what it was previously! Lastly, it allows the values to be defined inline which is particularly useful in situations where you’re putting many tweens into a TimelineLite/Max. No need to create local variables. Before turning up your nose and declaring this new chaining style beneath you, I’d encourage you to give it a try for a project or two. I’m pretty confident that you’ll quickly see how convenient and functional it is.
  2. Where do I get the classes?
    They’re in the com.greensock.data package in the AS3 zip downloads. Click the big “Download AS3″ button at the top right of this page or any of the tweening-related or loading-related pages.
  3. Do I have to use one of these classes in order for TweenLite/Max to work?
    Absolutely not. It is completely optional.
  4. Does code hinting work in all code editors?
    No, but most modern code editors offer this feature including Flash Builder, FDT, FlashDevelop, and even Flash Professional CS5.
  5. Will these classes work with older versions of TweenLite and TweenMax?
    Technically they can, but it is definitely best to update to at least version 11.4 of TweenLite/Max. To make TweenLiteVars and TweenMaxVars compatible with all versions, you must feed the raw “vars” data into the tween, so tack on “.vars” to the end of your method chain like this:

    //Don't forget the ".vars" at the end...
    TweenLite.to(mc, 1, new TweenLiteVars().prop("x", 100).autoAlpha(0).vars);
  6. If I was using an old version of TweenLiteVars or TweenMaxVars, will I need to rework my code to use the new versions?
    Yes, you will. I always try hard to avoid API changes that could affect legacy code like this, but sometimes it is necessary in order to take a big step forward. If you are currently using older versions of TweenLiteVars or TweenMaxVars and don’t want to spend time updating your code, make sure you keep a copy of the legacy versions of the classes. Feel free to send an e-mail request if necessary.
  • Twitter
  • Facebook
  • Digg
  • StumbleUpon
  • del.icio.us
  • Yahoo! Buzz
  • Google Bookmarks
  • RSS
  • LinkedIn
  • Reddit

Comments (17) RSS

Posted by Paulo Miranda on November 14, 2010

Hi,
Great update and i will definetly use it.
Could you do this:

onComplete(func:Function, … params):

instead of this:

onComplete(func:Function, params:Array = null)

It would be more user friendly and you still would receive an Array.

Posted by Jack on November 14, 2010

Actually, Paulo, I don’t think that would be more user friendly – an array makes it simple to group the parameters dynamically and reuse them in multiple tweens plus it maps more cleanly to the onCompleteParams special property that TweenLite and TweenMax look for in the generic vars object.

Posted by James on November 16, 2010

Inline?

Yuck.

Very disappointed.

Posted by James on November 16, 2010

Just to clarify, I’m a developer who very happily setup my Tween variables in FlashDevelop the “OLD WAY” (as your newsletter defined it). Code hinting was never a problem… I always instantiated a TweenLiteVars or TweenMaxVars object to populate and pass into to my Tween* function.

Oh well, what GreenSock dictates, we all must follow.

Cheers for the initiative. :)

Posted by Ramiro Araujo on November 16, 2010

James, as I understand, you can still use this new TweenVars with the old way just the way it was.

Posted by Jack on November 17, 2010

Not quite, Ramiro. Since the old properties are now functions, you can’t just do something like vars.delay = 5. You’d do vars.delay(5). But you certainly don’t need to chain things together if you don’t want to. You can do this:

var config:TweenLiteVars = new TweenLiteVars();
config.delay(5);
config.onComplete(myFunction);

Or you can even use the chaining syntax but split each property out onto its own line to make it [arguably] more readable:

new TweenLiteVars()
.delay(5)
.onComplete(myFunction);

Posted by Ahrengot on November 17, 2010

Wasn’t a fan of this new syntax when i read the mail, but it’s really starting to make sense to me now. This new format looks good, and i’m looking forward to trying it out in my next project :)

Posted by Ramiro Araujo on November 17, 2010

Hmm, ok. I’ve never used the old version. What I meant was that you can like your first example: declare it and call one method per line.

Posted by sjimmi on November 24, 2010

hmmm.. not digging the new way…

Posted by Zachary Dremann on November 30, 2010

This new syntax is pretty bad for things like blur filters. In the old method, you could do something like

myVars:TweenLiteVars = new TweenLiteVars();
myGlowVars:GlowFilterVars = new GlowFilterVars(1,1,0xffffff);
myGlowVars.addFilter = false;

In the new syntax, You have to do:
myVars:TweenLiteVars = new TweenLiteVars();
myVars.GlowFilter(1,1,0xffffff,1,2,false,false,2,false);

Not only is that not readable at at all, I have to define all those unnecessary variables.

Posted by Jack on November 30, 2010

Zachary, it is a bit of a double-edged sword but I’m confident that when you weigh all the pros and cons, they add up pretty decisively on the side of the new syntax. Even with having to define the 5 extra parameters in the example you posted, the new syntax is shorter. And remember that one of the primary purposes of these optional classes is enabling code hinting, so the readability argument loses its strength pretty quickly (put your cursor on any argument and CTRL-SPACE). The old way was practically impossible to do inline, making things much more verbose plus it required more than double the file size. And extra helper classes (like GlowFilterVars) were necessary. Not anymore. The new system even checks to make sure you activated the plugin if necessary. So all in all, it’s a big step forward, but I realize there will be some growing pains for folks who were used to the old way. I apologize for that.

Posted by Zachary Dremann on December 3, 2010

I hate to say it… But I like the new syntax. There are some negatives, but it really is easy to use inline. You win. :D

(But I still consider that unreadable. I can’t tell what variable i’m changing, and I can’t – at a glance – tell anything about it at all. But even with that, it’s better this way.)

Posted by Ryno on March 12, 2011

Inline isnt that bad really – its better for quick coding and user friendlyness

Posted by Mr. Lawyer on April 8, 2011

Come on guys inline isn’t so bad

Posted by Mark on December 23, 2011

I think TweenLiteVars are awesome (use it alot), but I would like to see these functions added to it:

.move(x:Number, y:Number, relative:Boolean = false)

.scaleX(value:Number, relative:Boolean = false)

.scaleY(value:Number, relative:Boolean = false)

.scale(value:Number, relative:Boolean = false) // does scaleX and scaleY

Posted by Jack on December 23, 2011

Your wish is my command, Mark :) I added those convenience methods (along with a few others) in the latest version.

Posted by Mark on December 23, 2011

Thanks, that was fast. I see you’ve added rotation() too, I forgot to mention that one too, had it in my mind too. Awesome! I’m glad I’ve requested it. Have a lovely christmas!

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: