GODPAPER | All Packages | All Classes | Index | Frames No Frames |
TextField

Package | starling.text
Class | public class TextField
Inheritance | TextField DisplayObjectContainer DisplayObject EventDispatcher 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:

- Standard TrueType fonts. This renders the text just like a conventional Flash TextField. It is recommended to embed the font, since you cannot be sure which fonts are available on the client system, and since this enhances rendering quality. Simply pass the font name to the corresponding property.
- Bitmap fonts. If you need speed or fancy font effects, use a bitmap font instead. That is a font that has its glyphs rendered to a texture atlas. To use it, first register the font with the method `registerBitmapFont`, and then pass the font name to the corresponding property of the text field.

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

- Windows: Bitmap Font Generator from Angel Code (free). Export the font data as an XML file and the texture as a png with white characters on a transparent background (32 bit).
- Mac OS: Glyph Designer from 71squared or bmGlyph (both commercial). They support Starling natively.

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
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | alpha : 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
|  | 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
|  | bold : Boolean Indicates whether the text is bold. | TextField
|  | 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
|  | color : uint The color of the text. | TextField
|  | filter : 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
|  | hasVisibleArea : 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
|  | name : String The name of the display object (default: null). | DisplayObject
|  | nativeFilters : Array The native Flash BitmapFilters to apply to this TextField. | TextField
|  | numChildren : int [read-only] The number of children of this container. | DisplayObjectContainer
|  | 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
|  | 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
|  | 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
|  | 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
|  | transformationMatrix : Matrix The transformation matrix of the object relative to its parent. | DisplayObject
|  | underline : Boolean Indicates whether the text is underlined. | TextField
|  | useHandCursor : 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
|  | visible : Boolean The visibility of the object. | DisplayObject
|  | width : Number [override] The width of the object in pixels. | 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

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined 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
|  | addChild(child:DisplayObject):DisplayObject Adds a child to the container. | DisplayObjectContainer
|  | addChildAt(child:DisplayObject, index:int):DisplayObject Adds a child to the container at a certain index. | DisplayObjectContainer
|  | addEventListener(type:String, listener:Function):void [override] | DisplayObject
|  | 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
|  | broadcastEvent(event:Event):void Dispatches an event on all children (recursively). | DisplayObjectContainer
|  | broadcastEventWith(type: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
|  | getBitmapFont(name:String):BitmapFont [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
|  | 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
|  | getTransformationMatrix(targetSpace:DisplayObject, resultMatrix:Matrix = null):Matrix Creates a matrix that represents the transformation from the local coordinate system to another. | DisplayObject
|  | globalToLocal(globalPoint:Point, resultPoint:Point = null):Point Transforms a point from global (stage) coordinates to the local coordinate system. | DisplayObject
|  | 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. | DisplayObjectContainer
|  | 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
|  | removeChild(child:DisplayObject, dispose:Boolean = false):DisplayObject 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] | DisplayObject
|  | removeEventListeners(type:String = null):void [override] | DisplayObject
|  | 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
|  | setChildIndex(child:DisplayObject, index:int):void Moves a child to a certain index. | DisplayObjectContainer
|  | sortChildren(compareFunction:Function):void Sorts the children according to a given function (that works just like the sort function of the Vector class). | DisplayObjectContainer
|  | swapChildren(child1:DisplayObject, child2:DisplayObject):void 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 [static] Unregisters the bitmap font and, optionally, disposes it. | TextField

Protected Methods

| Method | Defined By
--- | --- | ---
|  | formatText(textField:TextField, textFormat:TextFormat):void formatText is called immediately before the text is rendered. | TextField

Events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | added | Dispatched when an object is added to a parent. | DisplayObject
|  | addedToStage | Dispatched when an object is connected to the stage (directly or indirectly). | DisplayObject
|  | enterFrame | Dispatched once every frame on every object that is connected to the stage. | DisplayObject
|  | keyDown | Dispatched when a key on the keyboard is pressed. | DisplayObject
|  | keyUp | Dispatched when a key on the keyboard is released. | DisplayObject
|  | removed | Dispatched when an object is removed from its parent. | DisplayObject
|  | removedFromStage | Dispatched when an object is removed from the stage and won't be rendered any longer. | DisplayObject
|  | touch | Dispatched when an object is touched. | DisplayObject

Property Detail

autoScale | property

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

autoSize | property |

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

batchable | property |

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

bold | property |

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

border | property |

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

color | property |

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

fontName | property |

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

fontSize | property |

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

hAlign | property |

`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

starling.utils.HAlign

height | property |

`height:Number`[override]

The height of the object in pixels.

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

italic | property |

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

kerning | property |

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

nativeFilters | property |

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

text | property |

`text:String`

The displayed text.

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

Implementation
`public function get textBounds():Rectangle`

underline | property |

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

vAlign | property |

`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

starling.utils.VAlign

width | property |

`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`)``

Thu Jan 16 2014, 01:11 PM +08:00