How to use the Feathers StageTextTextEditor component

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.

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

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;
};

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.