How to use the Button component

The Button class displays a button that may be triggered by a mouse click or a tap on a touchscreen. It can optionally display text, an icon, or both — with a variety of layout options. Buttons have separate states for each of the different pointer phases. The skin and icon can be customized for each state, and the text may be rendered with different font styles for each state too.

Live preview of the Button component

The Basics

Start by creating a Button control, give it some text to display, and add it to the display list.

var button = new Button();
button.text = "Click Me";
addChild(button);

Add an event listener for TriggerEvent.TRIGGER to perform an action when the button is clicked or tapped.

button.addEventListener(TriggerEvent.TRIGGER, button_triggerHandler);

Listeners for TriggerEvent.TRIGGER have the following function signature.

function button_triggerHandler(event:TriggerEvent):Void {
    var button = cast(event.currentTarget, Button);
    trace("button triggered: " + button.text);
}

States

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

The ButtonState enum defines the states available to all button components.

  • UP is the button's default state when the user is not interacting with it, and the button is enabled.
  • DOWN is the state when the user presses the button with a mouse, touchscreen, or by pressing Keyboard.SPACE when the button is focused.
  • HOVER is the state when the mouse is hovering over the button. This state is not used for touchscreens or keyboard interaction.
  • DISABLED is the button's state when its enabled property has been set to false.

Styles

A number of styles may be customized on a Button component, including the font styles, the background skin, and an optional icon. Several more styles may be used to adjust the layout of the button's children.

Font styles

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

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

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

button.setTextFormatForState(ButtonState.DOWN, new TextFormat("Helvetica", 20, 0xcc0000));

Using the code above, the color of the button's text will change when the button is pressed, and the state changes to ButtonState.DOWN.

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

Background skin

Give the button 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;
button.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 button 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 and icon), 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 button's border or fill may be customized to change based on the button's current state, such as when the button is pressed down, the mouse is hovering over it, or the button is disabled. In the next example, a call to the skin's setFillForState() method makes it switch to a different fill when the button's DOWN state is active.

skin.setFillForState(ButtonState.DOWN, SolidColor(0xffcccc));

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

skin.setBorderForState(ButtonState.DOWN, SolidColor(2.0, 0x999999));

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

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

var hoverSkin = new RectangleSkin();
// ... set border, fill, width, and height
button.setSkinForState(ButtonState.HOVER, hoverSkin);

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

Icon

A button may optionally display an icon next to its the text (or it may display an icon without any text).

The following example loads an icon using its name registered with OpenFL's asset manager.

button.icon = new Bitmap(Assets.getBitmapData("myAssetName"));

Similar to the background skin, the button's icon may be optionally customized for different states.

button.setIconForState(ButtonState.DOWN, new Bitmap(Assets.getBitmapData("anotherAssetName")));

This example uses a Bitmap for the button's icon, but any type of display object may be used. Additionally, while it can be convenient to load icons with the Assets class, icons may come from anywhere — even by drawing them programatically.

Layout

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

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

The icon may be positioned on any side of the button's text. For instance, the following example moves the icon above the text, so that the icon and text are stacked vertically.

button.iconPosition = TOP;

Set the iconPosition property to any of the RelativePosition values.

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

button.gap = 10.0;

The horizontalAlign and verticalAlign properties will adjust the alignment of the icon and text inside the button, allowing you to anchor them at the edges or in the center.

button.horizontalAlign = CENTER;
button.verticalAlign = MIDDLE;