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

Package | com.greensock.layout
Class | public class AutoFitArea
Inheritance | AutoFitArea flash.display.Shape
Subclasses | LiquidArea

AutoFitArea 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. AutoFitArea extends the `Shape` class, so you can alter the width/height/scaleX/scaleY/x/y properties of the AutoFitArea and then all of the attached objects will automatically be affected. Attach as many DisplayObjects as you want. To make visualization easy, you can set the `previewColor` to any color 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).
When you `attach()` a DisplayObject, you can define a minimum and maximum width and height. AutoFitArea doesn't require that the DisplayObject's registration point be in its upper left corner either. You can even set the `calculateVisible` parameter to true when attaching an object so that AutoFitArea will ignore masked areas inside the DisplayObject (this is more processor-intensive, so beware).
For scaling, AutoFitArea alters the DisplayObject's `width` and/or `height` properties unless it is rotated in which case it alters the DisplayObject's `transform.matrix` directly so that accurate stretching/skewing can be accomplished.
There is also a `LiquidArea` class that extends AutoFitArea and integrates with LiquidStage so that it automatically adjusts its size whenever the stage is resized. This makes it 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 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:AutoFitArea = new AutoFitArea(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, set preview to true (by default previewColor is red)
    area.preview = true;

    //attach a CHANGE event listener to the area
    area.addEventListener(Event.CHANGE, onAreaUpdate);
    function onAreaUpdate(event:Event):void {
     trace("updated AutoFitArea");
    }

    //to create an AutoFitArea exactly around a "myImage" DisplayObject so that it conforms its initial dimensions around the DisplayObject, use the static createAround() method:
    var area:AutoFitArea = AutoFitArea.createAround(myImage);

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://www.greensock.com/club/.

Public Properties

| Property | Defined by
--- | --- | ---
|  | height : Number [write-only] | AutoFitArea
|  | 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 [write-only] | AutoFitArea
|  | scaleX : Number [write-only] | AutoFitArea
|  | scaleY : Number [write-only] | AutoFitArea
|  | width : Number [write-only] | AutoFitArea
|  | x : Number [write-only] | AutoFitArea
|  | y : Number [write-only] | AutoFitArea

Public Methods

| Method | Defined by
--- | --- | ---
|  | AutoFitArea(parent:DisplayObjectContainer, x:Number = 0, y:Number = 0, width:Number = 100, height:Number = 100, previewColor:uint = 0xFF0000) Constructor | AutoFitArea
|  | 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):AutoFitArea [static] Creates an AutoFitArea with its initial dimensions fit precisely around a target DisplayObject. | AutoFitArea
|  | 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. | AutoFitArea
|  | 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
|  | 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
|  | 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

height | property

`height:Number` [write-only]

Implementation
`public function set height(value:Number):void`

preview | property |

`preview:Boolean` [read-write]

To see a visual representation of the area on the screen, set `preview` to `true`. Doing so will add the area to the display list behind any DisplayObjects that have been attached.

Implementation
`public function get preview():Boolean`
`public function set preview(value:Boolean):void`

previewColor | property |

`previewColor:uint` [read-write]

The preview color with which the area should be filled, making it easy to visualize on the stage. You will not see this color unless you set `preview` to true or manually add the area to the display list with addChild().

Implementation
`public function get previewColor():uint`
`public function set previewColor(value:uint):void`

rotation | property |

`rotation:Number` [write-only]

Implementation
`public function set rotation(value:Number):void`

scaleX | property |

`scaleX:Number` [write-only]

Implementation
`public function set scaleX(value:Number):void`

scaleY | property |

`scaleY:Number` [write-only]

Implementation
`public function set scaleY(value:Number):void`

width | property |

`width:Number` [write-only]

Implementation
`public function set width(value:Number):void`

x | property |

`x:Number` [write-only]

Implementation
`public function set x(value:Number):void`

y | property |

`y:Number` [write-only]

Implementation
`public function set y(value:Number):void`
Constructor detail

AutoFitArea | () | constructor

`public function AutoFitArea(parent:DisplayObjectContainer, x:Number = 0, y:Number = 0, width:Number = 100, height:Number = 100, previewColor:uint = 0xFF0000)`

Constructor

Parameters

| `parent:DisplayObjectContainer` — The parent DisplayObjectContainer in which the AutoFitArea should be created. All objects that get attached must share the same parent.
| `x:Number` (default = `0`)`` — x coordinate of the AutoFitArea's upper left corner
| `y:Number` (default = `0`)`` — y coordinate of the AutoFitArea's upper left corner
| `width:Number` (default = `100`)`` — width of the AutoFitArea
| `height:Number` (default = `100`)`` — height of the AutoFitArea
| `previewColor:uint` (default = `0xFF0000`)`` — color of the AutoFitArea (which won't be seen unless you set preview to true or manually add it to the display list with addChild())

Method detail

addEventListener | () | method

`public override function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void`

Allows you to add an `Event.CHANGE` event listener.

Parameters

| `type:String` — Event type (`Event.CHANGE`)
| `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, 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`. Horizontally and vertically align the object within the area as well. When the area resizes, all attached DisplayObjects will automatically be moved/scaled accordingly.

Parameters

| `target:DisplayObject` — The DisplayObject to attach and scale/stretch to fit within the area.
| `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, `attach(mc, {scaleMode:"proportionalOutside", crop:true});` instead of `attach(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.
| `... args`

createAround | () | method |

`public static function createAround(target:DisplayObject, vars:Object = null, ... args):AutoFitArea`

Creates an AutoFitArea 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 AutoFitArea 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).
| `... args`

Returns

| `AutoFitArea` — An AutoFitArea instance

destroy | () | method |

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

disableTweenMode | () | method |

`public function 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. This effects perfomance because if, for example, you tween the area's `x, y, width`, and `height` properties simultaneously, `update()` would get called 4 times each frame (once for each property) even though it only really needs to be called once after all properties were updated inside the tween. So to maximize performance during a tween, it is best to use the tween's `onStart` to call `enableTweenMode()` at the beginning of the tween, use the tween's `onUpdate` to call the area's `update()` method, and then the tween's `onComplete` to call `disableTweenMode()` like so:
`TweenLite.to(myArea, 3, {x:100, y:50, width:300, height:250, onStart:myArea.enableTweenMode, onUpdate:myArea.update, onComplete:myArea.disableTweenMode});`

enableTweenMode | () | method |

`public function 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. This effects perfomance because if, for example, you tween the area's `x, y, width`, and `height` properties simultaneously, `update()` would get called 4 times each frame (once for each property) even though it only really needs to be called once after all properties were updated inside the tween. So to maximize performance during a tween, it is best to use the tween's `onStart` to call `enableTweenMode()` at the beginning of the tween, use the tween's `onUpdate` to call the area's `update()` method, and then the tween's `onComplete` to call `disableTweenMode()` like so:
`TweenLite.to(myArea, 3, {x:100, y:50, width:300, height:250, onStart:myArea.enableTweenMode, onUpdate:myArea.update, onComplete:myArea.disableTweenMode});`

getAttachedObjects | () | method |

`public function getAttachedObjects():Array`

Returns an Array of all attached DisplayObjects.

Returns

| `Array` — An array of all attached objects

release | () | method |

`public function release(target:DisplayObject):Boolean`

Releases control of an attached DisplayObject.

Parameters

| `target:DisplayObject` — The DisplayObject to release

Returns

| `Boolean` — if the target was found and released, this value will be true. If the target isn't attached, it will be false.

update | () | method |

`public function update(event:Event = null):void`

Forces the area to update, making any necessary adjustments to the scale/position of attached objects.

Parameters

| `event:Event` (default = `null`)`` — An optional event (which is unused internally) - this makes it possible to have an ENTER_FRAME or some other listener call this method if, for example, you want the AutoFitArea to constantly update and make any adjustments to attached objects that may have resized or been manually moved.