Options
All
  • Public
  • Public/Protected
  • All
Menu

Class TextField

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:

  • 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.
  • Custom text compositors. Any class implementing the 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:

  • 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.
  • Cross-Platform: Littera or ShoeBox are great tools, as well. Both are free to use and were built with Adobe AIR.

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.

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Properties

alpha

alpha: number

The opacity of the object. 0 = transparent, 1 = opaque. @default 1

autoScale

autoScale: boolean

Indicates whether the font size is automatically reduced if the complete text does not fit into the TextField. @default false

autoSize

autoSize: string

Specifies the type of auto-sizing the TextField will do. Note that any auto-sizing will implicitly deactivate all auto-scaling. @default none

base

The topmost object in the display tree the object is part of.

batchable

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.

@default false

blendMode

blendMode: string

The blend mode determines how the object is blended with the objects underneath.

default

auto

see

starling.display.BlendMode

border

border: boolean

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

bounds

bounds: Rectangle

The bounds of the object relative to the local coordinates of the parent.

filter

The filter that is attached to the display object. The starling.filters package contains several classes that define specific filters you can use. To combine several filters, assign an instance of the FilterChain class; to remove all filters, assign null.

Beware that a filter instance may only be used on one object at a time! Furthermore, when you remove or replace a filter, it is NOT disposed automatically (since you might want to reuse it on a different object).

@default null @see starling.filters.FragmentFilter @see starling.filters.FilterChain

format

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.

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

@default Verdana, 12 pt, black, centered

height

height: number

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.

is3D

is3D: boolean

Indicates if this object or any of its parents is a 'Sprite3D' object.

Protected isHorizontalAutoSize

isHorizontalAutoSize: boolean

isHtmlText

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! @default false

Protected isVerticalAutoSize

isVerticalAutoSize: boolean

mask

The display object that acts as a mask for the current object. Assign null to remove it.

A pixel of the masked display object will only be drawn if it is within one of the mask's polygons. Texture pixels and alpha values of the mask are not taken into account. The mask object itself is never visible.

If the mask is part of the display list, masking will occur at exactly the location it occupies on the stage. If it is not, the mask will be placed in the local coordinate system of the target object (as if it was one of its children).

For rectangular masks, you can use simple quads; for other forms (like circles or arbitrary shapes) it is recommended to use a 'Canvas' instance.

Note: a mask will typically cause at least two additional draw calls: one to draw the mask to the stencil buffer and one to erase it. However, if the mask object is an instance of starling.display.Quad and is aligned parallel to the stage axes, rendering will be optimized: instead of using the stencil buffer, the object will be clipped using the scissor rectangle. That's faster and reduces the number of draw calls, so make use of this when possible.

Note: AIR apps require the depthAndStencil node in the application descriptor XMLs to be enabled! Otherwise, stencil masking won't work.

@see Canvas @default null

maskInverted

maskInverted: boolean

Indicates if the masked region of this object is set to be inverted.

name

name: string

The name of the display object (default: null). Used by 'getChildByName()' of display object containers.

numChildren

numChildren: number

The number of children of this container.

Protected options

options: TextOptions

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.

parent

The display object container that contains this display object.

pivotX

pivotX: number

The x coordinate of the object's origin in its own coordinate space (default: 0).

pivotY

pivotY: number

The y coordinate of the object's origin in its own coordinate space (default: 0).

pixelSnapping

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. @default true

requiresRedraw

requiresRedraw: boolean

Indicates if the object needs to be redrawn in the upcoming frame, i.e. if it has changed its location relative to the stage or some other aspect of its appearance since it was last rendered.

root

The root object the display object is connected to (i.e. an instance of the class that was passed to the Starling constructor), or null if the object is not connected to the stage.

rotation

rotation: number

The rotation of the object in radians. (In Starling, all angles are measured in radians.)

scale

scale: number

Sets both 'scaleX' and 'scaleY' to the same value. The getter simply returns the value of 'scaleX' (even if the scaling values are different). @default 1

scaleX

scaleX: number

The horizontal scale factor. '1' means no scale, negative values flip the object.

default

1

scaleY

scaleY: number

The vertical scale factor. '1' means no scale, negative values flip the object.

default

1

skewX

skewX: number

The horizontal skew angle in radians.

skewY

skewY: number

The vertical skew angle in radians.

stage

stage: Stage

The stage the display object is connected to, or null if it is not connected to the stage.

style

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.

text

text: string

The displayed text.

textBounds

textBounds: Rectangle

Returns the bounds of the text within the text field.

touchGroup

touchGroup: boolean

If a container is a 'touchGroup', it will act as a single touchable object. Touch events will have the container as target, not the touched child. (Similar to 'mouseChildren' in the classic display list, but with inverted logic.)

default

false

touchable

touchable: boolean

Indicates if this object (and its children) will receive touch events.

transformationMatrix

transformationMatrix: Matrix

The transformation matrix of the object relative to its parent.

If you assign a custom transformation matrix, Starling will try to figure out suitable values for x, y, scaleX, scaleY, and rotation. However, if the matrix was created in a different way, this might not be possible. In that case, Starling will apply the matrix, but not update the corresponding properties.

CAUTION: not a copy, but the actual object!

transformationMatrix3D

transformationMatrix3D: Matrix3D

The 3D transformation matrix of the object relative to its parent.

For 2D objects, this property returns just a 3D version of the 2D transformation matrix. Only the 'Sprite3D' class supports real 3D transformations.

CAUTION: not a copy, but the actual object!

useHandCursor

useHandCursor: boolean

Indicates if the mouse cursor should transform into a hand while it's over the sprite.

default

false

visible

visible: boolean

The visibility of the object. An invisible object will be untouchable.

width

width: number

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.

wordWrap

wordWrap: boolean

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

x

x: number

The x coordinate of the object relative to the local coordinates of the parent.

y

y: number

The y coordinate of the object relative to the local coordinates of the parent.

Static defaultCompositor

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.

@default TrueTypeCompositor

Static defaultTextureFormat

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.

@default Context3DTextureFormat.BGRA_PACKED

Methods

addChild

addChildAt

addEventListener

  • addEventListener(type: string, listener: Function): void

alignPivot

  • alignPivot(horizontalAlign?: string, verticalAlign?: string): void

broadcastEvent

  • broadcastEvent(event: Event): void

broadcastEventWith

  • broadcastEventWith(eventType: string, data?: any): void

contains

dispatchEvent

  • dispatchEvent(event: Event): void
  • Dispatches an event to all objects that have registered listeners for its type. If an event with enabled 'bubble' property is dispatched to a display object, it will travel up along the line of parents, until it either hits the root object or someone stops its propagation manually.

    Parameters

    Returns void

dispatchEventWith

  • dispatchEventWith(type: string, bubbles?: boolean, data?: any): void

dispose

  • dispose(): void

drawToBitmapData

  • drawToBitmapData(out?: BitmapData, color?: number, alpha?: number): BitmapData
  • Draws the object into a BitmapData object.

    This is achieved by drawing the object into the back buffer and then copying the pixels of the back buffer into a texture. This also means that the returned bitmap data cannot be bigger than the current viewPort.

    @param out If you pass null, the object will be created for you. If you pass a BitmapData object, it should have the size of the object bounds, multiplied by the current contentScaleFactor. @param color The RGB color value with which the bitmap will be initialized. @param alpha The alpha value with which the bitmap will be initialized.

    Parameters

    • Optional out: BitmapData
    • Optional color: number
    • Optional alpha: number

    Returns BitmapData

getBounds

  • getBounds(targetSpace: DisplayObject, out?: Rectangle): Rectangle

getChildAt

getChildByName

getChildIndex

getTextBounds

  • getTextBounds(targetSpace: DisplayObject, out?: Rectangle): Rectangle

getTransformationMatrix

  • getTransformationMatrix(targetSpace: DisplayObject, out?: Matrix): Matrix

getTransformationMatrix3D

  • getTransformationMatrix3D(targetSpace: DisplayObject, out?: Matrix3D): Matrix3D

Protected get_alpha

  • get_alpha(): number

Protected get_autoScale

  • get_autoScale(): boolean

Protected get_autoSize

  • get_autoSize(): string

Protected get_base

Protected get_batchable

  • get_batchable(): boolean

Protected get_blendMode

  • get_blendMode(): string

get_border

  • get_border(): boolean

Protected get_bounds

  • get_bounds(): Rectangle

Protected get_filter

Protected get_format

Protected get_height

  • get_height(): number

Protected get_is3D

  • get_is3D(): boolean

Protected get_isHorizontalAutoSize

  • get_isHorizontalAutoSize(): boolean

Protected get_isHtmlText

  • get_isHtmlText(): boolean

Protected get_isVerticalAutoSize

  • get_isVerticalAutoSize(): boolean

Protected get_mask

Protected get_maskInverted

  • get_maskInverted(): boolean

Protected get_name

  • get_name(): string

Protected get_numChildren

  • get_numChildren(): number

Protected get_options

Protected get_parent

Protected get_pivotX

  • get_pivotX(): number

Protected get_pivotY

  • get_pivotY(): number

Protected get_pixelSnapping

  • get_pixelSnapping(): boolean

Protected get_requiresRedraw

  • get_requiresRedraw(): boolean

Protected get_root

Protected get_rotation

  • get_rotation(): number

Protected get_scale

  • get_scale(): number

Protected get_scaleX

  • get_scaleX(): number

Protected get_scaleY

  • get_scaleY(): number

Protected get_skewX

  • get_skewX(): number

Protected get_skewY

  • get_skewY(): number

Protected get_stage

Protected get_style

Protected get_text

  • get_text(): string

Protected get_textBounds

  • get_textBounds(): Rectangle

Protected get_touchGroup

  • get_touchGroup(): boolean

Protected get_touchable

  • get_touchable(): boolean

Protected get_transformationMatrix

  • get_transformationMatrix(): Matrix

Protected get_transformationMatrix3D

  • get_transformationMatrix3D(): Matrix3D

Protected get_useHandCursor

  • get_useHandCursor(): boolean

Protected get_visible

  • get_visible(): boolean

Protected get_width

  • get_width(): number

Protected get_wordWrap

  • get_wordWrap(): boolean

Protected get_x

  • get_x(): number

Protected get_y

  • get_y(): number

globalToLocal

  • globalToLocal(globalPoint: Point, out?: Point): Point
  • Transforms a point from global (stage) coordinates to the local coordinate system. If you pass an out-point, the result will be stored in this point instead of creating a new object.

    Parameters

    • globalPoint: Point
    • Optional out: Point

    Returns Point

globalToLocal3D

  • globalToLocal3D(globalPoint: Point, out?: Vector3D): Vector3D
  • Transforms a point from global (stage) coordinates to the 3D local coordinate system. If you pass an out-vector, the result will be stored in this point instead of creating a new object.

    Parameters

    • globalPoint: Point
    • Optional out: Vector3D

    Returns Vector3D

hasEventListener

  • hasEventListener(type: string, listener?: any): boolean

hitTest

hitTestMask

  • hitTestMask(localPoint: Point): boolean

local3DToGlobal

  • local3DToGlobal(localPoint: Vector3D, out?: Point): Point
  • Transforms a 3D point from the local coordinate system to global (stage) coordinates. This is achieved by projecting the 3D point onto the (2D) view plane.

    If you pass an out-point, the result will be stored in this point instead of creating a new object.

    Parameters

    • localPoint: Vector3D
    • Optional out: Point

    Returns Point

localToGlobal

  • localToGlobal(localPoint: Point, out?: Point): Point
  • Transforms a point from the local coordinate system to global (stage) coordinates. If you pass an out-point, the result will be stored in this point instead of creating a new object.

    Parameters

    • localPoint: Point
    • Optional out: Point

    Returns Point

removeChild

removeChildAt

removeChildren

  • removeChildren(beginIndex?: number, endIndex?: number, dispose?: boolean): void

removeEventListener

  • removeEventListener(type: string, listener: Function): void

removeEventListeners

  • removeEventListeners(type?: string): void

removeFromParent

  • removeFromParent(dispose?: boolean): void

render

setChildIndex

setRequiresRecomposition

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

    Returns void

setRequiresRedraw

  • setRequiresRedraw(): void
  • Forces the object to be redrawn in the next frame. This will prevent the object to be drawn from the render cache.

    This method is called every time the object changes in any way. When creating custom mesh styles or any other custom rendering code, call this method if the object needs to be redrawn.

    If the object needs to be redrawn just because it does not support the render cache, call painter.excludeFromCache() in the object's render method instead. That way, Starling's skipUnchangedFrames policy won't be disrupted.

    Returns void

Protected set_alpha

  • set_alpha(value: number): number

Protected set_autoScale

  • set_autoScale(value: boolean): boolean

Protected set_autoSize

  • set_autoSize(value: string): string

Protected set_batchable

  • set_batchable(value: boolean): boolean

Protected set_blendMode

  • set_blendMode(value: string): string

set_border

  • set_border(value: boolean): boolean

Protected set_filter

Protected set_format

Protected set_height

  • set_height(value: number): number

Protected set_isHtmlText

  • set_isHtmlText(value: boolean): boolean

Protected set_mask

Protected set_maskInverted

  • set_maskInverted(value: boolean): boolean

Protected set_name

  • set_name(value: string): string

Protected set_pivotX

  • set_pivotX(value: number): number

Protected set_pivotY

  • set_pivotY(value: number): number

Protected set_pixelSnapping

  • set_pixelSnapping(value: boolean): boolean

Protected set_rotation

  • set_rotation(value: number): number

Protected set_scale

  • set_scale(value: number): number

Protected set_scaleX

  • set_scaleX(value: number): number

Protected set_scaleY

  • set_scaleY(value: number): number

Protected set_skewX

  • set_skewX(value: number): number

Protected set_skewY

  • set_skewY(value: number): number

Protected set_style

Protected set_text

  • set_text(value: string): string

Protected set_touchGroup

  • set_touchGroup(value: boolean): boolean

Protected set_touchable

  • set_touchable(value: boolean): boolean

Protected set_transformationMatrix

  • set_transformationMatrix(matrix: Matrix): Matrix

Protected set_useHandCursor

  • set_useHandCursor(value: boolean): boolean

Protected set_visible

  • set_visible(value: boolean): boolean

Protected set_width

  • set_width(value: number): number

Protected set_wordWrap

  • set_wordWrap(value: boolean): boolean

Protected set_x

  • set_x(value: number): number

Protected set_y

  • set_y(value: number): number

sortChildren

  • sortChildren(compareFunction: function): void

swapChildren

swapChildrenAt

  • swapChildrenAt(index1: number, index2: number): void

Static getBitmapFont

  • 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

Static getCompositor

Static Protected get_defaultCompositor

Static Protected get_defaultTextureFormat

  • get_defaultTextureFormat(): string

Static registerBitmapFont

  • registerBitmapFont(bitmapFont: BitmapFont, name?: string): 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. @return the name of the font.

    Parameters

    Returns string

Static registerCompositor

  • 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

    Returns void

Static Protected set_defaultCompositor

Static Protected set_defaultTextureFormat

  • set_defaultTextureFormat(value: string): string

Static unregisterBitmapFont

  • unregisterBitmapFont(name: string, dispose?: boolean): void

Static unregisterCompositor

  • unregisterCompositor(name: string, dispose?: boolean): void

Static updateEmbeddedFonts

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

    Returns void

Generated using TypeDoc