How to use the MaskedTextInput component

The MaskedTextInput class displays an editable text field where user interaction is restricted by an input mask, which may be used to require specific characters, or categories of characters, at specific positions.

⚠️ Beta Notice: This component is still quite new. Some APIs may go through minor changes in upcoming releases.

The Basics

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

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

User input may be restricted by setting the inputMask property. For each position in the string, the input mask determines if it must be a specific character, or if it is restricted to a specific category of characters. If the user attempts to type a character that is not allowed at a specific position, their input will be ignored.

The following categories of characters are available to compose an input mask.

  • 0 — Digit (required). Any numeric digit between 0 and 9. Equivalent to the regular expression [0-9].
  • 9 — Digit or space (optional). If the value is a space, the text property skips it.
  • # — Digit, space, + (plus), or - (minus) (optional). If the value is a space, the text property includes it. Allows + and - characters too.
  • L — Letter (required). Any letter in the ranges a-z and A-Z. Equivalent to the regular expression [a-zA-Z].
  • ? — Letter (optional). Equivalent to the regular expression [a-zA-Z]?.
  • & — Character (required). Similar to L, but allows non-control characters outside the range of a-z and A-Z.
  • C — Character (optional). Similar to ?, but allows non-control characters outside the range of a-z and A-Z.
  • A — Alphanumeric (required). Any numeric digit between 0 and 9, and any letter in the ranges a-z and A-Z.
  • a — Alphanumeric (optional). Any numeric digit between 0 and 9, and any letter in the ranges a-z and A-Z.
input.inputMask = "XY-0L.000";

Text may be changed programatically by setting the text property.

input.text = "XY-9A.123";

Warning! If the string value passed to the text property setter is not formatted to match the inputMask property, an ArgumentError will be thrown. Partial strings are allowed, so with the input mask in the example above, "XY-09" and "XY-49-" would be considered valid.

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, MaskedTextInput);
    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 MaskedTextInput 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.