How to use the Feathers
TextFieldTextEditor 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
type property of the
TextField is set to
TextInput has focus, the
TextField instance is displayed on the classic display list above other Starling content. When focus is lost, the
TextField is drawn to
BitmapData and converted to a Starling
Texture to display as a snapshot within the Starling display list. This snapshot allows the
TextInput to be added to a scrolling container, and it will be properly clipped without the
TextField appearing above the other Starling content when it is not in focus.
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.
This text editor displays the classic Flash
TextField on the display list above Starling when the
TextInput has focus. When focused, this
TextField will not appear below other Starling display objects that might cover up the
TextInput when it is not focused. Generally, this situation does not happen frequently.
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
TextFieldTextEditor 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.
TextFieldTextEditor provides a slightly less native experience on mobile than
StageTextTextEditor. More advanced capabilities like copy and paste may not be available on all platforms when using
TextFieldTextEditor is best suited for situations where
StageTextTextEditor lacks other capabilities that your app requires, such as using embedded fonts.
TextField offers limited support right-to-left languages and bi-directional text, and
StageText or Flash Text Engine is recommended for these languages.
Advanced font styles
To use the classic Flash
TextInput, create a
TextFieldTextEditor in the appropriate factory exposed by the parent component. In the following example, we'll use the
textEditorFactory of a
Advanced font styles may be customized using the native
flash.text.TextFormat class. Pass an instance of
TextFormat to the text editor's
TextFormat allows you to customize font size, color, alignment, and more.
TextFieldTextEditor 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
TextFieldTextEditor API reference.
How to change advanced font styles when a parent component has multiple states
TextInput has multiple states, and it's possible to pass a different
TextFormat to the
TextFieldTextEditor for each state. When the parent component's state changes, the font styles of the text editor will update automatically.
For instance, we can provide a different font style for the focused state of a
TextInput by calling
We didn't provide separate font styles for other states, like
TextInput.STATE_DISABLED. When the
TextInput is in one of these states, the
TextFieldTextEditor 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
TextFieldTextEditor, pass the name specified in the
fontFamily parameter of the
[Embed] metadata to the
Be sure to set the
embedFonts property to