Packagestarling.text
Classpublic class TextField
InheritanceTextField Inheritance DisplayObjectContainer Inheritance DisplayObject Inheritance EventDispatcher Inheritance Object

A TextField displays text, either using standard true type fonts or custom bitmap fonts.

You can set all properties you are used to, like the font name and size, a color, the horizontal and vertical alignment, etc. The border property is helpful during development, because it lets you see the bounds of the TextField.

There are two types of fonts that can be displayed:

For bitmap fonts, we recommend one of the following tools:

When using a bitmap font, the 'color' property is used to tint the font texture. This works by multiplying the RGB values of that property with those of the texture's pixel. If your font contains just a single color, export it in plain white and change the 'color' property to any value you like (it defaults to zero, which means black). If your font contains multiple colors, change the 'color' property to Color.WHITE to get the intended result.

Batching of TextFields

Normally, TextFields will require exactly one draw call. For TrueType fonts, you cannot avoid that; bitmap fonts, however, may be batched if you enable the "batchable" property. This makes sense if you have several TextFields with short texts that are rendered one after the other (e.g. subsequent children of the same sprite), or if your bitmap font texture is in your main texture atlas.

The recommendation is to activate "batchable" if it reduces your draw calls (use the StatsDisplay to check this) AND if the TextFields contain no more than about 10-15 characters (per TextField). For longer texts, the batching would take up more CPU time than what is saved by avoiding the draw calls.



Public Properties
 PropertyDefined By
 Inheritedalpha : Number
The opacity of the object.
DisplayObject
  autoScale : Boolean
Indicates whether the font size is scaled down so that the complete text fits into the text field.
TextField
  autoSize : String
Specifies the type of auto-sizing the TextField will do.
TextField
 Inheritedbase : DisplayObject
[read-only] The topmost object in the display tree the object is part of.
DisplayObject
  batchable : Boolean
Indicates if TextField should be batched on rendering.
TextField
 InheritedblendMode : String
The blend mode determines how the object is blended with the objects underneath.
DisplayObject
  bold : Boolean
Indicates whether the text is bold.
TextField
  border : Boolean
Draws a border around the edges of the text field.
TextField
 Inheritedbounds : Rectangle
[read-only] The bounds of the object relative to the local coordinates of the parent.
DisplayObject
  color : uint
The color of the text.
TextField
  defaultTextureFormat : String
[static] The Context3D texture format that is used for rendering of all TrueType texts.
TextField
 Inheritedfilter : FragmentFilter
The filter that is attached to the display object.
DisplayObject
  fontName : String
The name of the font (true type or bitmap font).
TextField
  fontSize : Number
The size of the font.
TextField
  hAlign : String
The horizontal alignment of the text.
TextField
 InheritedhasVisibleArea : Boolean
[read-only] Indicates if an object occupies any visible area.
DisplayObject
  height : Number
[override] The height of the object in pixels.
TextField
 Inheritedis3D : Boolean
[read-only] Indicates if this object or any of its parents is a 'Sprite3D' object.
DisplayObject
  isHtmlText : Boolean
Indicates if the assigned text should be interpreted as HTML code.
TextField
  italic : Boolean
Indicates whether the text is italicized.
TextField
  kerning : Boolean
Indicates whether kerning is enabled.
TextField
  leading : Number
The amount of vertical space (called 'leading') between lines.
TextField
 Inheritedmask : DisplayObject
The display object that acts as a mask for the current object.
DisplayObject
 Inheritedname : String
The name of the display object (default: null).
DisplayObject
  nativeFilters : Array
The native Flash BitmapFilters to apply to this TextField.
TextField
 InheritednumChildren : int
[read-only] The number of children of this container.
DisplayObjectContainer
 Inheritedparent : DisplayObjectContainer
[read-only] The display object container that contains this display object.
DisplayObject
 InheritedpivotX : Number
The x coordinate of the object's origin in its own coordinate space (default: 0).
DisplayObject
 InheritedpivotY : Number
The y coordinate of the object's origin in its own coordinate space (default: 0).
DisplayObject
 Inheritedroot : DisplayObject
[read-only] The root object the display object is connected to (i.e.
DisplayObject
 Inheritedrotation : Number
The rotation of the object in radians.
DisplayObject
 Inheritedscale : Number
Sets both 'scaleX' and 'scaleY' to the same value.
DisplayObject
 InheritedscaleX : Number
The horizontal scale factor.
DisplayObject
 InheritedscaleY : Number
The vertical scale factor.
DisplayObject
 InheritedskewX : Number
The horizontal skew angle in radians.
DisplayObject
 InheritedskewY : Number
The vertical skew angle in radians.
DisplayObject
 Inheritedstage : Stage
[read-only] The stage the display object is connected to, or null if it is not connected to the stage.
DisplayObject
  text : String
The displayed text.
TextField
  textBounds : Rectangle
[read-only] Returns the bounds of the text within the text field.
TextField
 Inheritedtouchable : Boolean
Indicates if this object (and its children) will receive touch events.
DisplayObject
 InheritedtouchGroup : Boolean
If a container is a 'touchGroup', it will act as a single touchable object.
DisplayObjectContainer
 InheritedtransformationMatrix : Matrix
The transformation matrix of the object relative to its parent.
DisplayObject
 InheritedtransformationMatrix3D : Matrix3D
[read-only] The 3D transformation matrix of the object relative to its parent.
DisplayObject
  underline : Boolean
Indicates whether the text is underlined.
TextField
 InheriteduseHandCursor : Boolean
Indicates if the mouse cursor should transform into a hand while it's over the sprite.
DisplayObject
  vAlign : String
The vertical alignment of the text.
TextField
 Inheritedvisible : Boolean
The visibility of the object.
DisplayObject
  width : Number
[override] The width of the object in pixels.
TextField
 Inheritedx : Number
The x coordinate of the object relative to the local coordinates of the parent.
DisplayObject
 Inheritedy : Number
The y coordinate of the object relative to the local coordinates of the parent.
DisplayObject
Public Methods
 MethodDefined By
  
TextField(width:int, height:int, text:String, fontName:String = Verdana, fontSize:Number = 12, color:uint = 0x0, bold:Boolean = false)
Create a new text field with the given properties.
TextField
 Inherited
Adds a child to the container.
DisplayObjectContainer
 Inherited
Adds a child to the container at a certain index.
DisplayObjectContainer
 Inherited
addEventListener(type:String, listener:Function):void
[override] Registers an event listener at a certain object.
DisplayObject
 Inherited
alignPivot(hAlign:String = center, vAlign:String = center):void
Moves the pivot point to a certain position within the local coordinate system of the object.
DisplayObject
 Inherited
broadcastEvent(event:Event):void
Dispatches an event on all children (recursively).
DisplayObjectContainer
 Inherited
broadcastEventWith(type:String, data:Object = null):void
Dispatches an event with the given parameters on all children (recursively).
DisplayObjectContainer
 Inherited
contains(child:DisplayObject):Boolean
Determines if a certain object is a child of the container (recursively).
DisplayObjectContainer
 Inherited
dispatchEvent(event:Event):void
[override]
DisplayObject
 Inherited
dispatchEventWith(type:String, bubbles:Boolean = false, data:Object = null):void
Dispatches an event with the given parameters to all objects that have registered listeners for the given type.
EventDispatcher
  
dispose():void
[override] Disposes the underlying texture data.
TextField
  
[static] Returns a registered bitmap font (or null, if the font has not been registered).
TextField
  
getBounds(targetSpace:DisplayObject, resultRect:Rectangle = null):Rectangle
[override] Returns a rectangle that completely encloses the object as it appears in another coordinate system.
TextField
 Inherited
Returns a child object at a certain index.
DisplayObjectContainer
 Inherited
Returns a child object with a certain name (non-recursively).
DisplayObjectContainer
 Inherited
Returns the index of a child within the container, or "-1" if it is not found.
DisplayObjectContainer
 Inherited
getTransformationMatrix(targetSpace:DisplayObject, resultMatrix:Matrix = null):Matrix
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
 Inherited
getTransformationMatrix3D(targetSpace:DisplayObject, resultMatrix:Matrix3D = null):Matrix3D
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
 Inherited
globalToLocal(globalPoint:Point, resultPoint:Point = null):Point
Transforms a point from global (stage) coordinates to the local coordinate system.
DisplayObject
 Inherited
globalToLocal3D(globalPoint:Point, resultPoint:Vector3D = null):Vector3D
Transforms a point from global (stage) coordinates to the 3D local coordinate system.
DisplayObject
 Inherited
hasEventListener(type:String):Boolean
Returns if there are listeners registered for a certain event type.
EventDispatcher
  
hitTest(localPoint:Point, forTouch:Boolean = false):DisplayObject
[override] Returns the object that is found topmost beneath a point in local coordinates, or nil if the test fails.
TextField
 Inherited
hitTestMask(localPoint:Point):Boolean
Checks if a certain point is inside the display object's mask.
DisplayObject
 Inherited
local3DToGlobal(localPoint:Vector3D, resultPoint:Point = null):Point
Transforms a 3D point from the local coordinate system to global (stage) coordinates.
DisplayObject
 Inherited
localToGlobal(localPoint:Point, resultPoint:Point = null):Point
Transforms a point from the local coordinate system to global (stage) coordinates.
DisplayObject
  
redraw():void
Forces the text field to be constructed right away.
TextField
  
registerBitmapFont(bitmapFont:BitmapFont, name:String = null):String
[static] Makes a bitmap font available at any TextField in the current stage3D context.
TextField
 Inherited
removeChild(child:DisplayObject, dispose:Boolean = false):DisplayObject
Removes a child from the container.
DisplayObjectContainer
 Inherited
removeChildAt(index:int, dispose:Boolean = false):DisplayObject
Removes a child at a certain index.
DisplayObjectContainer
 Inherited
removeChildren(beginIndex:int = 0, endIndex:int = -1, dispose:Boolean = false):void
Removes a range of children from the container (endIndex included).
DisplayObjectContainer
 Inherited
removeEventListener(type:String, listener:Function):void
[override] Removes an event listener from the object.
DisplayObject
 Inherited
removeEventListeners(type:String = null):void
[override] Removes all event listeners with a certain type, or all of them if type is null.
DisplayObject
 Inherited
removeFromParent(dispose:Boolean = false):void
Removes the object from its parent, if it has one, and optionally disposes it.
DisplayObject
  
render(support:RenderSupport, parentAlpha:Number):void
[override] Renders the display object with the help of a support object.
TextField
 Inherited
setChildIndex(child:DisplayObject, index:int):void
Moves a child to a certain index.
DisplayObjectContainer
 Inherited
sortChildren(compareFunction:Function):void
Sorts the children according to a given function (that works just like the sort function of the Vector class).
DisplayObjectContainer
 Inherited
Swaps the indexes of two children.
DisplayObjectContainer
 Inherited
swapChildrenAt(index1:int, index2:int):void
Swaps the indexes of two children.
DisplayObjectContainer
  
unregisterBitmapFont(name:String, dispose:Boolean = true):void
[static] Unregisters the bitmap font and, optionally, disposes it.
TextField
Protected Methods
 MethodDefined By
  
formatText(textField:TextField, textFormat:TextFormat):void
This method is called immediately before the text is rendered.
TextField
  
Forces a redraw of the current contents right before the display object is rendered.
TextField
Events
 Event Summary Defined By
 InheritedDispatched when an object is added to a parent.DisplayObject
 InheritedDispatched when an object is connected to the stage (directly or indirectly).DisplayObject
 InheritedDispatched once every frame on every object that is connected to the stage.DisplayObject
 InheritedDispatched when a key on the keyboard is pressed.DisplayObject
 InheritedDispatched when a key on the keyboard is released.DisplayObject
 InheritedDispatched when an object is removed from its parent.DisplayObject
 InheritedDispatched when an object is removed from the stage and won't be rendered any longer.DisplayObject
 InheritedDispatched when an object is touched.DisplayObject
Property Detail
autoScaleproperty
autoScale:Boolean

Indicates whether the font size is scaled down so that the complete text fits into the text field.

The default value is false.


Implementation
    public function get autoScale():Boolean
    public function set autoScale(value:Boolean):void
autoSizeproperty 
autoSize:String

Specifies the type of auto-sizing the TextField will do. Note that any auto-sizing will make auto-scaling useless. Furthermore, it has implications on alignment: horizontally auto-sized text will always be left-, vertically auto-sized text will always be top-aligned.

The default value is "none".


Implementation
    public function get autoSize():String
    public function set autoSize(value:String):void
batchableproperty 
batchable:Boolean

Indicates if TextField should be batched on rendering. This works only with bitmap fonts, and it makes sense only for TextFields with no more than 10-15 characters. Otherwise, the CPU costs will exceed any gains you get from avoiding the additional draw call.

The default value is false.


Implementation
    public function get batchable():Boolean
    public function set batchable(value:Boolean):void
boldproperty 
bold:Boolean

Indicates whether the text is bold.

The default value is false.


Implementation
    public function get bold():Boolean
    public function set bold(value:Boolean):void
borderproperty 
border:Boolean

Draws a border around the edges of the text field. Useful for visual debugging.

The default value is false.


Implementation
    public function get border():Boolean
    public function set border(value:Boolean):void
colorproperty 
color:uint

The color of the text. Note that bitmap fonts should be exported in plain white so that tinting works correctly. If your bitmap font contains colors, set this property to Color.WHITE to get the desired result.

The default value is black.


Implementation
    public function get color():uint
    public function set color(value:uint):void
defaultTextureFormatproperty 
defaultTextureFormat:String

The Context3D texture format that is used for rendering of all TrueType texts. The default (

Context3DTextureFormat.BGRA_PACKED
) provides a good compromise between quality and memory consumption; use
BGRA
for the highest quality.


Implementation
    public static function get defaultTextureFormat():String
    public static function set defaultTextureFormat(value:String):void
fontNameproperty 
fontName:String

The name of the font (true type or bitmap font).


Implementation
    public function get fontName():String
    public function set fontName(value:String):void
fontSizeproperty 
fontSize:Number

The size of the font. For bitmap fonts, use BitmapFont.NATIVE_SIZE for the original size.


Implementation
    public function get fontSize():Number
    public function set fontSize(value:Number):void
hAlignproperty 
hAlign:String

The horizontal alignment of the text.

The default value is center.


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

See also

heightproperty 
height:Number[override]

The height of the object in pixels. Note that for objects in a 3D space (connected to a Sprite3D), this value might not be accurate until the object is part of the display list.


Implementation
    public function get height():Number
    public function set height(value:Number):void
isHtmlTextproperty 
isHtmlText:Boolean

Indicates if the assigned text should be interpreted as HTML code. For a description of the supported HTML subset, refer to the classic Flash 'TextField' documentation. Clickable hyperlinks and external images are not supported.

BEWARE: this property is ignored when using bitmap fonts!


Implementation
    public function get isHtmlText():Boolean
    public function set isHtmlText(value:Boolean):void
italicproperty 
italic:Boolean

Indicates whether the text is italicized.

The default value is false.


Implementation
    public function get italic():Boolean
    public function set italic(value:Boolean):void
kerningproperty 
kerning:Boolean

Indicates whether kerning is enabled.

The default value is true.


Implementation
    public function get kerning():Boolean
    public function set kerning(value:Boolean):void
leadingproperty 
leading:Number

The amount of vertical space (called 'leading') between lines.

The default value is 0.


Implementation
    public function get leading():Number
    public function set leading(value:Number):void
nativeFiltersproperty 
nativeFilters:Array

The native Flash BitmapFilters to apply to this TextField.

BEWARE: this property is ignored when using bitmap fonts!


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

The displayed text.


Implementation
    public function get text():String
    public function set text(value:String):void
textBoundsproperty 
textBounds:Rectangle  [read-only]

Returns the bounds of the text within the text field.


Implementation
    public function get textBounds():Rectangle
underlineproperty 
underline:Boolean

Indicates whether the text is underlined.

The default value is false.


Implementation
    public function get underline():Boolean
    public function set underline(value:Boolean):void
vAlignproperty 
vAlign:String

The vertical alignment of the text.

The default value is center.


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

See also

widthproperty 
width:Number[override]

The width of the object in pixels. Note that for objects in a 3D space (connected to a Sprite3D), this value might not be accurate until the object is part of the display list.


Implementation
    public function get width():Number
    public function set width(value:Number):void
Constructor Detail
TextField()Constructor
public function TextField(width:int, height:int, text:String, fontName:String = Verdana, fontSize:Number = 12, color:uint = 0x0, bold:Boolean = false)

Create a new text field with the given properties.

Parameters
width:int
 
height:int
 
text:String
 
fontName:String (default = Verdana)
 
fontSize:Number (default = 12)
 
color:uint (default = 0x0)
 
bold:Boolean (default = false)
Method Detail
dispose()method
override public function dispose():void

Disposes the underlying texture data.

formatText()method 
protected function formatText(textField:TextField, textFormat:TextFormat):void

This method is called immediately before the text is rendered. The intent of 'formatText' is to be overridden in a subclass, so that you can provide custom formatting for the TextField. In the overridden method, call 'setFormat' (either over a range of characters or the complete TextField) to modify the format to your needs.

Parameters

textField:TextField — the flash.text.TextField object that you can format.
 
textFormat:TextFormat — the default text format that's currently set on the text field.

getBitmapFont()method 
public static function getBitmapFont(name:String):BitmapFont

Returns a registered bitmap font (or null, if the font has not been registered). The name is not case sensitive.

Parameters

name:String

Returns
BitmapFont
getBounds()method 
override public function getBounds(targetSpace:DisplayObject, resultRect:Rectangle = null):Rectangle

Returns a rectangle that completely encloses the object as it appears in another coordinate system. If you pass a 'resultRectangle', the result will be stored in this rectangle instead of creating a new object.

Parameters

targetSpace:DisplayObject
 
resultRect:Rectangle (default = null)

Returns
Rectangle
hitTest()method 
override public function hitTest(localPoint:Point, forTouch:Boolean = false):DisplayObject

Returns the object that is found topmost beneath a point in local coordinates, or nil if the test fails. If "forTouch" is true, untouchable and invisible objects will cause the test to fail.

Parameters

localPoint:Point
 
forTouch:Boolean (default = false)

Returns
DisplayObject
redraw()method 
public function redraw():void

Forces the text field to be constructed right away. Normally, it will only do so lazily, i.e. before being rendered.

registerBitmapFont()method 
public static function registerBitmapFont(bitmapFont:BitmapFont, name:String = null):String

Makes a bitmap font available at any TextField in the current stage3D context. The font is identified by its name (not case sensitive). Per default, the name property of the bitmap font will be used, but you can pass a custom name, as well.

Parameters

bitmapFont:BitmapFont
 
name:String (default = null)

Returns
String — the name of the font.
render()method 
override public function render(support:RenderSupport, parentAlpha:Number):void

Renders the display object with the help of a support object. Never call this method directly, except from within another render method.

Parameters

support:RenderSupport — Provides utility functions for rendering.
 
parentAlpha:Number — The accumulated alpha value from the object's parent up to the stage.

requireRedraw()method 
protected final function requireRedraw():void

Forces a redraw of the current contents right before the display object is rendered. Useful especially in combination with the "formatText" method.

unregisterBitmapFont()method 
public static function unregisterBitmapFont(name:String, dispose:Boolean = true):void

Unregisters the bitmap font and, optionally, disposes it.

Parameters

name:String
 
dispose:Boolean (default = true)