com.greensock.text.SplitTextField

Package	com.greensock.text
Class	public class SplitTextField
Inheritance	SplitTextField flash.display.Sprite

SplitTextField makes it easy to break apart a TextField so that each character, word, or line is in its own TextField, making complex animation simple. When you create a SplitTextField, it seamlessly replaces the source TextField with itself (a Sprite) containing these multiple TextFields, all conveniently stored in a textFields array that you can, for example, feed to a TweenMax.allFrom() or loop through to create unique tweens for each character, word or line. The SplitTextField keeps the same scale/rotation/position as the source TextField, and you can optionally offset the registration point by a certain number of pixels on its local x- or y-axis, which can be useful if, for example, you want to be able to scale the whole SplitTextField from its center instead of its upper left corner. Use an onComplete in your tween to call the SplitTextField's deactivate() or destroy() method which will swap the original TextField back into place.

Example
Example AS3 code:

import com.greensock.text.SplitTextField;
import com.greensock.TweenMax;
import com.greensock.easing.Elastic;
import com.greensock.plugins.*;
import flash.geom.Point;

//split myTextField1 by characters (the default type of split)
var stf1:SplitTextField = new SplitTextField(myTextField1);

//tween each character down from 100 pixels above while fading in, and offset the start times by 0.05 seconds
TweenMax.allFrom(stf1.textFields, 1, {y:"-100", autoAlpha:0, ease:Elastic.easeOut}, 0.05);

//split myTextField2 by words
var stf2:SplitTextField = new SplitTextField(myTextField2, SplitTextField.TYPE_WORDS);

//explode the words outward using the physics2D feature of TweenLite/Max
TweenPlugin.activate([Physics2DPlugin]);
var i:int = stf2.textFields.length;
var explodeOrigin:Point = new Point(stf2.width * 0.4, stf2.height + 100);
while (i--) {
 var angle:Number = Math.atan2(stf2.textFields[i].y - explodeOrigin.y, stf2.textFields[i].x - explodeOrigin.x) * 180 / Math.PI;
 TweenMax.to(stf2.textFields[i], 2, {physics2D:{angle:angle, velocity:Math.random() * 200 + 150, gravity:400}, scaleX:Math.random() * 4 - 2, scaleY:Math.random() * 4 - 2, rotation:Math.random() * 100 - 50, autoAlpha:0, delay:1 + Math.random()});
}

//split myTextField3 by lines
var stf3:SplitTextField = new SplitTextField(myTextField3, SplitTextField.TYPE_LINES);

//slide each line in from the right, fading it in over 1 second and staggering the start times by 0.5 seconds. Then swap the original TextField back in.
TweenMax.allFrom(stf3.textFields, 1, {x:"200", autoAlpha:0, onComplete:stf3.deactivate}, 0.5);

NOTES / LIMITATIONS

Does not recognize "Auto kern" feature in Flash.
Positioning may be incorrect when non-standard anti-aliasing is used (like "anti-alias for readability"). Even with standard anti-aliasing, depending on the specific font you use positioning may be slightly off.
Does not work with htmlText
To improve performance, mouseChildren is set to false by default (you're welcome to set it to true if you need the TextFields to receive MouseEvents)
To avoid some bugs in the way Flash renders TextFields, when creating TextField instances dynamically make sure you set the various properties of the TextField BEFORE adding the actual text. For example, set the width, height, embedFonts, autoSize, multiline, and other properties before setting the text property.
Not intended for use in Flex (use FlexSplitTextField instead)

SplitTextField is a Club GreenSock membership benefit. You must have a valid membership to use this class without violating the terms of use. Visit http://blog.greensock.com/club/ to sign up or get more details.

Copyright 2010, GreenSock. All rights reserved. This work is subject to the terms in http://www.greensock.com/terms_of_use.html or for corporate Club GreenSock members, the software agreement that was issued with the corporate membership.

	Property	Defined by
		activated : Boolean When a SplitTextField is activated, it replaces the source TextField in the display list.	SplitTextField
		regOffsetX : Number To offset the registration point by a certain number of pixels along its x-axis (according to the SplitTextField's internal coordinate system), use regOffsetX.	SplitTextField
		regOffsetY : Number To offset the registration point by a certain number of pixels along its y-axis (according to the SplitTextField's internal coordinate system), use regOffsetY.	SplitTextField
		source : TextField The source TextField that gets split apart.	SplitTextField
		splitType : String Determines the way in which the source TextField is split apart - either by characters, words, or lines.	SplitTextField
		textFields : Array Array of TextFields resulting from the split (one for each character, word, or line based on the splitType)	SplitTextField

	Method	Defined by
		SplitTextField(source:TextField = null, splitType:String = "characters", regOffsetX:Number = 0, regOffsetY:Number = 0) Constructor.	SplitTextField
		activate():void When a SplitTextField is activated, it takes the place of the source TextField in the display list.	SplitTextField
		deactivate():void When a SplitTextField is deactivated, it swaps the source TextField back into the display list.	SplitTextField
		destroy():void Deactivates the SplitTextField (swapping the original TextField back into place) and deletes all child TextFields that resulted from the split operation, and nulls references to the source so that it's eligible for garbage collection.	SplitTextField
		split(source:TextField, spitType:String = "characters", container:DisplayObjectContainer = null, offset:Point = null):Array [static] This static method can be used to split apart any TextField and place the resulting TextFields into any DisplayObjectContainer.	SplitTextField

	Constant	Defined by
		TYPE_CHARACTERS : String = "characters" [static] Split type: characters	SplitTextField
		TYPE_LINES : String = "lines" [static] Split type: lines	SplitTextField
		TYPE_WORDS : String = "words" [static] Split type: words	SplitTextField

Property detail

activated

property

activated:Boolean [read-write]

When a SplitTextField is activated, it replaces the source TextField in the display list. When it is deactivated, it swaps the source TextField back into place

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

regOffsetX

property

regOffsetX:Number [read-write]

To offset the registration point by a certain number of pixels along its x-axis (according to the SplitTextField's internal coordinate system), use regOffsetX.

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

regOffsetY

property

regOffsetY:Number [read-write]

To offset the registration point by a certain number of pixels along its y-axis (according to the SplitTextField's internal coordinate system), use regOffsetY.

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

source

property

source:TextField [read-write]

The source TextField that gets split apart.

Implementation
public function get source():TextField
public function set source(value:TextField):void

splitType

property

splitType:String [read-write]

Determines the way in which the source TextField is split apart - either by characters, words, or lines. Use the TYPE_CHARACTERS, TYPE_WORDS, and TYPE_LINES constants.

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

textFields

property

public var textFields:Array

Array of TextFields resulting from the split (one for each character, word, or line based on the splitType)

Constructor detail

SplitTextField

()

constructor

public function SplitTextField(source:TextField = null, splitType:String = "characters", regOffsetX:Number = 0, regOffsetY:Number = 0)

Constructor.

Parameters

	`source:TextField` (default = `null`) — The source TextField that should be split apart. Remember, this TextField will be replaced in the display list with the SplitTextField (which is essentially a Sprite containing the various resulting TextFields).

	`splitType:String` (default = "`characters`") — Determines the way in which the TextField is split apart - either by characters, words, or lines. Use the `TYPE_CHARACTERS, TYPE_WORDS,` and `TYPE_LINES` constants.

	`regOffsetX:Number` (default = `0`) — To offset the registration point by a certain number of pixels along its x-axis (according to the SplitTextField's internal coordinate system), use regOffsetX.

	`regOffsetY:Number` (default = `0`) — To offset the registration point by a certain number of pixels along its y-axis (according to the SplitTextField's internal coordinate system), use regOffsetY.

Method detail

activate

()

method

public function activate():void

When a SplitTextField is activated, it takes the place of the source TextField in the display list.

deactivate

()

method

public function deactivate():void

When a SplitTextField is deactivated, it swaps the source TextField back into the display list. This makes it simple to animate the SplitTextField's contents with TweenLite/Max and then use an onComplete to call deactivate() which will swap the original (source) TextField back into place.

destroy

()

method

public function destroy():void

Deactivates the SplitTextField (swapping the original TextField back into place) and deletes all child TextFields that resulted from the split operation, and nulls references to the source so that it's eligible for garbage collection.

split

()

method

public static function split(source:TextField, spitType:String = "characters", container:DisplayObjectContainer = null, offset:Point = null):Array

This static method can be used to split apart any TextField and place the resulting TextFields into any DisplayObjectContainer. It provides the core functionality of the SplitTextField class, but can be used apart from any instance thereof as well.

Parameters

	`source:TextField` — The source TextField that should be split apart. Remember, this TextField will be replaced in the display list with the SplitTextField (which is essentially a Sprite containing the various resulting TextFields).

	`spitType:String` (default = "`characters`") — Determines the way in which the TextField is split apart - either by characters, words, or lines. Use the `TYPE_CHARACTERS, TYPE_WORDS,` and `TYPE_LINES` constants.

	`container:DisplayObjectContainer` (default = `null`) — The DisplayObjectContainer into which the new TextFields should be placed.

	`offset:Point` (default = `null`) — Determines the offset x/y of the new TextFields. By default, the TextFields will be positioned in the container as though the container's registration point was aligned perfectly with the source TextField's. The source TextField's scale, rotation, and x/y coordinates will have no effect whatsoever.

Returns

Array — Array of TextFields resulting from the split.

Constant detail

TYPE_CHARACTERS

constant

public static const TYPE_CHARACTERS:String = "characters"

Split type: characters

TYPE_LINES

constant

public static const TYPE_LINES:String = "lines"

Split type: lines

TYPE_WORDS

constant

public static const TYPE_WORDS:String = "words"

Split type: words

API Documentation	All Packages \| All Classes \| Index \| Frames No Frames
Class SplitTextField	Properties \| Methods \| Constants