LiquidStage – Automatically Reposition/Stretch DisplayObjects in Full-Browser SWFs

  • Version: 2.12, Updated 2011-07-12
  • Compatibility: AS3, Flash Player 9 and above

DESCRIPTION

LiquidStage allows you to “pin” DisplayObjects to reference points on the stage (or inside other DisplayObjects) so that when the stage is resized, they are repositioned and maintain their relative distance from the PinPoint. For example, you could make a logo Sprite stay in the bottom right corner when the stage is resized.

You can also scale or stretch DisplayObjects using the LiquidArea class which extends AutoFitArea and allows you to define a rectangular area that expands and contracts as the stage resizes, and you attach DisplayObjects so that they fill the area, scaling in any of the following modes: STRETCH, PROPORTIONAL_INSIDE, PROPORTIONAL_OUTSIDE, WIDTH_ONLY, or HEIGHT_ONLY. For example, you could have a bar snap to the bottom of the screen and stretch horizontally to fill the width of the stage. Or add a background image that proportionally scales to fill the entire stage.

If you’d like to see a real-world example, LiquidStage was used on dow.com/hu/.

There are a few things that make LiquidStage particularly useful:

  • Your DisplayObjects do not need to be at the root level – LiquidStage will compensate for nesting even if the DisplayObject’s anscestors are offset and/or scaled.
  • By default, repositioning only factors in the amount of change in the PinPoint’s position, meaning you are free to move the DisplayObject manually and LiquidStage will honor its new position instead of forcing it to always remain a certain distance from the PinPoint (although a “strict” mode is available too).
  • Not only can you pin things to the TOP_LEFT, TOP_CENTER, TOP_RIGHT, RIGHT_CENTER, BOTTOM_RIGHT, BOTTOM_CENTER, BOTTOM_LEFT, LEFT_CENTER, and CENTER, but you can create your own custom PinPoints in any DisplayObject.
  • Attach listeners to PinPoints to be notified when they change positions, and use toLocal() to determine a PinPoint’s position in any DisplayObject.
  • LiquidStage leverages the TweenLite engine to allow for animated transitions. Simply define the duration of the tween and optionally pass in a tween vars object to control other aspects of the tween like its ease, delay, add an onComplete, onUpdate, etc.
  • LiquidStage does NOT force you to align the stage to the upper left corner – it will honor whatever StageAlign you choose.
  • Optionally define a minimum/maximum width and height to prevent objects from repositioning when the stage gets too small or too big.
  • LiquidStage only does its work when the stage resizes, and it is built for maximum performance.

Interactive Demo

LiquidStage is a membership benefit of Club GreenSock (“Shockingly Green” and corporate levels).

Documentation

Please see the full ASDoc documentation.

Example code

import com.greensock.layout.*;

//create a LiquidStage instance for the current stage which was built at an original size of 550x400
//don't allow the stage to collapse smaller than 550x400 either.
var ls:LiquidStage = new LiquidStage(this.stage, 550, 400, 550, 400);
 
//attach a "logo" Sprite to the BOTTOM_RIGHT PinPoint
ls.attach(logo, ls.BOTTOM_RIGHT);

//create a 300x100 rectangular area at x:50, y:70 that stretches when the stage resizes (as though its top left and bottom right corners are pinned to their corresponding PinPoints on the stage)
var area:LiquidArea = new LiquidArea(this, 50, 70, 300, 100);

//attach a "myImage" Sprite to the area and set its ScaleMode to PROPORTIONAL_OUTSIDE and crop the overspill
area.attach(myImage, {scaleMode:ScaleMode.PROPORTIONAL_OUTSIDE, crop:true});

//if you'd like to preview the area visually (by default previewColor is red), set preview to true
area.preview = true;
 
//attach a RESIZE event listener to the LiquidStage instance (you could do this with the LiquidArea as well)
ls.addEventListener(Event.RESIZE, onLiquidStageUpdate);
function onLiquidStageUpdate(event:Event):void {
	trace("updated LiquidStage");
}

Notes / Limitations

  • You need to set up your objects on the stage initially with the desired relative distance between them and their PinPoint; LiquidStage doesn’t reposition them initially (except for the “reconcile” feature in the attach() method). For example, if you want logo_mc to be exactly 20 pixels away from the BOTTOM_RIGHT corner of the stage on both axis (x and y), you must put it there before attaching it.
  • If a DisplayObject is not in the display list (has no parent), LiquidStage will ignore it until it is back in the display list.
  • If you plan to set the “align” property of your stage, do so before creating its LiquidStage instance.

Videos

Thon Lorenz created a video tutorial that involves integrating Gaia and LiquidStage. Check it out.

FAQ

  1. Does LiquidStage automatically force my swf to fill the browser?
    No, LiquidStage is just ActionScript and doesn’t control how you embed your swf in your html page – you need to use the appropriate embed code to fill the browser. One common (and easy) tool for this is swfobject.
  2. Is the new version of LiquidStage backwards compatible with version 0.997 and before?
    No, LiquidStage was completely rebuilt in version 2 in order to be more flexible and capable. The API and structure has been significantly improved.
  3. Can I create custom PinPoints instead of just using the standard TOP_LEFT, BOTTOM_RIGHT, etc.?
    Absolutely. Create a PinPoint anywhere you want. You can attach listeners to PinPoints be notified when they change positions, and use toLocal() to determine a PinPoint’s position in any DisplayObject.
  4. I don’t see a download link? Where do I get the LiquidStage class?
    LiquidStage comes with “Shockingly Green” and corporate memberships to Club GreenSock. When you join, you’ll get access to the classes in your GreenSock account.

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 2011, GreenSock (This work is subject to the terms here.)
  • Twitter
  • Facebook
  • Digg
  • StumbleUpon
  • del.icio.us
  • Yahoo! Buzz
  • Google Bookmarks
  • RSS
  • LinkedIn
  • Reddit

Comments (17) RSS

Posted by John Webber on November 8, 2008

NICE! I will have to finish up my donation and get my hands on that. Finally a simple solution to the stretchable site.

Posted by fenixkim on November 9, 2008

It really is a very simple solution for working with Liquid Stage

Thx Jack!!

Posted by Paul Ferrie on November 11, 2008

This could be handy!

well done again

Posted by noponies on November 17, 2008

Nice work Jack. I like that you have allowed for the positional constants as well as custom ‘pinpoints’. Makes it more flexible.

Posted by David Kaneda on November 17, 2008

Nice work, once again - updates to TweenMax are looking great as well. Looking forward to testing this.

Posted by HaunGo on November 17, 2008

Boy’o’boy have I been waiting for this! I’ve been using a far more complex and frustrating class from someone.. I’m very glad to switch over to this one. Same syntax as TweenLite, PLUS that accompanying guarantee of quality! Bravo! Ima try it out right now!

-H

Posted by polacek on December 4, 2008

this is so freaking awesome

Posted by Ben on January 14, 2009

Liquid Stage is just what I have been looking for. I’m really looking forward to using it in my apps. Thank you.

Posted by P48L0 on January 20, 2009

lol man, you are good. xD

Posted by Ben Stone on March 9, 2009

Wow!… like all your handiwork, Jack, this class is utter poetry! I actually requoted lines 145-186 in a valentine’s card for my wife (her resulting goosebumps lasted for days!)

BTW- I’m now storing all your Classes as such:
gs.superlative.indispensable.magic.*

Posted by TL on September 8, 2009

You make my life worth living.

Posted by Michael Becker on November 6, 2009

Fantastic class. Although probably obvious to some, it is important to note that if you are dynamically adding objects from the library, you MUST position their x/y coordinates before using LiquidStage. Tripped me up for a bit as I assumed that it would automatically place an object where you tell it, but in fact it just keeps it where you place it. Correct me if I’m wrong…

Posted by Andrea on November 25, 2009

Oh my god guys, you rock!

Posted by Kevin on February 10, 2010

You are a marvel amongst men! You’ve saved me so much time and prevented many headaches. Keep up the great work.

Posted by one giant media on March 4, 2010

“Oh my god guys, you rock!”
- jack you really are the power of ten programmers

Posted by josh on March 17, 2010

Very simple and very clean. This is a tremendous tool that makes simple a lot of work. Thanks!

Posted by Tommy on December 8, 2011

I am a beginner in Flash AS3, may you guys please make a tutorial on how http://www.dow.com/hu/ was made. I will greatly appreciate it! Everyone seems very happy with the work being put here

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: