How to use the Alert component

The Alert class renders a window as a pop-up above all other content. Typically, an alert displays a header with a title, followed by some multiline text and an optional icon. A set of buttons to select different actions appears at the bottom of the alert.

The Basics

Creating an Alert works a bit differently than other components. Start by creating a button and listen for when it is triggered.

var button = new Button();
button.text = "Click Me";
button.addEventListener(TriggerEvent.TRIGGER, button_triggerHandler);
addChild(button);

The alert will be shown when the button is clicked or tapped. In the listener, rather than calling the Alert constructor, call the static function Alert.show() instead.

function button_triggerHandler(event:TriggerEvent):Void
{
    Alert.show("I have something important to say",
        "Warning",
        ["OK", "Cancel"],
        (state:ButtonBarItemState) -> {
          trace("Alert item trigger: " + event.state.text);
        }
    );
}

Three arguments are required, but the four are usually included. The first argument is the alert's primary message. The second argument is the title displayed in the alert's header. Third, the alert needs an array of strings to display as button text. Internally, the alert uses a ButtonBar to display its buttons. The fourth and final argument is a function that is called when one of the buttons is triggered. It receives a ButtonBarItemState object that may be used to determine which button was triggered.

Styles

A number of styles may be customized on the sub-components of an Alert component, including an optional background skin, and styles on the message label, the header, the button bar, and the scroll bars.

Background skin

Optionally give the alert 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;
alert.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 alert automatically calculates its preferred size based on the initial dimensions of its background skin (accounting for some other factors too, like header and footer, and 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 alert's border or fill may be customized to change when the alert is disabled. In the next example, setting the skin's disabledFill method makes it switch to a different fill when the alert 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 alert uses the same RectangleSkin for all states, and that skin listens for changes to the alert's current state. Alternatively, the alert's disabledBackgroundSkin method allows the alert to display a completely different display object when it is disabled.

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

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

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

Message Label

The message label in an Alert component is of type Label. Its appearance may be customized globally in a theme, or it may be customized outside of a theme on an specific, individual Alert.

See How to use the Label component for complete details about which styles are available for the message label.

Style message label globally

Use the Alert.CHILD_VARIANT_MESSAGE_LABEL constant in a theme to provide a function that globally styles the message labels in all Alert components.

styleProvider.setStyleFunction(
    Label,
    Alert.CHILD_VARIANT_MESSAGE_LABEL,
    setAlert_MessageLabel_Styles);

The function should use the following signature.

function setAlert_MessageLabel_Styles(label:Label):Void {
    // ... set styles here
}

Style the message label in a specific Alert

The messageLabelFactory property may be used to customize the creation of an individual message label.

alert.messageLabelFactory = () -> {
    var message = new Label();
    // ... set styles here
    return message;
};

Header

The header in an Alert component is of type Header. Its appearance may be customized globally in a theme, or it may be customized outside of a theme on an specific, individual Alert.

See How to use the Header component for complete details about which styles are available for the header.

Style header globally

Use the Alert.CHILD_VARIANT_HEADER constant in a theme to provide a function that globally styles the headers in all Alert components.

styleProvider.setStyleFunction(
    Header,
    Alert.CHILD_VARIANT_HEADER,
    setAlert_Header_Styles);

The function should use the following signature.

function setAlert_Header_Styles(header:Header):Void {
    // ... set styles here
}

Style the header in a specific Alert

The headerFactory property may be used to customize the creation of an individual header.

alert.headerFactory = () -> {
    var header = new Header();
    // ... set styles here
    return header;
};

ButtonBar

The button bar in an Alert component is of type ButtonBar. Its appearance may be customized globally in a theme, or it may be customized outside of a theme on an specific, individual Alert.

See How to use the ButtonBar component for complete details about which styles are available for the button bar.

Style button bar globally

Use the Alert.CHILD_VARIANT_BUTTON_BAR constant in a theme to provide a function that globally styles the buton bars in all Alert components.

styleProvider.setStyleFunction(
    ButtonBar,
    Alert.CHILD_VARIANT_BUTTON_BAR,
    setAlert_ButtonBar_Styles);

The function should use the following signature.

function setAlert_ButtonBar_Styles(buttonBar:ButtonBar):Void {
    // ... set styles here
}

Style the button bar in a specific Alert

The buttonBarFactory property may be used to customize the creation of an individual button bar.

alert.buttonBarFactory = () -> {
    var buttonBar = new ButtonBar();
    // ... set styles here
    return buttonBar;
};

Scroll bars

The scroll bars in an Alert component are of type HScrollBar and VScrollBar. Their appearance may be customized globally in a theme, or they may be customized outside of a theme on an specific, individual alert.

See How to use the HScrollBar and VScrollBar components for complete details about which styles are available for the scroll bars.

Style scroll bars globally

Use the HScrollBar and VScrollBar classes in a theme to provide a function that globally styles all scroll bars in your project.

styleProvider.setStyleFunction(HScrollBar, null, setHScrollBarStyles);
styleProvider.setStyleFunction(VScrollBar, null, setVScrollBarStyles);

The functions should use the following signatures.

function setHScrollBarStyles(scrollBar:HScrollBar):Void {
    // ... set styles here
}

function setVScrollBarStyles(scrollBar:VScrollBar):Void {
    // ... set styles here
}

Style scroll bars in a specific Alert

The scrollBarXFactory and scrollBarYFactory properties may be used to customize the creation of an individual alert's scroll bars.

alert.scrollBarXFactory = () -> {
    var scrollBar = new HScrollBar();
    // ... set styles here
    return scrollBar;
};

alert.scrollBarYFactory = () -> {
    var scrollBar = new VScrollBar();
    // ... set styles here
    return scrollBar;
};

Related Links

• feathers.controls.Alert API Reference