LiquidStage – Automatically Reposition/Stretch DisplayObjects in Full-Browser SWFs
- Version: 2.031, Updated 2010-02-10
- 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.
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_INSIDE and horizontally and vertically align it in the center of the area
-
area.attach(myImage, ScaleMode.PROPORTIONAL_INSIDE, AlignMode.CENTER, AlignMode.CENTER);
-
-
//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.
FAQ
- 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. - 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. - 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. - I don't see a download link? Where do I get the LiquidStage class?
LiquidStage comes with "Shockingly Green" and corporate memeberships to Club GreenSock. When you join, you'll get a confirmation e-mail with a link to download the bonus classes.
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.
Comments (14)
NICE! I will have to finish up my donation and get my hands on that. Finally a simple solution to the stretchable site.
It really is a very simple solution for working with Liquid Stage
Thx Jack!!
This could be handy!
well done again
Nice work Jack. I like that you have allowed for the positional constants as well as custom ‘pinpoints’. Makes it more flexible.
Nice work, once again - updates to TweenMax are looking great as well. Looking forward to testing this.
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
this is so freaking awesome
Liquid Stage is just what I have been looking for. I’m really looking forward to using it in my apps. Thank you.
lol man, you are good. xD
You make my life worth living.
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…
Oh my god guys, you rock!
You are a marvel amongst men! You’ve saved me so much time and prevented many headaches. Keep up the great work.
“Oh my god guys, you rock!”
- jack you really are the power of ten programmers