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

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

Access the format property to modify the appearance of the text, like the font name and size, a color, the horizontal and vertical alignment, etc. The border property is useful during development, because it lets you see the bounds of the TextField.

There are several 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 text fields contain no more than about 15-20 characters. 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 automatically reduced if the complete text does not fit into the TextField.
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
  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
  defaultCompositor : ITextCompositor
[static] The default compositor used to arrange the letters 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
  format : TextFormat
The format describes how the text will be rendered, describing the font name and size, color, alignment, etc.
TextField
  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 text should be interpreted as HTML code.
TextField
 Inheritedmask : DisplayObject
The display object that acts as a mask for the current object.
DisplayObject
 InheritedmaskInverted : Boolean
Indicates if the masked region of this object is set to be inverted.
DisplayObject
 Inheritedname : String
The name of the display object (default: null).
DisplayObject
 InheritednumChildren : int
[read-only] The number of children of this container.
DisplayObjectContainer
  padding : Number
The padding (in points) that's added to the sides of text that's rendered to a Bitmap.
TextField
 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
  pixelSnapping : Boolean
Controls whether or not the instance snaps to the nearest pixel.
TextField
 InheritedrequiresRedraw : Boolean
[read-only] Indicates if the object needs to be redrawn in the upcoming frame, i.e.
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
  style : MeshStyle
The mesh style that is used to render the text.
TextField
  styleSheet : StyleSheet
An optional style sheet to be used for HTML text.
TextField
  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
 InheriteduseHandCursor : Boolean
Indicates if the mouse cursor should transform into a hand while it's over the sprite.
DisplayObject
 Inheritedvisible : Boolean
The visibility of the object.
DisplayObject
  width : Number
[override] The width of the object in pixels.
TextField
  wordWrap : Boolean
Indicates if the text should be wrapped at word boundaries if it does not fit into the TextField otherwise.
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
Protected Properties
 PropertyDefined By
  options : TextOptions
[read-only] The options that describe how the letters of a text should be assembled.
TextField
Public Methods
 MethodDefined By
  
TextField(width:int, height:int, text:String, format:TextFormat = null, options:TextOptions = null)
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(horizontalAlign:String = center, verticalAlign: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(eventType: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
 Inherited
drawToBitmapData(out:BitmapData = null, color:uint = 0x0, alpha:Number = 0.0):BitmapData
Draws the object into a BitmapData object.
DisplayObject
  
[static] Returns a registered bitmap font compositor (or null, if no compositor has been registered with that name, or if it's not a bitmap font).
TextField
  
getBounds(targetSpace:DisplayObject, out: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
  
[static] Returns a registered text compositor (or null, if the font has not been registered).
TextField
 Inherited
getTransformationMatrix(targetSpace:DisplayObject, out:Matrix = null):Matrix
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
 Inherited
getTransformationMatrix3D(targetSpace:DisplayObject, out:Matrix3D = null):Matrix3D
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
 Inherited
globalToLocal(globalPoint:Point, out:Point = null):Point
Transforms a point from global (stage) coordinates to the local coordinate system.
DisplayObject
 Inherited
globalToLocal3D(globalPoint:Point, out:Vector3D = null):Vector3D
Transforms a point from global (stage) coordinates to the 3D local coordinate system.
DisplayObject
 Inherited
hasEventListener(type:String, listener:Function = null):Boolean
If called with one argument, figures out if there are any listeners registered for the given event type.
EventDispatcher
  
hitTest(localPoint:Point):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, out:Point = null):Point
Transforms a 3D point from the local coordinate system to global (stage) coordinates.
DisplayObject
 Inherited
localToGlobal(localPoint:Point, out:Point = null):Point
Transforms a point from the local coordinate system to global (stage) coordinates.
DisplayObject
  
registerBitmapFont(bitmapFont:BitmapFont, name:String = null):String
Deprecated: Please Use registerCompositor()
[static] Makes a bitmap font available at any TextField in the current stage3D context.
TextField
  
registerCompositor(compositor:ITextCompositor, fontName:String):void
[static] Makes a text compositor (like a BitmapFont) available to 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(painter:Painter):void
[override] Renders the display object with the help of a painter object.
TextField
 Inherited
setChildIndex(child:DisplayObject, index:int):void
Moves a child to a certain index.
DisplayObjectContainer
  
Forces the text to be recomposed before rendering it in the upcoming frame.
TextField
 Inherited
Forces the object to be redrawn in the next frame.
DisplayObject
 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
Deprecated: Please Use unregisterCompositor()
[static] Unregisters the bitmap font and, optionally, disposes it.
TextField
  
unregisterCompositor(fontName:String, dispose:Boolean = true):void
[static] Unregisters the specified text compositor and optionally disposes it.
TextField
  
[static] Updates the list of embedded fonts.
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 automatically reduced if the complete text does not fit into the TextField.

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 implicitly deactivate all auto-scaling.

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
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
defaultCompositorproperty 
defaultCompositor:ITextCompositor

The default compositor used to arrange the letters of the text. If a specific compositor was registered for a font, it takes precedence.

The default value is TrueTypeCompositor.


Implementation
    public static function get defaultCompositor():ITextCompositor
    public static function set defaultCompositor(value:ITextCompositor):void
defaultTextureFormatproperty 
defaultTextureFormat:String

The Context3D texture format that is used for rendering of all TrueType texts. The default provides a good compromise between quality and memory consumption; use

Context3DTextureFormat.BGRA
for the highest quality.

The default value is Context3DTextureFormat.BGRA_PACKED.


Implementation
    public static function get defaultTextureFormat():String
    public static function set defaultTextureFormat(value:String):void
formatproperty 
format:TextFormat

The format describes how the text will be rendered, describing the font name and size, color, alignment, etc.

Note that you can edit the font properties directly; there's no need to reassign the format for the changes to show up.

          var textField:TextField = new TextField(100, 30, "Hello Starling");
          textField.format.font = "Arial";
          textField.format.color = Color.RED;

The default value is Verdana, 12 pt, black, centered.


Implementation
    public function get format():TextFormat
    public function set format(value:TextFormat):void
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 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 images are not supported. Only works for TrueType fonts!

The default value is false.


Implementation
    public function get isHtmlText():Boolean
    public function set isHtmlText(value:Boolean):void
optionsproperty 
options:TextOptions  [read-only]

The options that describe how the letters of a text should be assembled. This class basically collects all the TextField's properties that are needed during text composition. Since an instance of 'TextOptions' is passed to the constructor, you can pass custom options to the compositor.


Implementation
    protected function get options():TextOptions
paddingproperty 
padding:Number

The padding (in points) that's added to the sides of text that's rendered to a Bitmap. If your text is truncated on the sides (which may happen if the font returns incorrect bounds), padding can make up for that. Value must be positive.

The default value is 0.0.


Implementation
    public function get padding():Number
    public function set padding(value:Number):void
pixelSnappingproperty 
pixelSnapping:Boolean

Controls whether or not the instance snaps to the nearest pixel. This can prevent the object from looking blurry when it's not exactly aligned with the pixels of the screen.

The default value is true.


Implementation
    public function get pixelSnapping():Boolean
    public function set pixelSnapping(value:Boolean):void
styleproperty 
style:MeshStyle

The mesh style that is used to render the text. Note that a style instance may only be used on one mesh at a time.


Implementation
    public function get style():MeshStyle
    public function set style(value:MeshStyle):void
styleSheetproperty 
styleSheet:StyleSheet

An optional style sheet to be used for HTML text. For more information on style sheets, please refer to the StyleSheet class in the ActionScript 3 API reference.

The default value is null.


Implementation
    public function get styleSheet():StyleSheet
    public function set styleSheet(value:StyleSheet):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
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
wordWrapproperty 
wordWrap:Boolean

Indicates if the text should be wrapped at word boundaries if it does not fit into the TextField otherwise.

The default value is true.


Implementation
    public function get wordWrap():Boolean
    public function set wordWrap(value:Boolean):void
Constructor Detail
TextField()Constructor
public function TextField(width:int, height:int, text:String, format:TextFormat = null, options:TextOptions = null)

Create a new text field with the given properties.

Parameters
width:int
 
height:int
 
text:String
 
format:TextFormat (default = null)
 
options:TextOptions (default = null)
Method Detail
dispose()method
override public function dispose():void

Disposes the underlying texture data.

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

Returns a registered bitmap font compositor (or null, if no compositor has been registered with that name, or if it's not a bitmap font). The name is not case sensitive.

Parameters

name:String

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

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

Parameters

targetSpace:DisplayObject
 
out:Rectangle (default = null)

Returns
Rectangle
getCompositor()method 
public static function getCompositor(fontName:String):ITextCompositor

Returns a registered text compositor (or null, if the font has not been registered). The fontName is not case sensitive.

Parameters

fontName:String

Returns
ITextCompositor
hitTest()method 
override public function hitTest(localPoint:Point):DisplayObject

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

Parameters

localPoint:Point

Returns
DisplayObject
registerBitmapFont()method 
public static function registerBitmapFont(bitmapFont:BitmapFont, name:String = null):String
Deprecated: Please Use registerCompositor()

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.
registerCompositor()method 
public static function registerCompositor(compositor:ITextCompositor, fontName:String):void

Makes a text compositor (like a BitmapFont) available to any TextField in the current stage3D context. The font is identified by its name (not case sensitive).

Parameters

compositor:ITextCompositor
 
fontName:String

render()method 
override public function render(painter:Painter):void

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

Parameters

painter:Painter — Captures the current render state and provides utility functions for rendering.

setRequiresRecomposition()method 
public function setRequiresRecomposition():void

Forces the text to be recomposed before rendering it in the upcoming frame. Any changes of the TextField itself will automatically trigger recomposition; changes in its parents or the viewport, however, need to be processed manually. For example, you might want to force recomposition to fix blurring caused by a scale factor change.

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

Unregisters the bitmap font and, optionally, disposes it.

Parameters

name:String
 
dispose:Boolean (default = true)

unregisterCompositor()method 
public static function unregisterCompositor(fontName:String, dispose:Boolean = true):void

Unregisters the specified text compositor and optionally disposes it.

Parameters

fontName:String
 
dispose:Boolean (default = true)

updateEmbeddedFonts()method 
public static function updateEmbeddedFonts():void

Updates the list of embedded fonts. Call this method when you loaded a TrueType font at runtime so that Starling can recognize it as such.