| Package | starling.text |
| Class | public class TextField |
| Inheritance | TextField  DisplayObjectContainer DisplayObject EventDispatcher Object |
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:
registerBitmapFont, and then pass
the font name to the corresponding property of the text field.ITextCompositor
interface can be used to render text. If the two standard options are not sufficient
for your needs, such a compositor might do the trick.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.
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.
| Property | Defined By | ||
|---|---|---|---|
 | alpha : 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 | ||
| base : 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 | ||
| blendMode : 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 | ||
| bounds : 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 | ||
| filter : 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 | ||
| is3D : 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 | ||
| mask : DisplayObject The display object that acts as a mask for the current object. | DisplayObject | |
| maskInverted : Boolean Indicates if the masked region of this object is set to be inverted. | DisplayObject | |
| name : String The name of the display object (default: null). | DisplayObject | |
| numChildren : 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 | ||
| parent : DisplayObjectContainer [read-only] The display object container that contains this display object. | DisplayObject | |
| pivotX : Number The x coordinate of the object's origin in its own coordinate space (default: 0). | DisplayObject | |
| pivotY : 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 | ||
| requiresRedraw : Boolean [read-only] Indicates if the object needs to be redrawn in the upcoming frame, i.e. | DisplayObject | |
| root : DisplayObject [read-only] The root object the display object is connected to (i.e. | DisplayObject | |
| rotation : Number The rotation of the object in radians. | DisplayObject | |
| scale : Number Sets both 'scaleX' and 'scaleY' to the same value. | DisplayObject | |
| scaleX : Number The horizontal scale factor. | DisplayObject | |
| scaleY : Number The vertical scale factor. | DisplayObject | |
| skewX : Number The horizontal skew angle in radians. | DisplayObject | |
| skewY : Number The vertical skew angle in radians. | DisplayObject | |
| stage : 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 | ||
| touchable : Boolean Indicates if this object (and its children) will receive touch events. | DisplayObject | |
| touchGroup : Boolean If a container is a 'touchGroup', it will act as a single touchable object. | DisplayObjectContainer | |
| transformationMatrix : Matrix The transformation matrix of the object relative to its parent. | DisplayObject | |
| transformationMatrix3D : Matrix3D [read-only] The 3D transformation matrix of the object relative to its parent. | DisplayObject | |
| useHandCursor : Boolean Indicates if the mouse cursor should transform into a hand while it's over the sprite. | DisplayObject | |
| visible : 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 | ||
| x : Number The x coordinate of the object relative to the local coordinates of the parent. | DisplayObject | |
| y : Number The y coordinate of the object relative to the local coordinates of the parent. | DisplayObject | |
| Property | Defined By | ||
|---|---|---|---|
| options : TextOptions [read-only] The options that describe how the letters of a text should be assembled. | TextField | ||
| Method | Defined By | ||
|---|---|---|---|
Create a new text field with the given properties. | TextField | ||
| Adds a child to the container. | DisplayObjectContainer | |
| Adds a child to the container at a certain index. | DisplayObjectContainer | |
| addEventListener(type:String, listener:Function):void [override] Registers an event listener at a certain object. | DisplayObject | |
| 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 | |
| broadcastEvent(event:Event):void Dispatches an event on all children (recursively). | DisplayObjectContainer | |
| broadcastEventWith(eventType:String, data:Object = null):void Dispatches an event with the given parameters on all children (recursively). | DisplayObjectContainer | |
| contains(child:DisplayObject):Boolean Determines if a certain object is a child of the container (recursively). | DisplayObjectContainer | |
| dispatchEvent(event:Event):void Dispatches an event to all objects that have registered listeners for its type. | EventDispatcher | |
| 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 | ||
| drawToBitmapData(out:BitmapData = null, color:uint = 0x0, alpha:Number = 0.0):BitmapData Draws the object into a BitmapData object. | DisplayObject | |
getBitmapFont(name:String):BitmapFont [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 | ||
| getChildAt(index:int):DisplayObject Returns a child object at a certain index. | DisplayObjectContainer | |
| getChildByName(name:String):DisplayObject Returns a child object with a certain name (non-recursively). | DisplayObjectContainer | |
| getChildIndex(child:DisplayObject):int Returns the index of a child within the container, or "-1" if it is not found. | DisplayObjectContainer | |
getCompositor(fontName:String):ITextCompositor [static] Returns a registered text compositor (or null, if the font has not been registered). | TextField | ||
getTextBounds(targetSpace:DisplayObject, out:Rectangle = null):Rectangle Returns the bounds of the text within the text field in the given coordinate space. | TextField | ||
| getTransformationMatrix(targetSpace:DisplayObject, out:Matrix = null):Matrix Creates a matrix that represents the transformation from the local coordinate system
to another. | DisplayObject | |
| getTransformationMatrix3D(targetSpace:DisplayObject, out:Matrix3D = null):Matrix3D Creates a matrix that represents the transformation from the local coordinate system
to another. | DisplayObject | |
| globalToLocal(globalPoint:Point, out:Point = null):Point Transforms a point from global (stage) coordinates to the local coordinate system. | DisplayObject | |
| globalToLocal3D(globalPoint:Point, out:Vector3D = null):Vector3D Transforms a point from global (stage) coordinates to the 3D local coordinate system. | DisplayObject | |
| 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 | ||
| hitTestMask(localPoint:Point):Boolean Checks if a certain point is inside the display object's mask. | DisplayObject | |
| local3DToGlobal(localPoint:Vector3D, out:Point = null):Point Transforms a 3D point from the local coordinate system to global (stage) coordinates. | DisplayObject | |
| 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 | ||
| Removes a child from the container. | DisplayObjectContainer | |
| removeChildAt(index:int, dispose:Boolean = false):DisplayObject Removes a child at a certain index. | DisplayObjectContainer | |
| removeChildren(beginIndex:int = 0, endIndex:int = -1, dispose:Boolean = false):void Removes a range of children from the container (endIndex included). | DisplayObjectContainer | |
| removeEventListener(type:String, listener:Function):void [override] Removes an event listener from the object. | DisplayObject | |
| removeEventListeners(type:String = null):void [override] Removes all event listeners with a certain type, or all of them if type is null. | DisplayObject | |
| removeFromParent(dispose:Boolean = false):void Removes the object from its parent, if it has one, and optionally disposes it. | DisplayObject | |
[override] Renders the display object with the help of a painter object. | TextField | ||
| setChildIndex(child:DisplayObject, index:int):void Moves a child to a certain index. | DisplayObjectContainer | |
setRequiresRecomposition():void Forces the text to be recomposed before rendering it in the upcoming frame. | TextField | ||
| setRequiresRedraw():void Forces the object to be redrawn in the next frame. | DisplayObject | |
| sortChildren(compareFunction:Function):void Sorts the children according to a given function (that works just like the sort function
of the Vector class). | DisplayObjectContainer | |
| Swaps the indexes of two children. | DisplayObjectContainer | |
| 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 | ||
updateEmbeddedFonts():void [static] Updates the list of embedded fonts. | TextField | ||
| autoScale | property |
Hide Inherited Public Properties
Show Inherited Public PropertiesautoScale:BooleanIndicates whether the font size is automatically reduced if the complete text does not fit into the TextField.
The default value is false.
public function get autoScale():Boolean public function set autoScale(value:Boolean):void| autoSize | property |
autoSize:StringSpecifies 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.
public function get autoSize():String public function set autoSize(value:String):void| batchable | property |
batchable:BooleanIndicates 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.
public function get batchable():Boolean public function set batchable(value:Boolean):void| border | property |
border:BooleanDraws a border around the edges of the text field. Useful for visual debugging.
The default value is false.
public function get border():Boolean public function set border(value:Boolean):void| defaultCompositor | property |
defaultCompositor:ITextCompositorThe 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.
public static function get defaultCompositor():ITextCompositor public static function set defaultCompositor(value:ITextCompositor):void| defaultTextureFormat | property |
defaultTextureFormat:StringThe 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.BGRAfor the highest quality.
The default value is Context3DTextureFormat.BGRA_PACKED.
public static function get defaultTextureFormat():String public static function set defaultTextureFormat(value:String):void| format | property |
format:TextFormatThe 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.
public function get format():TextFormat public function set format(value:TextFormat):void| height | property |
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.
public function get height():Number public function set height(value:Number):void| isHtmlText | property |
isHtmlText:BooleanIndicates 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.
public function get isHtmlText():Boolean public function set isHtmlText(value:Boolean):void| options | property |
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.
protected function get options():TextOptions| padding | property |
padding:NumberThe 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.
public function get padding():Number public function set padding(value:Number):void| pixelSnapping | property |
pixelSnapping:BooleanControls 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.
public function get pixelSnapping():Boolean public function set pixelSnapping(value:Boolean):void| style | property |
style:MeshStyleThe mesh style that is used to render the text. Note that a style instance may only be used on one mesh at a time.
public function get style():MeshStyle public function set style(value:MeshStyle):void| styleSheet | property |
styleSheet:StyleSheetAn 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.
public function get styleSheet():StyleSheet public function set styleSheet(value:StyleSheet):void| text | property |
text:StringThe displayed text.
public function get text():String public function set text(value:String):void| textBounds | property |
textBounds:Rectangle [read-only] Returns the bounds of the text within the text field.
public function get textBounds():Rectangle| width | property |
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.
public function get width():Number public function set width(value:Number):void| wordWrap | property |
wordWrap:BooleanIndicates if the text should be wrapped at word boundaries if it does not fit into the TextField otherwise.
The default value is true.
public function get wordWrap():Boolean public function set wordWrap(value:Boolean):void| 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.
Parameterswidth:int | |
height:int | |
text:String | |
format:TextFormat (default = null) | |
options:TextOptions (default = null) |
| dispose | () | method |
override public function dispose():voidDisposes the underlying texture data.
| getBitmapFont | () | method |
public static function getBitmapFont(name:String):BitmapFontReturns 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 |
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) |
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 |
ITextCompositor |
| getTextBounds | () | method |
public function getTextBounds(targetSpace:DisplayObject, out:Rectangle = null):RectangleReturns the bounds of the text within the text field in the given coordinate space.
Parameters
targetSpace:DisplayObject | |
out:Rectangle (default = null) |
Rectangle |
| hitTest | () | method |
override public function hitTest(localPoint:Point):DisplayObjectReturns 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 |
DisplayObject |
| 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) |
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):voidRenders 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():voidForces 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):voidUnregisters 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):voidUnregisters the specified text compositor and optionally disposes it.
Parameters
fontName:String | |
dispose:Boolean (default = true) |
| updateEmbeddedFonts | () | method |
public static function updateEmbeddedFonts():voidUpdates the list of embedded fonts. Call this method when you loaded a TrueType font at runtime so that Starling can recognize it as such.