How to use the Form and FormItem components

The Form and FormItem classes may be used to group a set of user-editable fields together. A form supports the submission of data when the Enter/Return key is pressed, or when a specific button is triggered.

Live preview of the Form and FormItem components

⚠️ Beta Notice: This component is still quite new to Feathers UI. It was included in the latest release because it should be stable enough for production use. However, some APIs may go through minor changes in upcoming releases — based on feedback from developers like you. Learn more about Beta APIs.

The Basics

Create a Form component, and add it to the display list.

var form = new Form();
addChild(form);

Typically, when you want to add a field to the form, you will wrap a UI control with a FormItem. Below, a TextInput is added to the form, with some descriptive text.

var nameItem = new FormItem();
nameItem.text = "Name:";
nameItem.content = new TextInput();
form.addChild(nameItem);

Like most Feathers UI containers, any type of display object may be added as a child of a Form. You are not strictly required to wrap all children with a FormItem.

Add an event listener for FormEvent.SUBMIT to perform an action when the form is submitted.

form.addEventListener(FormEvent.SUBMIT, form_submitHandler);

Listeners for FormEvent.SUBMIT have the following function signature.

function form_submitHandler(event:FormEvent):Void {
    var form = cast(event.currentTarget, Form);
    trace("form submitted");
}

Submit button

Set the submitButton property to indicate that a specific button should cause the form to dispatch FormEvent.SUBMIT.

var sendButton = new Button();
sendButton.text = "Send";
form.addChild(sendButton);

form.submitButton = sendButton;

Required form items

Sometimes, some items in a form are optional, while others are required. Typically, an asterisk or other symbol is displayed next to required form items. Set a form item's required property to indicate that it is required.

var nameItem = new FormItem();
nameItem.required = true;

Warning! Marking a form item as required does not automatically prevent the Form from being submitted. It is simply a visual indication, and manual form validation is required to cancel submission if data is missing.

Form Styles

A Form component may have an optional background skin.

Background skin

Optionally give the form 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 = 16.0;
skin.height = 16.0;
form.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 form automatically calculates its preferred size based on the initial dimensions of its background skin (accounting for some other factors too, like the size and position of children), 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 form's border or fill may be customized to change when the form is disabled. In the next example, setting the skin's disabledFill method makes it switch to a different fill when the form is disabled.

skin.disabledFill = SolidColor(0xffcccc);

Similarly, use the skin's disabledBorder property to change the border when disabled.

skin.disabledBorder = SolidColor(2.0, 0x999999);

In the examples above, the form uses the same RectangleSkin for all states, and that skin listens for changes to the form's current state. Alternatively, the form's disabledBackgroundSkin method allows the form to display a completely different display object when it is disabled.

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

var disabledSkin = new RectangleSkin();
// ... set border, fill, width, and height
form.disabledBackgroundSkin = disabledSkin;

In the example above, the form will have a separate skins when enabled and disabled.

FormItem Styles

A number of styles may be customized on a FormItem component, including the font styles, an optional background skin, and various layout adjustments.

Font styles

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

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

If the label's text should use different font styles when the form item is disabled, pass a TextFormat and state value to the disabledTextFormat property.

Background skin

Optionally give the form item a background using the backgroundSkin property. This property works similarly to the Form background skin, described above.

Required skin

When a form item is required, its requiredSkin will be displayed.

The following example loads a required skin using its name registered with OpenFL's asset manager.

formItem.requiredSkin = new Bitmap(Assets.getBitmapData("myAssetName"));

Layout

The textPosition property controls how the form item's text is positioned, relative to its content.

formItem.textPosition = LEFT;

Padding may be added on each side of the form item, including top, right, bottom, and left.

formItem.paddingTop = 5.0;
formItem.paddingRight = 8.0;
formItem.paddingBottom = 5.0;
formItem.paddingLeft = 8.0;

The gap refers to the space, measured in pixels, between the text and the content.

formItem.gap = 10.0;

The horizontalAlign and verticalAlign properties will adjust the alignment of the content within the form item's available space.

formItem.horizontalAlign = JUSTIFY;
formItem.verticalAlign = MIDDLE;