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

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

FlexSplitTextField makes it easy to break apart the TextField in a UIComponent like a Label, Text, or TextArea so that each character, word, or line is in its own TextField, making complex animation simple. When you create a FlexSplitTextField, it loops through the source's children looking for a TextField and when it finds one, it replaces it with the SplitTextField (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 FlexSplitTextField 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 FlexSplitTextField from its center instead of its upper left corner. Use an onComplete in your tween to call the FlexSplitTextField's `deactivate()` or `destroy()` method which will swap the original TextField back into place.

Example
Example AS3 code:

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

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

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

    //split myLabel2 by words
    var stf2:FlexSplitTextField = new FlexSplitTextField(myLabel2, FlexSplitTextField.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 myText by lines
    var stf3:FlexSplitTextField = new FlexSplitTextField(myText, FlexSplitTextField.TYPE_LINES);

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

NOTES / LIMITATIONS

- Does not work perfectly with non-standard antialiasing (like "anti-alias for readability")
- Does not work with htmlText
- Does not recognize custom kerning.
- 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.
- Due to rendering delays in the Flex framework, some componenets (like Text) will use the default width of 100 for the TextField initially until the component fully renders which happens even after the creationComplete event! Therefore, if you try to split apart the component's TextField too quickly, the result will look odd (100 pixels wide).

FlexSplitTextField 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 2011, 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.

Public Properties

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

Public Methods

| Method | Defined by
--- | --- | ---
|  | FlexSplitTextField(source:UIComponent = null, splitType:String = "characters", regOffsetX:Number = 0, regOffsetY:Number = 0) Constructor. | FlexSplitTextField
|  | activate():void When a FlexSplitTextField is activated, it takes the place of the source's original TextField in the display list. | FlexSplitTextField
|  | deactivate():void When a FlexSplitTextField is activated, it swaps the source's original TextField back into the display list. | FlexSplitTextField
|  | destroy():void Deactivates the FlexSplitTextField (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. | FlexSplitTextField
|  | 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. | FlexSplitTextField

Public Constants

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

Property detail

activated | property

`activated:Boolean` [read-write]

When a FlexSplitTextField is activated, it replaces the source's original TextField in the display list. When it is deactivated, it swaps the source's original 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 FlexSplitTextField'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 FlexSplitTextField's internal coordinate system), use regOffsetY.

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

source | property |

`source:UIComponent` [read-write]

The source UIComponent whose TextField gets split apart.

Implementation
`public function get source():UIComponent`
`public function set source(value:UIComponent):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 UITextFields resulting from the split (one for each character, word, or line based on the splitType)

Constructor detail

FlexSplitTextField | () | constructor

`public function FlexSplitTextField(source:UIComponent = null, splitType:String = "characters", regOffsetX:Number = 0, regOffsetY:Number = 0)`

Constructor.

Parameters

| `source:UIComponent` (default = `null`)`` — The source UIComponent whose child TextField should be split apart. Remember, its TextField will be replaced in the display list with the FlexSplitTextField (which is essentially a UIComponent 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 FlexSplitTextField'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 FlexSplitTextField's internal coordinate system), use regOffsetY.

Method detail

activate | () | method

`public function activate():void`

When a FlexSplitTextField is activated, it takes the place of the source's original TextField in the display list.

deactivate | () | method |

`public function deactivate():void`

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

destroy | () | method |

`public function destroy():void`

Deactivates the FlexSplitTextField (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 FlexSplitTextField 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 FlexSplitTextField (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