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: 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
 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
  italic : Boolean
Indicates whether the text is italicized.
TextField
  kerning : Boolean
Indicates whether kerning is enabled.
TextField
 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
 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
 InheritedtransformationMatrix : Matrix
The 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]
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
Dispatches an event to all objects that have registered listeners for its type.
EventDispatcher
 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
globalToLocal(globalPoint:Point, resultPoint:Point = null):Point
Transforms a point from global (stage) coordinates to the local coordinate system.
DisplayObject
 Inherited
hasEventListener(type:String):Boolean
Returns if there are listeners registered for a certain event type.
EventDispatcher
 Inherited
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.
DisplayObjectContainer
 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]
DisplayObject
 Inherited
removeEventListeners(type:String = null):void
[override]
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
formatText is called immediately before the text 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. For bitmap fonts, use Color.WHITE to use the original, untinted color.

The default value is black.


Implementation
    public function get color():uint
    public function set color(value:uint):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.


Implementation
    public function get height():Number
    public function set height(value:Number):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
nativeFiltersproperty 
nativeFilters:Array

The native Flash BitmapFilters to apply to this TextField. Only available when using standard (TrueType) 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.


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

formatText 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 TextField. textField is the flash.text.TextField object that you can specially format; textFormat is the default TextFormat for textField.

Parameters

textField:TextField
 
textFormat:TextFormat

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
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
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.

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)