How to use the Feathers TextInput component

The TextInput class supports the editing of text. It displays a background skin and uses a text editor to allow the user to modify the text.

The Basics

First, let's create a TextInput control and add it to the display list:

var input:TextInput = new TextInput();
this.addChild( input );

Changing text programmatically

Text may be changed programatically by setting the text property:

input.text = "Hello World";

Prompt

A prompt or hint may be displayed to describe the purpose of the text input when the text input does not contain any text.

input.prompt = "Password";

Simply set the prompt property to any String to display it inside the text input.

The prompt is a standard text renderer, and it may be customized with the promptFactory property:

input.promptFactory = function():ITextRenderer
{
    var textRenderer:BitmapFontTextRenderer = new BitmapFontTextRenderer();
 
    // customize properties and styleshere
    textRenderer.textFormat = new BitmapFontTextFormat( bitmapFont );
 
    return textRenderer;
}

If you aren't using a theme, you can customize the prompt's text format in the factory. Alternatively, you can use the promptProperties object to customize properties:

input.promptProperties.textFormat = new BitmapFontTextFormat( bitmapFont );

Using a custom factory is better for performance and it will allow you to use code hinting in your IDE, if available.

Focus and Selection

You may programmatically set focus to the text input by calling setFocus():

input.setFocus();

You can select part of the text too:

input.selectRange(0, input.text.length);

If you simply want to set the position of the cursor, you can omit the second argument to selectRange():

input.selectRange(0);

Events

Text inputs provide a number of useful events. One of the most common requirements is knowing, in real time, when the value of the text property has changed:

input.addEventListener( Event.CHANGE, input_changeHandler );

We can listen for Event.CHANGE.

We might also want to know when the user presses Keyboard.ENTER:

input.addEventListener( FeathersEventType.ENTER, input_enterHandler );

Simply listen for FeathersEventType.ENTER.

Finally, you might also want to know when the text input receives and loses focus:

input.addEventListener( FeathersEventType.FOCUS_IN, input_focusInHandler );
input.addEventListener( FeathersEventType.FOCUS_OUT, input_focusOutHandler );

The FeathersEventType.FOCUS_IN and FeathersEventType.FOCUS_OUT events are specially dispatched by the TextInput, even if the focus manager is not enabled.

Customizing Behavior

The displayAsPassword property may be enabled to mask a text input's text:

input.displayAsPassword = true;

Set the isEditable property to false to make the text uneditable, without giving the text input a disabled appearance:

input.isEditable = false;

To limit the number of characters that may be entered, use the maxChars property:

input.maxChars = 16;

The restrict property limits the set of characters that can be entered into the text input. It works like the restrict property on flash.text.TextField.

input.restrict = "0-9";

In the example above, we restrict to numeric values only.

Skinning a TextInput

A text input provides a number of properties to customize its appearance. For full details about what skin and style properties are available, see the TextInput API reference. We'll look at a few of the most common properties below.

Font Styles

This section explains how to customize the font styles used by the text editor sub-component. Feathers provides multiple text editors to choose from, and each one will have different properties that may be set to customize font styles and other capabilities. For more information about text editors, including which ones are available, please read Introduction to Feathers Text Editors.

The font styles of a text input may be changed through the . Each text editor displays fonts differently and has different properties, so the way to make changes to the font styles depends on each text editor.

The text editor may be styled using the textEditorFactory:

input.textEditorFactory = function():ITextEditor
{
    var editor:StageTextTextEditor = new StageTextTextEditor();
    editor.fontFamily = "Helvetica";
    editor.fontSize = 12;
    editor.color = 0x333333;
    return editor;
}

You may also pass properties to the text editor through textEditorProperties:

input.textEditorProperties.fontFamily = "Helvetica";
input.textEditorProperties.fontSize = 12;
input.textEditorProperties.color = 0x333333;

Using the textEditorProperties hash is a bit slower, so if the font styles do not change, you should always use the textEditorFactory. The textEditorProperties is best for when the font styles change after the editor is initially created.

Background and Layout

In addition to changing font styles on the text editor, you can change the text input's background skin and padding. Text input has three separate background skins, but two of them are optional.

input.backgroundSkin = new Scale9Image( backgroundSkinTextures );
input.backgroundDisabledSkin = new Scale9Image( disabledBackgroundSkinTextures );
input.backgroundFocusedSkin = new Scale9Image( focusedBackgroundSkinTextures );

The default backgroundSkin is displayed when the text input doesn't have focus and is enabled. The backgroundDisabledSkin is displayed when the text input is not enabled, but if you don't provide a disabled background skin, the default background skin will be used. Similarly, the backgroundFocusedSkin is displayed when the text input has focus. Again, text input will fall back to the default background skin if there is no focused background skin.

You can change the padding values on each side:

input.paddingTop = 10;
input.paddingRight = 10;
input.paddingBottom = 10;
input.paddingLeft = 10;

The dimensions of the text editor will be affected by the padding to show more of the background skin around the edges. This can allow you to reveal a border.

The typicalText property may be used to help the text input calculate its dimensions based on the dimensions of a specific rendered string:

input.typicalText = "The quick brown fox jumps over the lazy dog";

By default, the text input uses only its background skin for measurement. typicalText is useful when there is a width or height that must be based on the font styles. For instance, the NumericStepper component uses this property to provide the text input with a string that represents the largest possible string it might display.

Targeting a TextInput in a theme

If you are creating a theme, you can set a function for the default styles like this:

getStyleProviderForClass( TextInput ).defaultStyleFunction = setTextInputStyles;

If you want to customize a specific text input to look different than the default, you may use a custom style name to call a different function:

input.styleNameList.add( "custom-text-input" );

You can set the function for the custom style name like this:

getStyleProviderForClass( TextInput )
    .setFunctionForStyleName( "custom-text-input", setCustomTextInputStyles );

Trying to change the text input's styles and skins outside of the theme may result in the theme overriding the properties, if you set them before the text input was added to the stage and initialized. Learn to extend an existing theme to add custom skins.

If you aren't using a theme, then you may set any of the text input's properties directly.