Packagecom.greensock.layout
Classpublic class LiquidArea
InheritanceLiquidArea Inheritance AutoFitArea Inheritance flash.display.Shape

LiquidArea is an AutoFitArea that integrates with LiquidStage, automatically adjusting its size whenever the stage is resized. Like AutoFitArea, it allows you to define a rectangular area and then attach() DisplayObjects so that they automatically fill the area, scaling/stretching in any of the following modes: STRETCH, PROPORTIONAL_INSIDE, PROPORTIONAL_OUTSIDE, NONE, WIDTH_ONLY, or HEIGHT_ONLY. Horizontally align the attached DisplayObjects left, center, or right. Vertically align them top, center, or bottom. Since LiquidArea inherits from the Shape class, so you can alter its width, height, scaleX, scaleY, x,, or y properties and then all of the attached objects will automatically be adjusted accordingly. Attach as many DisplayObjects as you want. To make visualization easy, you can choose a previewColor and set the preview property to true in order to see the area on the stage (or simply use it like a regular Shape by adding it to the display list with addChild(), but the preview property makes it simpler because it automatically ensures that it is behind all of its attached DisplayObjects in the stacking order).

You can set minimum and maximum width/height constraints on a LiquidArea so that stage resizes don't expand or contract it beyond certain values.

With LiquidArea, it's simple to create things like a background that proportionally fills the stage or a bar that always stretches horizontally to fill the stage but stays stuck to the bottom, etc.


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);

//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 CHANGE event listener to the LiquidArea instance
ls.addEventListener(Event.CHANGE, onAreaUpdate);
function onAreaUpdate(event:Event):void {
 trace("updated LiquidArea");
}
LiquidArea 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/.


Public Properties
 PropertyDefined by
 Inheritedheight : Number
AutoFitArea
  maxHeight : Number
Maximum height that a LiquidStage resize is allowed to make the LiquidArea (only affects stage resizes, not when you manually set the height property)
LiquidArea
  maxWidth : Number
Maximum width that a LiquidStage resize is allowed to make the LiquidArea (only affects stage resizes, not when you manually set the width property)
LiquidArea
  minHeight : Number
Minimum height that a LiquidStage resize is allowed to make the LiquidArea (only affects stage resizes, not when you manually set the height property)
LiquidArea
  minWidth : Number
Minimum width that a LiquidStage resize is allowed to make the LiquidArea (only affects stage resizes, not when you manually set the width property)
LiquidArea
 Inheritedpreview : Boolean
To see a visual representation of the area on the screen, set preview to true.
AutoFitArea
 InheritedpreviewColor : uint
The preview color with which the area should be filled, making it easy to visualize on the stage.
AutoFitArea
 Inheritedrotation : Number
AutoFitArea
 InheritedscaleX : Number
AutoFitArea
 InheritedscaleY : Number
AutoFitArea
 Inheritedwidth : Number
AutoFitArea
 Inheritedx : Number
AutoFitArea
 Inheritedy : Number
AutoFitArea
Public Methods
 MethodDefined by
  
LiquidArea(parent:DisplayObjectContainer, x:Number, y:Number, width:Number, height:Number, previewColor:uint = 0xFF0000, minWidth:Number = 0, minHeight:Number = 0, maxWidth:Number = 99999999, maxHeight:Number = 99999999, autoPinCorners:Boolean = true, liquidStage:LiquidStage = null, strict:Boolean = false)
Constructor
LiquidArea
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Allows you to add an Event.CHANGE event listener.
AutoFitArea
 Inherited
attach(target:DisplayObject, scaleMode:String = "proportionalInside", hAlign:String = "center", vAlign:String = "center", crop:Boolean = false, minWidth:Number = 0, maxWidth:Number = 999999999, minHeight:Number = 0, maxHeight:Number = 999999999, calculateVisible:Boolean = false, customAspectRatio:Number):void
Attaches a DisplayObject, causing it to automatically scale to fit the area in one of the following ScaleModes: STRETCH, PROPORTIONAL_INSIDE, PROPORTIONAL_OUTSIDE, NONE, WIDTH_ONLY, or HEIGHT_ONLY.
AutoFitArea
  
createAround(target:DisplayObject, scaleMode:String = "proportionalInside", hAlign:String = "center", vAlign:String = "center", crop:Boolean = false, previewColor:uint = 0xFF0000, minWidth:Number = 0, minHeight:Number = 0, maxWidth:Number = 99999999, maxHeight:Number = 99999999, autoPinCorners:Boolean = true, calculateVisible:Boolean = false, liquidStage:LiquidStage = null, reconcile:Boolean = true, strict:Boolean = false):LiquidArea
[static] Creates an LiquidArea with its initial dimensions fit precisely around a target DisplayObject.
LiquidArea
  
destroy():void
Destroys the instance by releasing all DisplayObjects, setting preview to false, and nulling references to the parent, ensuring that garbage collection isn't hindered.
LiquidArea
 Inherited
disableTweenMode():void
Disables the area's tween mode; normally, any changes to the area's transform properties like x, y, scaleX, scaleY, width, or height will force an immediate update() call but when the area is in tween mode, that automatic update() is suspended.
AutoFitArea
  
dynamicTween(duration:Number, vars:Object):TweenLite
If you want to tween a LiquidArea's transform properties (like x, y, width, height, scaleX, or scaleY), you may want the destination values to be dynamically affected by LiquidStage resizes and that's exactly what dynamicTween() allows.
LiquidArea
 Inherited
enableTweenMode():void
Enables the area's tween mode; normally, any changes to the area's transform properties like x, y, scaleX, scaleY, width, or height will force an immediate update() call but when the area is in tween mode, that automatic update() is suspended.
AutoFitArea
 Inherited
getAttachedObjects():Array
Returns an Array of all attached DisplayObjects.
AutoFitArea
  
pinCorners(topLeft:PinPoint, bottomRight:PinPoint, reconcile:Boolean = true, tweenDuration:Number = 0, tweenVars:Object = null, strict:Boolean = false):void
By default, a LiquidArea pins itself to the TOP_LEFT and BOTTOM_RIGHT PinPoints of the LiquidStage, but this method allows you to pin the corners to different PinPoints if you prefer.
LiquidArea
 Inherited
release(target:DisplayObject):Boolean
Releases control of an attached DisplayObject.
AutoFitArea
 Inherited
update(event:Event = null):void
Forces the area to update, making any necessary adjustments to the scale/position of attached objects.
AutoFitArea
Property detail
maxHeightproperty
public var maxHeight:Number

Maximum height that a LiquidStage resize is allowed to make the LiquidArea (only affects stage resizes, not when you manually set the height property)

maxWidthproperty 
public var maxWidth:Number

Maximum width that a LiquidStage resize is allowed to make the LiquidArea (only affects stage resizes, not when you manually set the width property)

minHeightproperty 
public var minHeight:Number

Minimum height that a LiquidStage resize is allowed to make the LiquidArea (only affects stage resizes, not when you manually set the height property)

minWidthproperty 
public var minWidth:Number

Minimum width that a LiquidStage resize is allowed to make the LiquidArea (only affects stage resizes, not when you manually set the width property)

Constructor detail
LiquidArea()constructor
public function LiquidArea(parent:DisplayObjectContainer, x:Number, y:Number, width:Number, height:Number, previewColor:uint = 0xFF0000, minWidth:Number = 0, minHeight:Number = 0, maxWidth:Number = 99999999, maxHeight:Number = 99999999, autoPinCorners:Boolean = true, liquidStage:LiquidStage = null, strict:Boolean = false)

Constructor

Parameters
parent:DisplayObjectContainer — The parent DisplayObjectContainer in which the LiquidArea should be created. All objects that get attached must share the same parent.
 
x:Number — x coordinate of the LiquidArea's upper left corner
 
y:Number — y coordinate of the LiquidArea's upper left corner
 
width:Number — width of the LiquidArea
 
height:Number — height of the LiquidArea
 
previewColor:uint (default = 0xFF0000) — color of the LiquidArea (which won't be seen unless you set preview to true or manually add it to the display list with addChild())
 
minWidth:Number (default = 0) — Minimum width that a LiquidStage resize is allowed to make the LiquidArea (only affects stage resizes, not when you manually set the width property)
 
minHeight:Number (default = 0) — Minimum height that a LiquidStage resize is allowed to make the LiquidArea (only affects stage resizes, not when you manually set the height property)
 
maxWidth:Number (default = 99999999) — Maximum width that a LiquidStage resize is allowed to make the LiquidArea (only affects stage resizes, not when you manually set the width property)
 
maxHeight:Number (default = 99999999) — Maximum height that a LiquidStage resize is allowed to make the LiquidArea (only affects stage resizes, not when you manually set the height property)
 
autoPinCorners:Boolean (default = true) — By default, the LiquidArea's upper left corner is pinned to the LiquidStage's TOP_LEFT PinPoint, and its lower right corner is pinned to the LiquidStage's BOTTOM_RIGHT PinPoint, but to skip the pinning, set autoPinCorners to false.
 
liquidStage:LiquidStage (default = null) — Optionally declare the LiquidStage instance to which this LiquidArea should be associated. If none is defined, the class will try to determine the LiquidStage instance based on the parent's stage property (LiquidStage.getByStage()). The only time it is useful to specifically declare the LiquidStage instance is when you plan to subload a swf that uses LiquidStage into another swf that also has a LiquidStage instance (thus they share the same stage).
 
strict:Boolean (default = false) — If strict is true, the top left and bottom right corners will always retain their absolute distance from the PinPoints that are used in pinCorners() (the LiquidStage's TOP_LEFT and BOTTOM_RIGHT by default) instead of adjusting themselves in a relative fashion. If they are not strict, you could alter the position/size of the LiquidArea independently and then when the stage is resized, the corners would only move by however much the stage changed (more flexible).
Method detail
createAround()method
public static function createAround(target:DisplayObject, scaleMode:String = "proportionalInside", hAlign:String = "center", vAlign:String = "center", crop:Boolean = false, previewColor:uint = 0xFF0000, minWidth:Number = 0, minHeight:Number = 0, maxWidth:Number = 99999999, maxHeight:Number = 99999999, autoPinCorners:Boolean = true, calculateVisible:Boolean = false, liquidStage:LiquidStage = null, reconcile:Boolean = true, strict:Boolean = false):LiquidArea

Creates an LiquidArea with its initial dimensions fit precisely around a target DisplayObject. It also attaches the target DisplayObject immediately.

Parameters
target:DisplayObject — The target DisplayObject whose position and dimensions the LiquidArea should match initially.
 
scaleMode:String (default = "proportionalInside") — Determines how the target should be scaled to fit the LiquidArea. ScaleMode choices are: STRETCH, PROPORTIONAL_INSIDE, PROPORTIONAL_OUTSIDE, NONE, WIDTH_ONLY, or HEIGHT_ONLY.
 
hAlign:String (default = "center") — Horizontal alignment of the target inside the LiquidArea. AlignMode choices are: LEFT, CENTER, and RIGHT.
 
vAlign:String (default = "center") — Vertical alignment of the target inside the LiquidArea. AlignMode choices are: TOP, CENTER, and BOTTOM.
 
crop:Boolean (default = false) — If true, a mask will be created so that the target will be cropped wherever it exceeds the bounds of the AutoFitArea.
 
previewColor:uint (default = 0xFF0000) — color of the LiquidArea (which won't be seen unless you set preview to true or manually add it to the display list with addChild())
 
minWidth:Number (default = 0) — Minimum width that a LiquidStage resize is allowed to make the LiquidArea (only affects stage resizes, not when you manually set the width property)
 
minHeight:Number (default = 0) — Minimum height that a LiquidStage resize is allowed to make the LiquidArea (only affects stage resizes, not when you manually set the height property)
 
maxWidth:Number (default = 99999999) — Maximum width that a LiquidStage resize is allowed to make the LiquidArea (only affects stage resizes, not when you manually set the width property)
 
maxHeight:Number (default = 99999999) — Maximum height that a LiquidStage resize is allowed to make the LiquidArea (only affects stage resizes, not when you manually set the height property)
 
autoPinCorners:Boolean (default = true) — By default, the LiquidArea's upper left corner is pinned to the LiquidStage's TOP_LEFT PinPoint, and its lower right corner is pinned to the LiquidStage's BOTTOM_RIGHT PinPoint, but to skip the pinning, set autoPinCorners to false.
 
calculateVisible:Boolean (default = false) — If true, only the visible portions of the target will be taken into account when determining its position and scale which can be useful for objects that have masks applied (otherwise, Flash reports their width/height and getBounds() values including the masked portions). Setting calculateVisible to true degrades performance, so only use it when absolutely necessary.
 
liquidStage:LiquidStage (default = null) — Optionally declare the LiquidStage instance to which this LiquidArea should be associated. If none is defined, the class will try to determine the LiquidStage instance based on the parent's stage property (LiquidStage.getByStage()). The only time it is useful to specifically declare the LiquidStage instance is when you plan to subload a swf that uses LiquidStage into another swf that also has a LiquidStage instance (thus they share the same stage).
 
reconcile:Boolean (default = true) — If true, LiquidStage will be reverted to retroMode (briefly forcing the stage to the base width/height) before creating the LiquidArea. This effectively acts as though the target was attached BEFORE the stage was scaled. If you create the LiquidArea after the stage has been scaled and you don't want it to reconcile with the initial base stage size initially, set reconcile to false.
 
strict:Boolean (default = false) — If strict is true, the top left and bottom right corners will always retain their absolute distance from the PinPoints that are used in pinCorners() (the LiquidStage's TOP_LEFT and BOTTOM_RIGHT by default) instead of adjusting themselves in a relative fashion. If they are not strict, you could alter the position/size of the LiquidArea independently and then when the stage is resized, the corners would only move by however much the stage changed (more flexible).

Returns
LiquidArea — An LiquidArea instance
destroy()method 
public override function destroy():void

Destroys the instance by releasing all DisplayObjects, setting preview to false, and nulling references to the parent, ensuring that garbage collection isn't hindered.

dynamicTween()method 
public function dynamicTween(duration:Number, vars:Object):TweenLite

If you want to tween a LiquidArea's transform properties (like x, y, width, height, scaleX, or scaleY), you may want the destination values to be dynamically affected by LiquidStage resizes and that's exactly what dynamicTween() allows. For example, maybe you start tweening to a width of 100 but in the middle of the tween, the user widens the stage by 50 pixels - with a tween generated by dynamicTween(), the width will end up being 150 instead of 100. Only one dynamic tween can be in effect at any given time.

Parameters
duration:Number — The duration of the tween in seconds (unless useFrames:true is passed in through the vars object in which case the duration is described in terms of frames)
 
vars:Object — The tween vars object that defines the destination values, ease, etc. For example {width:100, height:200, ease:Elastic.easeOut}

Returns
TweenLite — A TweenLite instance
pinCorners()method 
public function pinCorners(topLeft:PinPoint, bottomRight:PinPoint, reconcile:Boolean = true, tweenDuration:Number = 0, tweenVars:Object = null, strict:Boolean = false):void

By default, a LiquidArea pins itself to the TOP_LEFT and BOTTOM_RIGHT PinPoints of the LiquidStage, but this method allows you to pin the corners to different PinPoints if you prefer.

Parameters
topLeft:PinPoint — The PinPoint to which the top left corner of the LiquidArea should be pinned.
 
bottomRight:PinPoint — The PinPoint to which the bottom right corner of the LiquidArea should be pinned.
 
reconcile:Boolean (default = true) — If true, the LiquidArea's position and dimensions will immediately be adjusted as though it was attached BEFORE the stage was scaled. If you create the LiquidArea 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 LiquidArea tween to its new position and dimensions instead of immediately moving/resizing, 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})
 
strict:Boolean (default = false) — If strict is true, the top left and bottom right corners will always retain their absolute distance from the PinPoints that are used in pinCorners() (the LiquidStage's TOP_LEFT and BOTTOM_RIGHT by default) instead of adjusting themselves in a relative fashion. If they are not strict, you could alter the position/size of the LiquidArea independently and then when the stage is resized, the corners would only move by however much the stage changed (more flexible).