How to use the Feathers
TextFieldTextRenderer class renders text using the classic flash.text.TextField a software-based vector font renderer. Text may be rendered with either device fonts (the fonts installed on a user's operating system) or embedded fonts (in TTF or OTF formats). The
TextField is drawn to
BitmapData and converted to a Starling
Texture to display as a snapshot within the Starling display list.
Advantages and disadvantages
The classic Flash
TextField may render text using device fonts, which are the fonts installed on the user's operating system. For some languages with many glyphs and ligatures, device fonts may be the only option when embedded fonts would require too much memory.
Similarly, since embedded vector fonts often require less memory than embedded bitmap fonts, you may still be able to use embedded vector fonts when bitmap fonts would require too much memory.
Changing vector-based text on the GPU is slower than with bitmap fonts because the text needs to be redrawn to
BitmapData and then it needs to be uploaded to a texture on the GPU. However, once this texture is on the GPU, performance will be very smooth as long as the text doesn't change again. For text that changes often, the texture upload time may become a bottleneck.
Because each passage of vector text needs to be drawn to
BitmapData, each separate renderer requires its own separate texture on the GPU. This results in more state changes and draw calls, which can create more work for the GPU, and it might hurt performance if you have many different instances of
TextFieldTextRenderer on screen at the same time.
flash.text.TextField can sometimes render a bit faster than Flash Text Engine. However, this performance difference is generally negligible.
flash.text.TextField has some known issues and limitations:
TextFieldmay render incorrectly when drawn to
BitmapDataimmediately after its properties have been changed. As a workaround,
TextFieldTextRenderercan wait one frame before drawing to
BitmapDataand uploading as a texture when the text or font styles are changed. Often, this delay will not be an issue, but it can be seen if watching closely.
TextFieldoffers limited support for some languages, including right-to-left languages and bi-directional text, and Flash Text Engine is recommended for these languages.
TextFieldTextRenderer supports a limited subset of HTML courtesy of
flash.text.TextField. This may be used to render richer text with multiple font styles.
Advanced font styles
To render text with the classic Flash
TextField, create a
TextFieldTextRenderer in the appropriate factory exposed by the parent component. In the following example, we'll use the
labelFactory of a
Advanced font styles may be customized using the native
flash.text.TextFormat class. Pass an instance of
TextFormat to the text renderer's
TextFormat allows you to customize font size, color, alignment, and more.
To render the
text property of the
TextFieldTextRenderer using a limited subset of HTML, set the
isHTML property to
TextFieldTextRenderer provides a number of other advanced properties that may be customized, but aren't included in this quick introduction. For complete details about available properties, please take a look at the
TextFieldTextRenderer API reference.
How to change advanced font styles when a parent component has multiple states
Some components, like
TextInput, have multiple states. It's possible topass more than one
TextFormat to the
TextFieldTextRenderer so that the font styles change when the parent component's state changes.
For instance, we can provide a different font style for the down state of a
Button by calling
We didn't provide separate font styles for other states, like
ButtonState.DISABLED. When the
Button is in one of these states, the
TextFieldTextRenderer will fall back to using the value we passed to the
Using embedded fonts
To embed a TTF or OTF font for
[Embed] metadata, like this:
Here are the parameters:
sourceparameter is the path to the TTF or OTF font file.
fontFamilygives a name to the font. This name will be passed to the
fontWeightparameter controls which weight is embedded.
fontStyleparameter controls whether the font is italic or not.
mimeTypeparameter must be set to
embedAsCFFparameter must be set to
falseto use a font with the classic Flash
To use an embedded font with
TextFieldTextRenderer, pass the name specified in the
fontFamily parameter of the
[Embed] metadata to the
Be sure to set the
embedFonts property to