API Documentation | All Packages | All Classes | Index | Frames No Frames |
Class LiquidArea

Package | com.greensock.layout
Class | public class LiquidArea
Inheritance | LiquidArea AutoFitArea 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_OUTSIDE and crops the extra content that spills over the edges
    area.attach(myImage, {scaleMode:ScaleMode.PROPORTIONAL_OUTSIDE, crop:true});

    //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 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
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined by
--- | --- | ---
|  | height : 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
|  | preview : Boolean To see a visual representation of the area on the screen, set `preview` to `true`. | AutoFitArea
|  | previewColor : uint The preview color with which the area should be filled, making it easy to visualize on the stage. | AutoFitArea
|  | rotation : Number | AutoFitArea
|  | scaleX : Number | AutoFitArea
|  | scaleY : Number | AutoFitArea
|  | width : Number | AutoFitArea
|  | x : Number | AutoFitArea
|  | y : Number | AutoFitArea

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined 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
|  | 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
|  | attach(target:DisplayObject, vars:Object = null, ... args):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, vars:Object = null, ... args):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
|  | 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
|  | 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
|  | 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
|  | release(target:DisplayObject):Boolean Releases control of an attached DisplayObject. | AutoFitArea
|  | update(event:Event = null):void Forces the area to update, making any necessary adjustments to the scale/position of attached objects. | AutoFitArea

Property detail

maxHeight | property

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

maxWidth | property |

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

minHeight | property |

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

minWidth | property |

`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, vars:Object = null, ... args):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.
| `vars:Object` (default = `null`)`` — An object used for defining various optional parameters (see below for list) - this is more readable and concise than defining 11 or more normal arguments. For example, `createAround(mc, {scaleMode:"proportionalOutside", crop:true});` instead of `createAround(mc, "proportionalOutside", "center", "center", true, 0, 99999999, 0, 99999999, false, NaN, false);`. The following optional parameters are recognized: scaleMode : String - Determines how the target should be scaled to fit the area. Use the ScaleMode class constants: `STRETCH, PROPORTIONAL_INSIDE, PROPORTIONAL_OUTSIDE, NONE, WIDTH_ONLY,` or `HEIGHT_ONLY` hAlign : String - Horizontal alignment of the target inside the area. Use the AlignMode class constants: `LEFT`, `CENTER`, and `RIGHT`. vAlign : String - Vertical alignment of the target inside the area. Use the AlignMode class constants: `TOP`, `CENTER`, and `BOTTOM`. crop : Boolean - If true, a mask will be created and added to the display list so that the target will be cropped wherever it exceeds the bounds of the AutoFitArea. roundPosition : Boolean - To force the target's x/y position to snap to whole pixel values, set `roundPosition` to `true` (it is `false` by default). customBoundsTarget : DisplayObject - A DisplayObject that AutoFitArea/LiquidArea should use when measuring bounds instead of the `target`. For example, maybe the target contains 3 boxes arranged next to each other, left-to-right and instead of fitting ALL of those boxes into the area, you only want the center one fit into the area. In this case, you can define the customBoundsTarget as that center box so that the AutoFitArea/LiquidArea only uses it when calculating bounds. Make sure that the object is in the display list (its `visible` property can be set to false if you want to use an invisible object to define custom bounds). minWidth : Number - Minimum width to which the target is allowed to scale maxWidth : Number - Maximum width to which the target is allowed to scale minHeight : Number - Minimum height to which the target is allowed to scale maxHeight : Number - Maximum height to which the target is allowed to scale calculateVisible : Boolean - 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. customAspectRatio : Number - Normally if you set the `scaleMode` to `PROPORTIONAL_INSIDE` or `PROPORTIONAL_OUTSIDE`, its native (unscaled) dimensions will be used to determine the proportions (aspect ratio), but if you prefer to define a custom width-to-height ratio, use `customAspectRatio`. For example, if an item is 100 pixels wide and 50 pixels tall at its native size, the aspect ratio would be 100/50 or 2. If, however, you want it to be square (a 1-to-1 ratio), the `customAspectRatio` would be 1. previewColor : uint - The preview color of the AutoFitArea (default is 0xFF0000). To preview, you must set the AutoFitArea's `visible` property to true (it is false by default). reconcile : Boolean - 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`. autoPinCorners : Boolean - 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. strict : Boolean - 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). liquidStage : LiquidStage - 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).
| `... args`

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