Packagecom.greensock.layout
Classpublic class LiquidStage
InheritanceLiquidStage Inheritance flash.events.EventDispatcher

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 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.

There are a few things that make LiquidStage particularly useful:


Example
Example AS3 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: Copyright 2010, GreenSock. All rights reserved. This work is subject to the license that came with your Club GreenSock membership and is ONLY to be used by corporate or "Shockingly Green" Club GreenSock members. To learn more about Club GreenSock, visit http://blog.greensock.com/club/.



Public Properties
 PropertyDefined by
  BOTTOM_CENTER : PinPoint
bottom center of the stage
LiquidStage
  BOTTOM_LEFT : PinPoint
bottom left corner of the stage
LiquidStage
  BOTTOM_RIGHT : PinPoint
bottom right corner of the stage
LiquidStage
  CENTER : PinPoint
center of the stage
LiquidStage
  defaultStage : LiquidStage
[static] Refers to the first LiquidStage instance created (or you can set it to any other instance) - it serves as an easy way to reference a LiquidStage through a static variable.
LiquidStage
  isBaseSize : Boolean
[read-only] Only true when the LiquidStage instance is at the base size as it was defined in the constructor (baseWidth and baseHeight).
LiquidStage
  LEFT_CENTER : PinPoint
left center of the stage
LiquidStage
  maxHeight : uint
maximum height of the LiquidStage area
LiquidStage
  maxWidth : uint
maximum width of the LiquidStage area
LiquidStage
  minHeight : uint
minimum height of the LiquidStage area
LiquidStage
  minWidth : uint
minimum width of the LiquidStage area
LiquidStage
  retroMode : Boolean
When retroMode is true, LiquidStage will revert to (and stay at) the base stage size as it was defined in the constructor (baseWidth and baseHeight) which can be useful when you want to pin objects according to coordinates on the original (unscaled) stage.
LiquidStage
  RIGHT_CENTER : PinPoint
right center of the stage
LiquidStage
  stage : Stage
[read-only] The stage associated with the LiquidStage instance
LiquidStage
  stageBox : Sprite
[read-only] A Sprite that starts out at the native size of the stage (baseWidth/baseHeight) and then gets scaled to fit the stage - you can use this for the target parameter for custom PinPoints that you place positions on the stage.
LiquidStage
  TOP_CENTER : PinPoint
top center of the stage
LiquidStage
  TOP_LEFT : PinPoint
top left corner of the stage
LiquidStage
  TOP_RIGHT : PinPoint
top right corner of the stage
LiquidStage
Public Methods
 MethodDefined by
  
LiquidStage(stage:Stage, baseWidth:uint, baseHeight:uint, minWidth:uint = 0, minHeight:uint = 0, maxWidth:uint = 99999999, maxHeight:uint = 99999999)
Constructor
LiquidStage
  
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Use this to add an Event.RESIZE event listener which can be particularly handy if you need to run other functions AFTER LiquidStage does all its repositioning.
LiquidStage
  
attach(target:DisplayObject, pin:PinPoint, strict:Boolean = false, reconcile:Boolean = true, tweenDuration:Number = 0, tweenVars:Object = null):void
Attaches a DisplayObject to a particular PinPoint (like TOP_RIGHT) so that any movement of the PinPoint will also affect the relative position of the DisplayObject.
LiquidStage
  
getByStage(stage:Stage):LiquidStage
[static] Retrieves the LiquidStage instance associated with a particular stage.
LiquidStage
  
release(target:DisplayObject):Boolean
Releases a DisplayObject from being controlled by LiquidStage after having been attached.
LiquidStage
  
update(event:Event = null):void
Forces an update of all PinPoints and DisplayObject positions.
LiquidStage
Property detail
BOTTOM_CENTERproperty
public var BOTTOM_CENTER:PinPoint

bottom center of the stage

BOTTOM_LEFTproperty 
public var BOTTOM_LEFT:PinPoint

bottom left corner of the stage

BOTTOM_RIGHTproperty 
public var BOTTOM_RIGHT:PinPoint

bottom right corner of the stage

CENTERproperty 
public var CENTER:PinPoint

center of the stage

defaultStageproperty 
public static var defaultStage:LiquidStage

Refers to the first LiquidStage instance created (or you can set it to any other instance) - it serves as an easy way to reference a LiquidStage through a static variable.

isBaseSizeproperty 
isBaseSize:Boolean  [read-only]

Only true when the LiquidStage instance is at the base size as it was defined in the constructor (baseWidth and baseHeight). This essentially indicates whether or not the stage is currently scaled.

Implementation
    public function get isBaseSize():Boolean
LEFT_CENTERproperty 
public var LEFT_CENTER:PinPoint

left center of the stage

maxHeightproperty 
public var maxHeight:uint

maximum height of the LiquidStage area

maxWidthproperty 
public var maxWidth:uint

maximum width of the LiquidStage area

minHeightproperty 
public var minHeight:uint

minimum height of the LiquidStage area

minWidthproperty 
public var minWidth:uint

minimum width of the LiquidStage area

retroModeproperty 
retroMode:Boolean  [read-write]

When retroMode is true, LiquidStage will revert to (and stay at) the base stage size as it was defined in the constructor (baseWidth and baseHeight) which can be useful when you want to pin objects according to coordinates on the original (unscaled) stage.

Implementation
    public function get retroMode():Boolean
    public function set retroMode(value:Boolean):void
RIGHT_CENTERproperty 
public var RIGHT_CENTER:PinPoint

right center of the stage

stageproperty 
stage:Stage  [read-only]

The stage associated with the LiquidStage instance

Implementation
    public function get stage():Stage
stageBoxproperty 
stageBox:Sprite  [read-only]

A Sprite that starts out at the native size of the stage (baseWidth/baseHeight) and then gets scaled to fit the stage - you can use this for the target parameter for custom PinPoints that you place positions on the stage.

Implementation
    public function get stageBox():Sprite
TOP_CENTERproperty 
public var TOP_CENTER:PinPoint

top center of the stage

TOP_LEFTproperty 
public var TOP_LEFT:PinPoint

top left corner of the stage

TOP_RIGHTproperty 
public var TOP_RIGHT:PinPoint

top right corner of the stage

Constructor detail
LiquidStage()constructor
public function LiquidStage(stage:Stage, baseWidth:uint, baseHeight:uint, minWidth:uint = 0, minHeight:uint = 0, maxWidth:uint = 99999999, maxHeight:uint = 99999999)

Constructor

Parameters
stage:Stage — The Stage to which LiquidStage is applied
 
baseWidth:uint — The width of the SWF as it was built in the IDE originally (NOT the width that it is stretched to in the browser or standalone player).
 
baseHeight:uint — The height of the SWF as it was built in the IDE originally (NOT the height that it is stretched to in the browser or standalone player).
 
minWidth:uint (default = 0) — Minimum width (if you never want the width of LiquidStage to go below a certain amount, use minWidth).
 
minHeight:uint (default = 0) — Minimum height (if you never want the height of LiquidStage to go below a certain amount, use minHeight).
 
maxWidth:uint (default = 99999999) — Maximum width (if you never want the width of LiquidStage to exceed a certain amount, use maxWidth).
 
maxHeight:uint (default = 99999999) — Maximum height (if you never want the height of LiquidStage to exceed a certain amount, use maxHeight).
Method detail
addEventListener()method
public override function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void

Use this to add an Event.RESIZE event listener which can be particularly handy if you need to run other functions AFTER LiquidStage does all its repositioning.

Parameters
type:String — Event type (Event.RESIZE)
 
listener:Function — Listener function
 
useCapture:Boolean (default = false) — useCapture
 
priority:int (default = 0) — Priority level
 
useWeakReference:Boolean (default = false) — Use weak references
attach()method 
public function attach(target:DisplayObject, pin:PinPoint, strict:Boolean = false, reconcile:Boolean = true, tweenDuration:Number = 0, tweenVars:Object = null):void

Attaches a DisplayObject to a particular PinPoint (like TOP_RIGHT) so that any movement of the PinPoint will also affect the relative position of the DisplayObject. Attaching the DisplayObject does NOT force it to share the same coordinates as the PinPoint - it simply causes the PinPoint's movement to proportionally affect the position of the DisplayObject. The relationship is one-way so moving the DisplayObject will not move the PinPoint. Unless the strict parameter is true, changes are relative so you are free to move the DisplayObject as you wish and when the PinPoint's position changes, its proportional movement will honor the DisplayObject's new position instead of forcing it back to the same distance from the PinPoint. But again, you can set the strict parameter to true if you want to force the object to always maintain a certain distance from the PinPoint

For example, if your object is 100 pixels away from the PinPoint and the PinPoint moves 15 pixels, the DisplayObject will move 15 pixels as well (or however many pixels it takes to maintain its relative distance to the PinPoint which may be more or less than 15 pixels if it is nested inside a scaled parent). Strict mode, however, will force the DisplayObject to maintain its exact distance away from the PinPoint (no manual position changes will be honored when LiquidStage updates).

Parameters
target:DisplayObject — The DisplayObject to attach
 
pin:PinPoint — The PinPoint to which the target should be attached (like TOP_RIGHT or CENTER or a custom PinPoint)
 
strict:Boolean (default = false) — In strict mode, the target will be forced to remain EXACTLY the same distance from the pin as it was when it was attached. If strict is false, LiquidStage will honor any manual changes you make to the target's position, making it more flexible. Note that LiquidStage only performs updates to the target's position when the stage resizes and/or when update() is called.
 
reconcile:Boolean (default = true) — If true, the target's position will immediately be moved as far as the PinPoint has moved from its original position, effectively acting as though the target was attached BEFORE the stage was scaled. If you attach an object after the stage has been scaled and you don't want it to reconcile with the PinPoint initially, set reconcile to false.
 
tweenDuration:Number (default = 0) — To make the target tween to its new position instead of immediately moving there, set the tween duration (in seconds) to a non-zero value. A TweenLite instance will be used for the tween.
 
tweenVars:Object (default = null) — To control other aspects of the tween (like ease, onComplete, delay, etc.), use an object just like the one you'd pass into a TweenLite instance as the 3rd parameter (like {ease:Elastic.easeOut, delay:0.2})
getByStage()method 
public static function getByStage(stage:Stage):LiquidStage

Retrieves the LiquidStage instance associated with a particular stage. For example:

//create the LiquidStage instance
var ls:LiquidStage = new LiquidStage(this.stage, 550, 400);

//then later, if you need to find the LiquidStage instance for this stage to attach() objects, you could do this:
var ls:LiquidStage = LiquidStage.getByStage(this.stage);
ls.attach(mc1, ls.TOP_RIGHT);
ls.attach(mc2, ls.BOTTOM_CENTER);

Parameters
stage:Stage — The stage whose LiquidStage instance to return

Returns
LiquidStage — LiquidStage instance associated with the stage
release()method 
public function release(target:DisplayObject):Boolean

Releases a DisplayObject from being controlled by LiquidStage after having been attached.

Parameters
target:DisplayObject — The DisplayObject to release

Returns
Boolean — if the target was found and released, this value will be true. Otherwise, it will be false.
update()method 
public function update(event:Event = null):void

Forces an update of all PinPoints and DisplayObject positions.

Parameters
event:Event (default = null)