How to use the TextInput component

The TextInput class displays editable text in a single line.

For editable text with multiple wrapping lines and scrolling, see the TextArea component.

Live preview of the TextInput component

The Basics

Create a TextInput control and add it to the the display list.

var input = new TextInput();
addChild(input);

Text may be changed programatically by setting the text property.

input.text = "Matt Murdock";

Add an event listener for Event.CHANGE to perform an action when the user edits the text.

input.addEventListener(Event.CHANGE, textInput_changeHandler);

Check for the new value of the text property in the listener function.

function textInput_changeHandler(event:Event):Void {
    var input = cast(event.currentTarget, TextInput);
    trace("text input change: " + input.text);
}

States

When the user interacts with a text input using the mouse, keyboard, or touchscreen, its state will change, which may affect its appearance. For instance, the text input's background skin and font styles may be rendered differently in different states.

The TextInputState enum defines the states available to all text input components.

  • ENABLED is the text input's default state.
  • DISABLED is the text input's state when its enabled property has been set to false.
  • FOCUSED is the text input's state when it currently has focus.
  • ERROR is the text input's state when an error string has been set.

Styles

A number of styles may be customized on a TextInput component, including the font styles and the background skin. Several more styles may be used to adjust the layout of the text input's children.

Font styles

The font styles of the text input's text may be customized by passing an openfl.text.TextFormat object to the textFormat property.

input.textFormat = new TextFormat("Helvetica", 20, 0x3c3c3c);

If the text input's text should use different font styles when the text input is in different states, pass a TextFormat and state value to the setTextFormatForState() method.

input.setTextFormatForState(TextInputState.FOCUSED, new TextFormat("Helvetica", 20, 0xcc0000));

Using the code above, the color of the text input's text will change when the text input receives focus, and the state changes to TextInputState.FOCUSED.

When font styles aren't available for a specific state, the text input will use the default textFormat as a fallback.

Background skin

Give the text input a background using the backgroundSkin property. The following example sets it to a RectangleSkin instance.

var skin = new RectangleSkin();
skin.border = SolidColor(1.0, 0x999999);
skin.fill = SolidColor(0xcccccc);
skin.width = 64.0;
skin.height = 32.0;
input.backgroundSkin = skin;

The border and fill properties of the RectangleSkin are used to adjust its appearance. They support a variety of values — from solid colors to gradients to bitmaps.

The text input automatically calculates its preferred size based on the initial dimensions of its background skin (accounting for some other factors too, like the dimensions of the text), so it's important to set a skin's width and height properties to appropriate values to use in this calculation.

See Skinning with common shapes for more details about how to use RectangleSkin with the LineStyle and FillStyle enums that change its border and fill appearance.

The appearance of the text input's border or fill may be customized to change based on the text input's current state, such as when the text input receives focus, there is an error string, or the text input is disabled. In the next example, a call to the skin's setFillForState() method makes it switch to a different fill when the text input's FOCUSED state is active.

skin.setFillForState(TextInputState.FOCUSED, SolidColor(0xffcccc));

Similarly, use the skin's setBorderForState() method to change the border for a specific state.

skin.setBorderForState(TextInputState.FOCUSED, SolidColor(2.0, 0x999999));

In the examples above, the text input uses the same RectangleSkin for all states, and that skin listens for changes to the text input's current state. Alternatively, the text input's setSkinForState() method allows the text input to display a completely different display object when its current state changes.

var defaultSkin = new RectangleSkin();
// ... set border, fill, width, and height
input.backgroundSkin = defaultSkin;

var hoverSkin = new RectangleSkin();
// ... set border, fill, width, and height
input.setSkinForState(TextInputState.FOCUSED, hoverSkin);

In the example above, the text input will have a custom skin for the FOCUSED state, and all other states will share the default backgroundSkin.