com.greensock.layout.LiquidStage

Package	com.greensock.layout
Class	public class LiquidStage
Inheritance	LiquidStage 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:

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

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:

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. 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 attach()-ing 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.
LiquidStage is a Club GreenSock membership benefit. You must have a valid membership to use this class without violating the terms of use. Visit http://www.greensock.com/club/ to sign up or get more details.

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

	Property	Defined 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

	Method	Defined 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_CENTER

property

public var BOTTOM_CENTER:PinPoint

bottom center of the stage

BOTTOM_LEFT

property

public var BOTTOM_LEFT:PinPoint

bottom left corner of the stage

BOTTOM_RIGHT

property

public var BOTTOM_RIGHT:PinPoint

bottom right corner of the stage

CENTER

property

public var CENTER:PinPoint

center of the stage

defaultStage

property

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.

isBaseSize

property

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_CENTER

property

public var LEFT_CENTER:PinPoint

left center of the stage

maxHeight

property

public var maxHeight:uint

maximum height of the LiquidStage area

maxWidth

property

public var maxWidth:uint

maximum width of the LiquidStage area

minHeight

property

public var minHeight:uint

minimum height of the LiquidStage area

minWidth

property

public var minWidth:uint

minimum width of the LiquidStage area

retroMode

property

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_CENTER

property

public var RIGHT_CENTER:PinPoint

right center of the stage

stage

property

stage:Stage [read-only]

The stage associated with the LiquidStage instance

Implementation
public function get stage():Stage

stageBox

property

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_CENTER

property

public var TOP_CENTER:PinPoint

top center of the stage

TOP_LEFT

property

public var TOP_LEFT:PinPoint

top left corner of the stage

TOP_RIGHT

property

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)

API Documentation	All Packages \| All Classes \| Index \| Frames No Frames
Class LiquidStage	Properties \| Methods