GreenSock

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

Posted in Transforming, Tweening by jack on the November 8th, 2008
  • Version: 0.992, Updated 12/14/2008
  • Compatibility: AS3
  • File Size added to published SWF: About 4Kb (not including TweenLite)

This class is a membership benefit of Club GreenSock

DESCRIPTION

LiquidStage allows you to "pin" DisplayObjects to reference points on the stage or in other DisplayObjects so that when the stage is resized, the DisplayObjects are repositioned and stay exactly the same distance from the reference point(s) they're registered to. It also allows you to define another pin point horizontally and/or vertically which will change the width/height of the DisplayObject when the stage is resized, stretching it visually. For example, maybe you want a logo Sprite to always maintain a particular distance from the bottom right corner. Or maybe you'd like a bar to snap to the bottom of the screen and stretch horizontally to fill the bottom of the stage. Here is an example of what LiquidStage can do.

It may sound pretty simple, but there are some really useful features like:

  • Your DisplayObjects do not need to be at the root level - LiquidStage will compensate for nesting even if the DisplayObject's ancestors are offset (not at the 0,0 position).
  • Repositioning/Resizing values are relative so if you pin an object and then move it, LiquidStage will honor that new position.
  • 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.
  • LiquidStage leverages the TweenLite engine to allow for animated transitions. You can define the duration of the transition and the easing equation for each DisplayObject individually.
  • If there are any TweenLite/FilterLite/Max instances that are tweening the x/y coordinates of an object, LiquidStage will seamlessly integrate itself with the existing tween(s) by updating their end values on the fly.
  • x and y coordinates are always snapped to whole pixel values, so you don't need to worry about mushy text or distorted images.
  • 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 width/height to prevent objects from repositioning when the stage gets too small.
  • LiquidStage only does its work when the stage resizes, so it's not constantly draining CPU cycles and hurting performance.

Interactive Demo

LiquidStage is a membership benefit of Club GreenSock ("Shockingly Green" individual level and most corporate levels).

USAGE

The first step is to init() LiquidStage to feed it the info it needs, like the stage and the width/height that you originally built your SWF at (you only need to do this once), like:

  1. LiquidStage.init(this.stage, 550, 400);

Then you can pin your DisplayObjects with the pinObject(), pinObjects(), or stretchObject() methods like:

  1. LiquidStage.pinObject(myClip, LiquidStage.BOTTOM_RIGHT);

STATIC METHODS

LiquidStage.init(stage:Stage, baseWidth:uint, baseHeight:uint, minWidth:uint, minHeight:uint):void
  • Description: Initializes the LiquidStage. This should be done immediately in your application (on the first frame or in your main class's constructor for example). Don't pin any objects until LiquidStage.init() has been called.
  • Parameters:
    1. stage: A reference to your SWF's stage
    2. baseWidth: The width at which you built the original SWF
    3. baseHeight: The height at which you built the original SWF
    4. minWidth: The minimum width that LiquidStage should allow the stage to collapse.
    5. minHeight: The minimum height that LiquidStage should allow the stage to collapse.

LiquidStage.pinObject(object:DisplayObject, point:PinPoint, accordingToBase:Boolean, duration:Number, ease:Function):void
  • Description: Pins a DisplayObject to a particular PinPoint (LiquidStage.BOTTOM_RIGHT for example). No stretching will occur when the stage resizes - the DisplayObject will simply be repositioned to maintain the same distance from this PinPoint.
  • Parameters:
    1. object: The DisplayObject to pin
    2. point: The PinPoint to which the DisplayObject should be pinned. LiquidStage.BOTTOM_RIGHT for example. Or create your own PinPoint.
    3. accordingToBase: Determines whether or not LiquidStage should record the position based on the original SWF's size (the one at which it was built). Normally you should leave this as true unless you're pinning an object dynamically after the SWF has been stretched to fill the browser window.
    4. duration: If you'd like to animate the repositioning, enter the duration (in seconds) of the tween here.
    5. ease: Defines the easing equation to be used for the animation (if duration is more than zero). For example, Strong.easeInOut, Elastic.easeOut, etc.

LiquidStage.pinObjects(objects:Array, point:PinPoint, accordingToBase:Boolean, duration:Number, ease:Function):void
  • Description: Same as LiquidStage.pinObject() but accepts an Array of DisplayObjects so that you can pin them all to the same PinPoint with a single call.
  • Parameters: (see LiquidStage.pinObject() above)

LiquidStage.stretchObject(object:DisplayObject, primaryPoint:PinPoint, xStretchPoint:PinPoint, yStretchPoint:PinPoint, accordingToBase:Boolean, duration:Number, ease:Function):void
  • Description: Just like LiquidStage.pinObject() but allows you to use another PinPoint to stretch the DisplayObject horizontally and/or a PinPoint to stretch the DisplayObject vertically. For example, you could pin an object to the upper left corner and then if you define the lower left corner as the yStretchPoint, the bar will stretch vertically as the window resizes so that the gaps remain consistent on the top and bottom. If you also use the upper right corner, for example, it would stretch the width and height as the window resizes. Stretching simply modifies the width and/or height properties of the DisplayObject.
  • Parameters:
    1. object: The DisplayObject to pin
    2. primaryPoint: The primary PinPoint to which the DisplayObject should be pinned. LiquidStage.TOP_LEFT for example. This point determines the position of the DisplayObject when the window resizes.
    3. xStretchPoint: The PinPoint to which the right edge of the DisplayObject should be pinned. This point determines the width of the DisplayObject when the window resizes.
    4. yStretchPoint: The PinPoint to which the bottom edge of the DisplayObject should be pinned. This point determines the height of the DisplayObject when the window resizes.
    5. accordingToBase: Determines whether or not LiquidStage should record the position based on the original SWF's size (the one at which it was built). Normally you should leave this as true unless you're pinning an object dynamically after the SWF has been stretched to fill the browser window.
    6. duration: If you'd like to animate the repositioning, enter the duration (in seconds) of the tween here.
    7. ease: Defines the easing equation to be used for the animation (if duration is more than zero). For example, Strong.easeInOut, Elastic.easeOut, etc.

LiquidStage.releaseObject(object:DisplayObject):void
  • Description: Releases a DisplayObject from being affected by LiquidStage.
  • Parameters:
    1. object: The DisplayObject to release

EXAMPLES

To make the logo_mc Sprite pin itself to the bottom right corner of your SWF that's built to a 550x400 dimension, you'd do:

  1. import gs.utils.LiquidStage;
  2.  
  3. LiquidStage.init(this.stage, 550, 400);
  4. LiquidStage.pinObject(logo_mc, LiquidStage.BOTTOM_RIGHT);

To pin the logo_mc as mentioned above and make the bottomBar_mc Sprite pin itself to both the bottom left and bottom right corners so that it stretches as the window resizes in a SWF that's built to a 550x400 dimension, and set the minimum width and height to that base size (550x400) so that it cannot collapse to a smaller size than that, and animate the transition over the course of 1.5 seconds with an Elastic.easeOut ease, do:

  1. import gs.utils.LiquidStage;
  2. import gs.easing.Elastic;
  3. import flash.display.*;
  4.  
  5. this.stage.align = StageAlign.TOP_LEFT;
  6. LiquidStage.init(this.stage, 550, 400, 550, 400);
  7. LiquidStage.pinObject(logo_mc, LiquidStage.BOTTOM_RIGHT);
  8. LiquidStage.stretchObject(bottomBar_mc, LiquidStage.BOTTOM_LEFT, LiquidStage.BOTTOM_RIGHT, null, true, 1.5, Elastic.easeOut);

To create a custom PinPoint in the "videoDisplay" Sprite and pin the "videoControls" to that custom point so that videoControls always maintains the same distance from its registration point to the PinPoint inside videoDisplay, you'd do:

  1. import gs.utils.LiquidStage;
  2. import gs.utils.PinPoint;
  3.  
  4. LiquidStage.init(this.stage, 550, 400);
  5. var myCustomPinPoint:PinPoint = new PinPoint(100, 200, videoDisplay);
  6. LiquidStage.pinObject(videoControls, myCustomPinPoint);

FAQ

  1. I don't see a download link? Where do I get the LiquidStage class?
    LiquidStage comes with "Shockingly Green" and most 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 e-mail me a question. Or post your question on the new forums. When you e-mail or post your question, please include a simplified FLA file (and any class files) that clearly demonstrates the problem and provide a brief explanation.

Author: Jack Doyle, (e-mail: jack -at- greensock.com)
Copyright 2008, GreenSock (This work is subject to the terms here.)

7 Responses to 'LiquidStage - Automatically Reposition/Stretch DisplayObjects in Full-Browser SWFs'

Subscribe to comments with RSS

  1. John Webber said,

    on November 8th, 2008 at 10:12 pm

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

  2. fenixkim said,

    on November 9th, 2008 at 9:40 am

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

    Thx Jack!!

  3. Paul Ferrie said,

    on November 11th, 2008 at 7:03 am

    This could be handy!

    well done again

  4. David Kaneda said,

    on November 17th, 2008 at 2:56 pm

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

  5. noponies said,

    on November 17th, 2008 at 2:59 pm

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

  6. HaunGo said,

    on November 17th, 2008 at 5:42 pm

    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

  7. polacek said,

    on December 4th, 2008 at 2:26 pm

    this is so freaking awesome

Leave a Reply