Packagecom.greensock
Classpublic class FlexBlitMask
InheritanceFlexBlitMask Inheritance mx.core.UIComponent

[AS3 only] A FlexBlitMask is basically a rectangular UIComponent that acts as a high-performance mask for a DisplayObject by caching a bitmap version of it and blitting only the pixels that should be visible at any given time, although its bitmapMode can be turned off to restore interactivity in the DisplayObject whenever you want. It is a Flex-friendly version of BlitMask. When scrolling very large images or text blocks, a FlexBlitMask can greatly improve performance, especially on mobile devices that have weaker processors. Here are some of the conveniences FlexBlitMask offers:

View the examples



Public Properties
 PropertyDefined By
  autoUpdate : Boolean
If true, the FlexBlitMask will automatically watch the target to see if its position/scale/rotation has changed on each frame (while bitmapMode is true) and if so, it will update() to make sure the FlexBlitMask always stays synced with the target.
FlexBlitMask
  bitmapMode : Boolean
When true, the FlexBlitMask optimizes itself for performance by setting the target's visible property to false (greatly reducing the load on Flash's graphics rendering routines) and uses its internally cached bitmap version of the target to redraw only the necessary pixels inside the masked area.
FlexBlitMask
  fillColor : uint
The ARGB hexadecimal color that should fill the empty areas of the FlexBlitMask.
FlexBlitMask
  height : Number
[override] Height of the FlexBlitMask
FlexBlitMask
  rotation : Number
[override] [write-only] Rotation of the FlexBlitMask (always 0 because FlexBlitMasks can't be rotated!)
FlexBlitMask
  scaleX : Number
[override] scaleX (warning: altering the scaleX won't actually change its value - instead, it affects the width property accordingly)
FlexBlitMask
  scaleY : Number
[override] scaleY (warning: altering the scaleY won't actually change its value - instead, it affects the height property accordingly)
FlexBlitMask
  scrollX : Number
Typically a value between 0 and 1 indicating the target's position in relation to the FlexBlitMask on the x-axis where 0 is at the beginning, 0.5 is scrolled to exactly the halfway point, and 1 is scrolled all the way.
FlexBlitMask
  scrollY : Number
Typically a value between 0 and 1 indicating the target's position in relation to the FlexBlitMask on the y-axis where 0 is at the beginning, 0.5 is scrolled to exactly the halfway point, and 1 is scrolled all the way.
FlexBlitMask
  smoothing : Boolean
If false (the default), the bitmap (and the FlexBlitMask's x/y coordinates) will be rendered only on whole pixels which is faster in terms of processing.
FlexBlitMask
  target : DisplayObject
The target DisplayObject that the FlexBlitMask should mask
FlexBlitMask
  width : Number
[override] Width of the FlexBlitMask
FlexBlitMask
  wrap : Boolean
If true, the bitmap will be wrapped around to the opposite side when it scrolls off one of the edges (only in bitmapMode of course), like the FlexBlitMask is filled with a grid of bitmap copies of the target.
FlexBlitMask
  wrapOffsetX : Number
When wrap is true, wrapOffsetX controls how many pixels along the x-axis the wrapped copies of the bitmap are spaced.
FlexBlitMask
  wrapOffsetY : Number
When wrap is true, wrapOffsetY controls how many pixels along the y-axis the wrapped copies of the bitmap are spaced.
FlexBlitMask
  x : Number
[override] x coordinate of the FlexBlitMask (it will automatically be forced to whole pixel values if smoothing is false).
FlexBlitMask
  y : Number
[override] y coordinate of the FlexBlitMask (it will automatically be forced to whole pixel values if smoothing is false).
FlexBlitMask
Public Methods
 MethodDefined By
  
FlexBlitMask(target:DisplayObject = null, x:Number = 0, y:Number = 0, width:Number = 100, height:Number = 100, smoothing:Boolean = false, autoUpdate:Boolean = true, fillColor:uint = 0x00000000, wrap:Boolean = false)
Constructor
FlexBlitMask
  
disableBitmapMode(event:Event = null):void
Identical to setting bitmapMode = false but this method simplifies adding that functionality to tweens or using it as an event handler.
FlexBlitMask
  
dispose():void
Disposes of the FlexBlitMask and its internal BitmapData instances, releasing them for garbage collection.
FlexBlitMask
  
enableBitmapMode(event:Event = null):void
Identical to setting bitmapMode = true but this method simplifies adding that functionality to tweens or using it as an event handler.
FlexBlitMask
  
Repositions the target so that it is visible within the BlitMask, as though wrap was enabled (this method is called automatically when bitmapMode is disabled while wrap is true).
FlexBlitMask
  
setActualSize(w:Number, h:Number):void
[override]
FlexBlitMask
  
setSize(width:Number, height:Number):void
Sets the width and height of the FlexBlitMask.
FlexBlitMask
  
update(event:Event = null, forceRecaptureBitmap:Boolean = false):void
Updates the FlexBlitMask's internal bitmap to reflect the target's current position/scale/rotation.
FlexBlitMask
Property Detail
autoUpdateproperty
autoUpdate:Boolean

If true, the FlexBlitMask will automatically watch the target to see if its position/scale/rotation has changed on each frame (while bitmapMode is true) and if so, it will update() to make sure the FlexBlitMask always stays synced with the target. This is the easiest way to use FlexBlitMask but it is slightly less efficient than manually calling update() whenever you need to. Keep in mind that if you're tweening with TweenLite or TweenMax, you can simply set its onUpdate to the FlexBlitMask's update() method to keep things synced. Like onUpdate:myFlexBlitMask.update.


Implementation
    public function get autoUpdate():Boolean
    public function set autoUpdate(value:Boolean):void
bitmapModeproperty 
bitmapMode:Boolean

When true, the FlexBlitMask optimizes itself for performance by setting the target's visible property to false (greatly reducing the load on Flash's graphics rendering routines) and uses its internally cached bitmap version of the target to redraw only the necessary pixels inside the masked area. Since only a bitmap version of the target is shown while in bitmapMode, the target won't be interactive. So if you have buttons and other objects that normally react to MouseEvents, they won't while in bitmapMode. If you need the interactivity, simply set bitmapMode to false and then it will turn the target's visible property back to true and its mask property to the FlexBlitMask itself. Typically it is best to turn bitmapMode on at least when you're animating the target or the FlexBlitMask itself, and then when the tween/animation is done and you need interactivity, set bitmapMode back to false. For example: var bm:FlexBlitMask = new FlexBlitMask(mc, 0, 0, 300, 200, true); TweenLite.to(mc, 3, {x:200, onUpdate:bm.update, onComplete:completeHandler}); function completeHandler():void { bm.bitmapMode = false; }


Implementation
    public function get bitmapMode():Boolean
    public function set bitmapMode(value:Boolean):void

See also

fillColorproperty 
fillColor:uint

The ARGB hexadecimal color that should fill the empty areas of the FlexBlitMask. By default, it is transparent (0x00000000). If you wanted a red color, for example, it would be 0xFFFF0000.


Implementation
    public function get fillColor():uint
    public function set fillColor(value:uint):void
heightproperty 
height:Number[override]

Height of the FlexBlitMask


Implementation
    public function get height():Number
    public function set height(value:Number):void
rotationproperty 
rotation:Number  [write-only] [override]

Rotation of the FlexBlitMask (always 0 because FlexBlitMasks can't be rotated!)


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

scaleX (warning: altering the scaleX won't actually change its value - instead, it affects the width property accordingly)


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

scaleY (warning: altering the scaleY won't actually change its value - instead, it affects the height property accordingly)


Implementation
    public function get scaleY():Number
    public function set scaleY(value:Number):void
scrollXproperty 
scrollX:Number

Typically a value between 0 and 1 indicating the target's position in relation to the FlexBlitMask on the x-axis where 0 is at the beginning, 0.5 is scrolled to exactly the halfway point, and 1 is scrolled all the way. This makes it very easy to animate the scroll. For example, to scroll from beginning to end over 5 seconds, you could do: myFlexBlitMask.scrollX = 0; TweenLite.to(myFlexBlitMask, 5, {scrollX:1});


Implementation
    public function get scrollX():Number
    public function set scrollX(value:Number):void

See also

scrollYproperty 
scrollY:Number

Typically a value between 0 and 1 indicating the target's position in relation to the FlexBlitMask on the y-axis where 0 is at the beginning, 0.5 is scrolled to exactly the halfway point, and 1 is scrolled all the way. This makes it very easy to animate the scroll. For example, to scroll from beginning to end over 5 seconds, you could do: myFlexBlitMask.scrollY = 0; TweenLite.to(myFlexBlitMask, 5, {scrollY:1});


Implementation
    public function get scrollY():Number
    public function set scrollY(value:Number):void

See also

smoothingproperty 
smoothing:Boolean

If false (the default), the bitmap (and the FlexBlitMask's x/y coordinates) will be rendered only on whole pixels which is faster in terms of processing. However, for the best quality and smoothest animation, set smoothing to true.


Implementation
    public function get smoothing():Boolean
    public function set smoothing(value:Boolean):void
targetproperty 
target:DisplayObject

The target DisplayObject that the FlexBlitMask should mask


Implementation
    public function get target():DisplayObject
    public function set target(value:DisplayObject):void
widthproperty 
width:Number[override]

Width of the FlexBlitMask


Implementation
    public function get width():Number
    public function set width(value:Number):void
wrapproperty 
wrap:Boolean

If true, the bitmap will be wrapped around to the opposite side when it scrolls off one of the edges (only in bitmapMode of course), like the FlexBlitMask is filled with a grid of bitmap copies of the target. Use the wrapOffsetX and wrapOffsetY properties to affect how far apart the copies are from each other. You can reposition the target anywhere and FlexBlitMask will align the copies accordingly.


Implementation
    public function get wrap():Boolean
    public function set wrap(value:Boolean):void

See also

wrapOffsetXproperty 
wrapOffsetX:Number

When wrap is true, wrapOffsetX controls how many pixels along the x-axis the wrapped copies of the bitmap are spaced. It is essentially the gap between the copies (although you can use a negative value or 0 to avoid any gap).


Implementation
    public function get wrapOffsetX():Number
    public function set wrapOffsetX(value:Number):void

See also

wrapOffsetYproperty 
wrapOffsetY:Number

When wrap is true, wrapOffsetY controls how many pixels along the y-axis the wrapped copies of the bitmap are spaced. It is essentially the gap between the copies (although you can use a negative value or 0 to avoid any gap).


Implementation
    public function get wrapOffsetY():Number
    public function set wrapOffsetY(value:Number):void

See also

xproperty 
x:Number[override]

x coordinate of the FlexBlitMask (it will automatically be forced to whole pixel values if smoothing is false).


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

y coordinate of the FlexBlitMask (it will automatically be forced to whole pixel values if smoothing is false).


Implementation
    public function get y():Number
    public function set y(value:Number):void
Constructor Detail
FlexBlitMask()Constructor
public function FlexBlitMask(target:DisplayObject = null, x:Number = 0, y:Number = 0, width:Number = 100, height:Number = 100, smoothing:Boolean = false, autoUpdate:Boolean = true, fillColor:uint = 0x00000000, wrap:Boolean = false)

Constructor

Parameters
target:DisplayObject (default = null) — The DisplayObject that will be masked by the FlexBlitMask
 
x:Number (default = 0) — x coorinate of the upper left corner of the FlexBlitMask. If smoothing is false, the x coordinate will be rounded to the closest integer.
 
y:Number (default = 0) — y coordinate of the upper right corner of the FlexBlitMask
 
width:Number (default = 100) — width of the FlexBlitMask (in pixels)
 
height:Number (default = 100) — height of the FlexBlitMask (in pixels)
 
smoothing:Boolean (default = false) — If false (the default), the bitmap (and the FlexBlitMask's x/y coordinates) will be rendered only on whole pixels which is faster in terms of processing. However, for the best quality and smoothest animation, set smoothing to true.
 
autoUpdate:Boolean (default = true) — If true (the default), the FlexBlitMask will automatically watch the target to see if its position/scale/rotation has changed on each frame (while bitmapMode is true) and if so, it will update() to make sure the FlexBlitMask always stays synced with the target. This is the easiest way to use FlexBlitMask but it is slightly less efficient than manually calling update() whenever you need to. Keep in mind that if you're tweening with TweenLite or TweenMax, you can simply set its onUpdate to the FlexBlitMask's update() method to keep things synced. Like onUpdate:myFlexBlitMask.update.
 
fillColor:uint (default = 0x00000000) — The ARGB hexadecimal color that should fill the empty areas of the FlexBlitMask. By default, it is transparent (0x00000000). If you wanted a red color, for example, it would be 0xFFFF0000.
 
wrap:Boolean (default = false) — If true, the bitmap will be wrapped around to the opposite side when it scrolls off one of the edges (only in bitmapMode of course), like the FlexBlitMask is filled with a grid of bitmap copies of the target. Use the wrapOffsetX and wrapOffsetY properties to affect how far apart the copies are from each other.
Method Detail
disableBitmapMode()method
public function disableBitmapMode(event:Event = null):void

Identical to setting bitmapMode = false but this method simplifies adding that functionality to tweens or using it as an event handler. For example, to enable bitmapMode at the beginning of a tween and then disable it when the tween completes, you could do: TweenLite.to(mc, 3, {x:400, onStart:myFlexBlitMask.enableBitmapMode, onUpdate:myFlexBlitMask.update, onComplete:myFlexBlitMask.disableBitmapMode});

Parameters

event:Event (default = null) — An optional Event that isn't used internally but makes it possible to use the method as an event handler like addEventListener(MouseEvent.CLICK, myFlexBlitMask.disableBitmapMode).

See also

dispose()method 
public function dispose():void

Disposes of the FlexBlitMask and its internal BitmapData instances, releasing them for garbage collection.

enableBitmapMode()method 
public function enableBitmapMode(event:Event = null):void

Identical to setting bitmapMode = true but this method simplifies adding that functionality to tweens or using it as an event handler. For example, to enable bitmapMode at the beginning of a tween and then disable it when the tween completes, you could do: TweenLite.to(mc, 3, {x:400, onStart:myFlexBlitMask.enableBitmapMode, onUpdate:myFlexBlitMask.update, onComplete:myFlexBlitMask.disableBitmapMode});

Parameters

event:Event (default = null) — An optional Event that isn't used internally but makes it possible to use the method as an event handler like addEventListener(MouseEvent.CLICK, myFlexBlitMask.enableBitmapMode).

See also

normalizePosition()method 
public function normalizePosition():void

Repositions the target so that it is visible within the BlitMask, as though wrap was enabled (this method is called automatically when bitmapMode is disabled while wrap is true). For example, if you tween the target way off the edge of the BlitMask and have wrap enabled, it will appear to come back in from the other side even though the raw coordinates of the target would indicate that it is outside the BlitMask. If you want to force the coordinates to normalize so that they reflect that wrapped position, simply call normalizePosition(). It will automatically choose the coordinates that would maximize the visible portion of the target if a seam is currently showing.

setActualSize()method 
override public function setActualSize(w:Number, h:Number):void

Parameters

w:Number
 
h:Number

setSize()method 
public function setSize(width:Number, height:Number):void

Sets the width and height of the FlexBlitMask. Keep in mind that a FlexBlitMask should not be rotated or scaled. You can also directly set the width or height properties.

Parameters

width:Number — The width of the FlexBlitMask
 
height:Number — The height of the FlexBlitMask

See also

update()method 
public function update(event:Event = null, forceRecaptureBitmap:Boolean = false):void

Updates the FlexBlitMask's internal bitmap to reflect the target's current position/scale/rotation. This is a very important method that you'll need to call whenever visual or transformational changes are made to the target so that the FlexBlitMask remains synced with it.

Parameters

event:Event (default = null) — An optional Event object (which isn't used at all internally) in order to make it easier to use update() as an event handler. For example, you could addEventListener(Event.ENTER_FRAME, myFlexBlitMask.update) to make sure it is updated on every frame (although it would be more efficient to simply set autoUpdate to true in this case).
 
forceRecaptureBitmap:Boolean (default = false) — Normally, the cached bitmap of the target is only recaptured if its scale or rotation changed because doing so is rather processor-intensive, but you can force a full update (and regeneration of the cached bitmap) by setting forceRecaptureBitmap to true.

Examples
Example AS3 code:


    
        
    
    
    
    
    

Notes: Copyright 2011-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.