API Documentation | All Packages | All Classes | Index | Frames No Frames |
Class 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 2011, 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

| 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

Public Methods

| 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, roundPosition:Boolean = false):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, suppressEvents:Boolean = false):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, roundPosition:Boolean = false):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}`)
| `roundPosition:Boolean` (default = `false`)`` — To force the target's x/y position to snap to whole pixel values, set `roundPosition` to `true` (it is `false` by default).

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, suppressEvents:Boolean = false):void`

Forces an update of all PinPoints and DisplayObject positions.

Parameters

| `event:Event` (default = `null`)``
| `suppressEvents:Boolean` (default = `false`)``