How to use the StageTextTextEditor component (Starling version)
The StageTextTextEditor
class renders text using flash.text.StageText
. StageText
is optimized to use the native text input controls on mobile platforms like iOS and Android. StageText
supports native copy/paste, auto-correction, auto-completion, text selection, and other advanced text input capabilities.
When the TextInput
has focus, the StageText
instance is displayed on a layer above other Starling content. When focus is lost, the StageText
is drawn to BitmapData
and converted to a Starling Texture
to display as a snapshot within the Starling display list. This allows the TextInput
to be added to a scrolling container, and it will be properly clipped without the StageText
appearing above the other Starling content when it is not in focus.
StageTextTextEditor
is one of many different text editors supported by the FeathersTextInput
component. Since no method of editing text is considered definitively better than the others, Feathers allows you to choose the best text editor for your project's requirements. See Introduction to Feathers text editors for complete details about all of the text editing options supported by Feathers.
Advantages and disadvantages
StageTextTextEditor
may use 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.
Embedded fonts are not officially supported. If you need embedded fonts on mobile, you should use TextFieldTextEditor
instead.
StageTextTextEditor
may be used in desktop apps, but other text editors are recommended because they provide more features and customizability.
Features of StageText
vary both in availability and behavior per platform. On some platforms, some properties may be completely ignored. Check the StageText
API documentation for full details.
This text editor displays a StageText
on a layer above Starling when the TextInput
has focus. When focused, this StageText
will not appear below other Starling display objects that might otherwise 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 StageTextTextEditor
on screen at the same time.
Advanced font styles
In general, you should customize font styles on the parent component of a text editor using a
starling.text.TextFormat
object. For example, to customize the font styles on aTextInput
component, you'd set the input'sfontStyles
property.input.fontStyles = new TextFormat( "Helvetica", 20, 0xcc0000 );
However,
starling.text.TextFormat
object does not always expose every unique font styling feature that a text editor supports. The next section demostrates how to set advanced font styles that may not be exposed through this class.
To use flash.text.StageText
with TextInput
, create a StageTextTextEditor
in the appropriate factory exposed by the parent component. In the following example, we'll use the textEditorFactory
of a TextInput
component:
var input:TextInput = new TextInput();
input.textEditorFactory = function():ITextEditor
{
var textEditor:StageTextTextEditor = new StageTextTextEditor();
textEditor.styleProvider = null;
//set advanced font styles here
return textEditor;
};
You may need to remove the text editor'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 tonull
in the code above.
Advanced font styles may be customized using the text editor's properties like fontFamily
, fontSize
, and color
. Many of the property names defined by StageText
are duplicated on StageTextTextEditor
:
textEditor.fontFamily = "Arial";
textEditor.fontSize = 16;
textEditor.color = 0xcccccc;
StageTextTextEditor
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 StageTextTextEditor
API reference.