Packageflupie.textanim
Classpublic class TextAnim
InheritanceTextAnim Inheritance flash.display.Sprite

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9 and later

A class for dynamic text animation in actionscript 3.

TextAnim works creating blocks of text, then applying functions that you create to each one of them. We call these functions as effects. These functions must receives a TextAnimBlock as a parameter.

Here is the most basic example:

                  
	import flupie.textanim.TextAnim;
	import flupie.textanim.TextAnimBlock;
	 
	var myTextAnim:TextAnim = new TextAnim(myTextField);
	myTextAnim.effects = myEffect;
	myTextAnim.start();
	
	function myEffect(block:TextAnimBlock):void {
		block.scaleY = 2;
	}
               



Public Properties
 PropertyDefined By
  anchorX : String
The horizontal registration of each TextAnimBlock.
TextAnim
  anchorY : String
The vertical registration of each TextAnimBlock.
TextAnim
  blocksVisible : Boolean
Sets the visibility of all blocks.
TextAnim
  delay : Number = 0
Sets the delay (in milliseconds) before start.
TextAnim
  effects : *
Are the effect functions that will be called for all blocks, according to the interval specified.
TextAnim
  firstBlock : TextAnimBlock
The first block reference.
TextAnim
  htmlText : String
Sets a html as text.
TextAnim
  interval : Number = 100
Sets the interval (in milliseconds) between each effect dispatch.
TextAnim
  length : int
Amount of TextAnimBlocks.
TextAnim
  mode : String
Is the way of the effects dispatches will be occurs.
TextAnim
  onBlocksCreated : Function
Callback function called when the blocks are created, or recreated.
TextAnim
  onComplete : Function
Callback function called when the last effect was dispatched.
TextAnim
  onProgress : Function
Callback function called when each effect dispatch.
TextAnim
  onStart : Function
Callback function called when the TextAnim starts.
TextAnim
  source : TextField
The original TextField instance thats TextAnim will use as reference.
TextAnim
  split : String
To specify how the TextAnim will break the text: in chars, words or lines.
TextAnim
  text : String
Changes the text.
TextAnim
  time : Number = 0
Indicates a fixed total time (in milliseconds) of effects dispatches.
TextAnim
Public Methods
 MethodDefined By
  
TextAnim(source:TextField, autoReplace:Boolean = true)
Constructor.
TextAnim
  
To apply the effects to a single block.
TextAnim
  
create(source:TextField, config:Object = null):TextAnim
[static] Creates an instance of TextAnim in a fast way.
TextAnim
  
dispose():void
Clear all blocks, internal references, stops the progress and kill the TextAnim instance.
TextAnim
  
forEachBlocks(callback:Function):void
Apply a function to each block of this TextAnim.
TextAnim
  
setAnchor(anchorX:String, anchorY:String):void
Modify the registration x and y of all blocks.
TextAnim
  
start(delay:Number = 0):void
Starts the flow of effects dispatches, with delay specified.
TextAnim
  
stop():void
Stops the flow of effects dispatches.
TextAnim
Property Detail
anchorXproperty
anchorX:String

The horizontal registration of each TextAnimBlock.

It can be TextAnimAnchor.CENTER, TextAnimAnchor.LEFT, TextAnimAnchor.RIGHT

The default value is TextAnimAnchor.CENTER;.


Implementation
    public function get anchorX():String
    public function set anchorX(value:String):void

See also

anchorYproperty 
anchorY:String

The vertical registration of each TextAnimBlock.

It can be TextAnimAnchor.CENTER, TextAnimAnchor.TOP, TextAnimAnchor.BOTTOM

The default value is TextAnimAnchor.CENTER;.


Implementation
    public function get anchorY():String
    public function set anchorY(value:String):void

See also

blocksVisibleproperty 
blocksVisible:Boolean

Sets the visibility of all blocks.

Change the visible property of each block. In some animations the blocks must be hidden, to show them gradually.


Implementation
    public function get blocksVisible():Boolean
    public function set blocksVisible(value:Boolean):void
delayproperty 
public var delay:Number = 0

Sets the delay (in milliseconds) before start.

The default value is 0.

effectsproperty 
public var effects:*

Are the effect functions that will be called for all blocks, according to the interval specified.

It can be an Array of functions or just one. These functions must receives a TextAnimBlock as a parameter.

Example:

myTextAnim.effects = effect1Function;

or

myTextAnim.effects = [effect1Function, effect2Function];

firstBlockproperty 
public var firstBlock:TextAnimBlock

The first block reference.

TextAnim has a singly linked list of blocks, and this is the head of the list.

The default value is null.

htmlTextproperty 
htmlText:String

Sets a html as text. Like text, all the blocks will be recreated.


Implementation
    public function get htmlText():String
    public function set htmlText(value:String):void

See also

intervalproperty 
public var interval:Number = 100

Sets the interval (in milliseconds) between each effect dispatch.

If the interval is 300, it means that the TextAnim will dispatch an effect each 300 milliseconds, until all the blocks are animated.

The default value is 100.

lengthproperty 
public var length:int

Amount of TextAnimBlocks.

modeproperty 
public var mode:String

Is the way of the effects dispatches will be occurs.

TextAnim dispatch effects in five diferent ways:

The default value is TextAnimMode.FIRST_LAST.

onBlocksCreatedproperty 
public var onBlocksCreated:Function

Callback function called when the blocks are created, or recreated.

It occurs when the split or text changes.

The default value is null.

onCompleteproperty 
public var onComplete:Function

Callback function called when the last effect was dispatched.


		import flupie.textanim.TextAnim;
		
		var myTextAnim:TextAnim = new TextAnim(myTextField);
		myTextAnim.effects = myEffect;
		myTextAnim.onComplete = function():void {
			trace("text animation completed!");
		}
		myTextAnim.start();
		

The default value is null.

onProgressproperty 
public var onProgress:Function

Callback function called when each effect dispatch.


		import flupie.textanim.TextAnim;
		
		var myTextAnim:TextAnim = new TextAnim(myTextField);
		myTextAnim.effects = myEffect;
		myTextAnim.onProgress = function():void {
			trace("effect was dispatched.");
		}
		myTextAnim.start();
		

The default value is null.

onStartproperty 
public var onStart:Function

Callback function called when the TextAnim starts.

Runs only after delay setted.


		import flupie.textanim.TextAnim;
		
		var myTextAnim:TextAnim = new TextAnim(myTextField);
		myTextAnim.effects = myEffect;
		myTextAnim.delay = 1000;
		myTextAnim.onStart = function():void {
			trace("textAnim starts after 1 second");
		}
		myTextAnim.start();
		

The default value is null.

sourceproperty 
public var source:TextField

The original TextField instance thats TextAnim will use as reference.

Can be any textField, since it has an embed font.

splitproperty 
split:String

To specify how the TextAnim will break the text: in chars, words or lines.

Everytime split changes, the blocks will be recreated automatically, keeping the text and appearance.

myTextAnim.split = TextAnimSplit.WORDS; //this instance will be splitted in words.


Implementation
    public function get split():String
    public function set split(value:String):void

See also

textproperty 
text:String

Changes the text. All the blocks will be recreated.

The first value will be the same of the source's text. If you need use html as text, use htmlText.


Implementation
    public function get text():String
    public function set text(value:String):void

See also

timeproperty 
public var time:Number = 0

Indicates a fixed total time (in milliseconds) of effects dispatches.

A value of 5000 means the last dispatch will occurs 5 seconds after the first dispatch. Interval is ignored if time has a value higher than 0.

The default value is 0.

Constructor Detail
TextAnim()Constructor
public function TextAnim(source:TextField, autoReplace:Boolean = true)

Constructor. Receives a TextField instance and instruction to replace that automatically.

The source TextField must have the font embbeded.

TextAnim will use the source as reference to create and organize TextAnimBlocks to looks identical to the source text. If the source already is in displayList, TextAnim can self add in displayList in the same position/depth with autoReplace setted as true.

By default, TextAnim creates the first set of blocks with the source text, but you can change this text everytime you want, using text or htmlText properties.

Auto-replacement if the source textField is in displayList: var anim:TextAnim = new TextAnim(myTextField);

Without auto-replacement, then you need do add settings manually:

		var anim:TextAnim = new TextAnim(myTextField);
		myTextField.x = 50;
		myTextField.y = 100;
		addChild(myTextField);
		

Parameters
source:TextField — The TextField instance that TextAnim will be based.
 
autoReplace:Boolean (default = true) — Do a replacement removing the source and placing this TextAnim instance in the same scope, with same positions. (works only if the source textfield was in display list).
Method Detail
applyEffect()method
public function applyEffect(block:TextAnimBlock):void

To apply the effects to a single block.

Use when you need play the effects just to one block: myTextAnim.applyEffect(myTextAnimBlock);

Parameters

block:TextAnimBlock — The target block who plays the instance effects.

create()method 
public static function create(source:TextField, config:Object = null):TextAnim

Creates an instance of TextAnim in a fast way.

If you needs a fast text animation, hit:

TextAnim.create(myTextField, {effects:myEffect, split:TextAnimSplit.WORDS}).start();

or:


		var anim:TextAnim = TextAnim.create(myTextField, {effects:myEffect, interval:50, split:TextAnimSplit.WORDS});
		anim.start(500); //delay to start (in milliseconds)
		

Parameters

source:TextField — The TextField instance that TextAnim will be based.
 
config:Object (default = null) — Additional instance settings, like time, blocksVisible, etc.

Returns
TextAnim — TextAnim an instance of TextAnim.
dispose()method 
public function dispose():void

Clear all blocks, internal references, stops the progress and kill the TextAnim instance.

Do it when the instance of TextAnim is not needed anymore. Delete blocks, remove references and clear memory.


		myTextAnim.dispose();
		myTextAnim = null;
		

forEachBlocks()method 
public function forEachBlocks(callback:Function):void

Apply a function to each block of this TextAnim.

Offers access to all blocks of textAnim instance.


		myTextAnim.forEachBlocks = function(block:TextAnimBlock):void {
			block.alpha = .5;
			trace(block.index, block.text); //index number of block (ID)
		};
		

Parameters

callback:Function — The function that will be applied to each block.

setAnchor()method 
public function setAnchor(anchorX:String, anchorY:String):void

Modify the registration x and y of all blocks.

Parameters

anchorX:String — The horizontal registration (TextAnimAnchor.LEFT, TextAnimAnchor.RIGHT and TextAnimAnchor.CENTER).
 
anchorY:String — The vertical registration (TextAnimAnchor.TOP, TextAnimAnchor.BOTTOM and TextAnimAnchor.CENTER).

start()method 
public function start(delay:Number = 0):void

Starts the flow of effects dispatches, with delay specified.

myTextAnim.start(2000); //This instance will start after 2 seconds.

Parameters

delay:Number (default = 0) — The time (in milliseconds) thats TextAnim will wait to execute the first dispatch.

See also

stop()method 
public function stop():void

Stops the flow of effects dispatches.

The effects, onProgress and textAnimEvent.PROGRESS dispatches stops. The onComplete will not be dispatched, except that animation starts again.

See also