How to use the TextArea component

The TextArea class displays editable text wrapped over multiple lines that may be scrolled.

For a single line of editable text, see the TextInput component.

Live preview of the TextArea component

The Basics

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

var textArea = new TextArea();
addChild(textArea);

Text may be changed programatically by setting the text property.

textArea.text = "Jessica Jones";

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

textArea.addEventListener(Event.CHANGE, textArea_changeHandler);

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

function textArea_changeHandler(event:Event):Void {
    var textArea = cast(event.currentTarget, TextArea);
    trace("text area change: " + textArea.text);
}

States

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

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

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

Styles

A number of styles may be customized on a TextArea component, including the font styles and the background skin.

Font styles

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

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

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

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

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

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

Background skin

Give the text area 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 area 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 area's border or fill may be customized to change based on the text area's current state, such as when the text area receives focus, there is an error string, or the text area is disabled. In the next example, a call to the skin's setFillForState() method makes it switch to a different fill when the text area'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 area uses the same RectangleSkin for all states, and that skin listens for changes to the text area's current state. Alternatively, the text area's setSkinForState() method allows the text area to display a completely different display object when its current state changes.

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

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

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