Packagecom.greensock.layout
Classpublic class AutoFitArea
InheritanceAutoFitArea Inheritance 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.

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 2010-2013, GreenSock. All rights reserved. This work is subject to the terms in http://www.greensock.com/terms_of_use.html or for Club GreenSock members, the software agreement that was issued with the membership.


Public Properties
 PropertyDefined By
  height : Number
[override] [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
[override] [write-only]
AutoFitArea
  scaleX : Number
[override] [write-only]
AutoFitArea
  scaleY : Number
[override] [write-only]
AutoFitArea
  width : Number
[override] [write-only]
AutoFitArea
  x : Number
[override] [write-only]
AutoFitArea
  y : Number
[override] [write-only]
AutoFitArea
Public Methods
 MethodDefined 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
[override] 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
heightproperty
height:Number  [write-only] [override]


Implementation
    public function set height(value:Number):void
previewproperty 
preview:Boolean

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
previewColorproperty 
previewColor:uint

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
rotationproperty 
rotation:Number  [write-only] [override]


Implementation
    public function set rotation(value:Number):void
scaleXproperty 
scaleX:Number  [write-only] [override]


Implementation
    public function set scaleX(value:Number):void
scaleYproperty 
scaleY:Number  [write-only] [override]


Implementation
    public function set scaleY(value:Number):void
widthproperty 
width:Number  [write-only] [override]


Implementation
    public function set width(value:Number):void
xproperty 
x:Number  [write-only] [override]


Implementation
    public function set x(value:Number):void
yproperty 
y:Number  [write-only] [override]


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





Thu Oct 24 2013, 01:43 PM -05:00