Create a new text field with the given properties.
The opacity of the object. 0 = transparent, 1 = opaque. @default 1
Indicates whether the font size is automatically reduced if the complete text does not fit into the TextField. @default false
Specifies the type of auto-sizing the TextField will do. Note that any auto-sizing will implicitly deactivate all auto-scaling. @default none
The topmost object in the display tree the object is part of.
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
The blend mode determines how the object is blended with the objects underneath.
Draws a border around the edges of the text field. Useful for visual debugging. @default false
The bounds of the object relative to the local coordinates of the parent.
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
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.
@default Verdana, 12 pt, black, centered
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.
Indicates if this object or any of its parents is a 'Sprite3D' object.
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
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
Indicates if the masked region of this object is set to be inverted.
The name of the display object (default: null). Used by 'getChildByName()' of display object containers.
The number of children of this container.
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.
The display object container that contains this display object.
The x coordinate of the object's origin in its own coordinate space (default: 0).
The y coordinate of the object's origin in its own coordinate space (default: 0).
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
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.
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.
The rotation of the object in radians. (In Starling, all angles are measured in radians.)
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
The horizontal scale factor. '1' means no scale, negative values flip the object.
The vertical scale factor. '1' means no scale, negative values flip the object.
The horizontal skew angle in radians.
The vertical skew angle in radians.
The stage the display object is connected to, or null if it is not connected to the stage.
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.
The displayed text.
Returns the bounds of the text within the text field.
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.)
Indicates if this object (and its children) will receive touch events.
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!
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!
Indicates if the mouse cursor should transform into a hand while it's over the sprite.
The visibility of the object. An invisible object will be untouchable.
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.
Indicates if the text should be wrapped at word boundaries if it does not fit into the TextField otherwise. @default true
The x coordinate of the object relative to the local coordinates of the parent.
The y coordinate of the object relative to the local coordinates of the parent.
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
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.BGRAfor the highest quality.
@default Context3DTextureFormat.BGRA_PACKED
Adds a child to the container. It will be at the frontmost position.
Adds a child to the container at a certain index.
Moves the pivot point to a certain position within the local coordinate system of the object. If you pass no arguments, it will be centered.
Dispatches an event on all children (recursively). The event must not bubble.
Dispatches an event with the given parameters on all children (recursively). The method uses an internal pool of event objects to avoid allocations.
Determines if a certain object is a child of the container (recursively).
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.
Dispatches an event with the given parameters to all objects that have registered listeners for the given type. The method uses an internal pool of event objects to avoid allocations.
Disposes the underlying texture data.
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.
Returns a child object at a certain index. If you pass a negative index, '-1' will return the last child, '-2' the second to last child, etc.
Returns a child object with a certain name (non-recursively).
Returns the index of a child within the container, or "-1" if it is not found.
Returns the bounds of the text within the text field in the given coordinate space.
Creates a matrix that represents the transformation from the local coordinate system
to another. If you pass an out
-matrix, the result will be stored in this matrix
instead of creating a new object.
Creates a matrix that represents the transformation from the local coordinate system
to another. This method supports three dimensional objects created via 'Sprite3D'.
If you pass an out
-matrix, the result will be stored in this matrix
instead of creating a new object.
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.
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.
If called with one argument, figures out if there are any listeners registered for the given event type. If called with two arguments, also determines if a specific listener is registered.
Checks if a certain point is inside the display object's mask. If there is no mask,
this method always returns true
(because having no mask is equivalent
to having one that's infinitely big).
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.
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.
Removes a child from the container. If the object is not a child, the method returns
null
. If requested, the child will be disposed right away.
Removes a child at a certain index. The index positions of any display objects above the child are decreased by 1. If requested, the child will be disposed right away.
Removes a range of children from the container (endIndex included). If no arguments are given, all children will be removed.
Removes the object from its parent, if it has one, and optionally disposes it.
Moves a child to a certain index. Children at and after the replaced position move up.
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.
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.
Sorts the children according to a given (that works just like the sort function of the Vector class).
Swaps the indexes of two children.
Swaps the indexes of two children.
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.
Returns a registered text compositor (or null, if the font has not been registered). The name is not case sensitive.
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.
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).
Unregisters the bitmap font and, optionally, disposes it.
Unregisters the text compositor and, optionally, disposes it.
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.
Generated using TypeDoc
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:
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.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.