How to use the TextFieldTextRenderer component (Starling version)

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

TextFieldTextRenderer is one of many different text renderers supported by Feathers. Since no method of rendering text on the GPU is considered definitively better than the others, Feathers allows you to choose the best text renderer for your project's requirements. See Introduction to Feathers text renderers for complete details about all of the text rendering options supported by Feathers.

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:

  • TextField may render incorrectly when drawn to BitmapData immediately after its properties have been changed. As a workaround, TextFieldTextRenderer can wait one frame before drawing to BitmapData and 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.

  • TextField offers 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

In general, you should customize font styles on the parent component of a text renderer using a starling.text.TextFormat object. For example, to customize the font styles on a Button component, you'd set the button's fontStyles property.

button.fontStyles = new TextFormat( "Helvetica", 20, 0xcc0000 );

However, starling.text.TextFormat object does not always expose every unique font styling feature that a text renderer supports. The next section demostrates how to set advanced font styles that may not be exposed through this class.

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 Button component:

var button:Button = new Button();
button.label = "Click Me";
button.labelFactory = function():ITextRenderer
{
	var textRenderer:TextFieldTextRenderer = new TextFieldTextRenderer();
	textRenderer.styleProvider = null;

	//set advanced font styles here

	return textRenderer;
};

You may need to remove the text renderer's style provider in the factory before changing font styles to avoid conflicts with the default styles set by a theme. That's why the styleProvider property is set to null in the code above.

Advanced font styles may be customized using the native flash.text.TextFormat class. Pass an instance of TextFormat to the text renderer's textFormat property:

textRenderer.textFormat = new TextFormat( "Source Sans Pro", 16, 0xcccccc );

The TextFormat allows you to customize font size, color, alignment, and more.

var format:TextFormat = new TextFormat( "Helvetica" );
format.size = 20;
format.color = 0xc4c4c4;
format.align = TextFormatAlign.CENTER;

To render the text property of the TextFieldTextRenderer using a limited subset of HTML, set the isHTML property to true:

textRenderer.text = "<span class='heading'>hello</span> world!";
textRenderer.isHTML = true;

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 Button and 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 setTextFormatForState():

var defaultFormat:TextFormat = new TextFormat( "Helvetica", 20, 0xc4c4c4 );
textRenderer.textFormat = defaultFormat;

var downFormat:TextFormat = new TextFormat( "Helvetica", 20, 0x343434 );
textRenderer.setTextFormatForState( ButtonState.DOWN, downFormat );

We didn't provide separate font styles for other states, like ButtonState.HOVER or ButtonState.DISABLED. When the Button is in one of these states, the TextFieldTextRenderer will fall back to using the value we passed to the textFormat property.

Using embedded fonts

To embed a TTF or OTF font for TextFieldTextRenderer, use [Embed] metadata, like this:

[Embed(source="my-font.ttf",fontFamily="My Font Name",fontWeight="normal",fontStyle="normal",mimeType="application/x-font",embedAsCFF="false")]
private static const MY_FONT:Class;

Here are the parameters:

  • The source parameter is the path to the TTF or OTF font file.
  • fontFamily gives a name to the font. This name will be passed to the TextFormat object.
  • The fontWeight parameter controls which weight is embedded.
  • The fontStyle parameter controls whether the font is italic or not.
  • The mimeType parameter must be set to application/x-font.
  • The embedAsCFF parameter must be set to false to use a font with the classic Flash TextField.

To use an embedded font with TextFieldTextRenderer, pass the name specified in the fontFamily parameter of the [Embed] metadata to the TextFormat object.

textRenderer.textFormat = new TextFormat( "My Font Name", 16, 0xcccccc );
textRenderer.embedFonts = true;

Be sure to set the embedFonts property to true.

When setting font styles with starling.text.TextFormat, the TextFieldTextRenderer automatically detects if a font is embedded. The embedFonts property only needs to be set when using flash.text.TextFormat to provide advanced font styles.