How to use the Feathers Alert component

The Alert class renders a window as a pop-up over all other content. Typically, an alert displays a header with a title, followed by some multiline, word-wrapped text, and a set of buttons to select different actions.

The Basics

We create an Alert a bit differently than other components. Rather than calling a constructor, we call the static function Alert.show(). Let's see how this works by displaying a simple message in an Alert when we touch a button. First, let's create the button:

var button:Button = new Button();
button.label = "Click Me";
button.addEventListener( Event.TRIGGERED, button_triggeredHandler );
this.addChild( button );

Then, in the listener for the button's Event.TRIGGERED event, we create the alert:

function button_triggeredHandler( event:Event ):void
{
    var button:Button = Button( event.currentTarget );
    var alert:Alert = Alert.show( "I have something important to say", "Warning", new ListCollection(
    [
        { label: "OK", triggered: okButton_triggeredHandler }
    ]) );
}

Three arguments are required. The first is the alert's message. The second argument is the title displayed in the alert's header. Finally, a ListCollection of button data must be passed in to display in a ButtonGroup.

In addition to listening for Event.TRIGGERED to be dispatched by individual buttons, you may also listen for Event.CLOSE on the alert:

alert.addEventListener( Event.CLOSE, alert_closeHandler );

The event object's data property will contain the item from the ButtonGroup data provider that is associated with the button that was triggered:

function alert_closeHandler( event:Event, data:Object ):void
{
    if( data.label == "OK" )
    {
        // the OK button was clicked
    }
}

Additional, optional arguments are available for Alert.show(). Let's take a look at those next.

Modality

Following the button group is the isModal argument. This determines whether there is an overlay between the alert and the rest of the display list. When an alert is modal, the overlay blocks touches to everything that appears under the alert. If the alert isn't modal, there will be no overlay to block the touch, and anything below the alert will remain interactive.

Alerts are displayed using the PopUpManager. By default, modal overlays are managed by the PopUpManager, but you can give a custom overlay to all alerts (that will be different from other modal pop-ups) when you set the static property, overlayFactory:

Alert.overlayFactory = function():DisplayObject
{
    return new TiledImage( myTexture );
};

When PopUpManager.addPopUp() is called to show the alert, the custom overlay factory will be passed in as an argument.

Centering

Following the modality is the isCentered argument. This determines if the alert will be globally centered on the Starling stage. If the alert or the stage is resized, the alert will be automatically repositioned to remain centered.

Custom Alert factory

When an alert is created with Alert.show(), the function stored by the Alert.alertFactory() property is called to instantiate an Alert instance. One of the final arguments of Alert.show() allows you to specify a custom alert factory. This let's you customize an individual alert to be different than other alerts. For instance, let's say that a particular alert should have different background skin than others. We might create an alert factory function like this:

function customAlertFactory():Alert
{
    var alert:Alert = new Alert();
    alert.styleNameList.add( "custom-alert" );
    return alert;
};
Alert.show( "I have something important to say", "Alert Title", new ListCollection({label: "OK"}), true, true, customAlertFactory );

If you're working with a theme, you can set a custom styling function for a Alert with the style name "custom-alert" to provide different skins for this alert.

Skinning an Alert

The skins for an Alert control are divided into the header, the message text renderer, and the button group. Additionally, an alert may have background skins and various other styles. For full details about what skin and style properties are available, see the Alert API reference.

Background skins and basic styles

We'll start the skinning process by giving our alert appropriate background skins.

alert.backgroundSkin = new Scale9Image( enabledTextures );
alert.backgroundDisabledSkin = new Image( disabledTextures );

The backgroundSkin property provides the default background for when the alert is enabled. The backgroundDisabledSkin is displayed when the alert is disabled. If the backgroundDisabledSkin isn't provided to a disabled alert, it will fall back to using the backgroundSkin in the disabled state.

Padding may be added around the edges of the alert. This padding is applied around the edges of the message text renderer, and is generally used to show a bit of the background as a border.

alert.paddingTop = 15;
alert.paddingRight = 20;
alert.paddingBottom = 15;
alert.paddingLeft = 20;

If all four padding values should be the same, you may use the padding property to quickly set them all at once:

alert.padding = 20;

Targeting an Alert in a theme

If you are creating a theme, you can specify a function for the default styles like this:

getStyleProviderForClass( Alert ).defaultStyleFunction = setAlertStyles;

If you want to customize a specific alert to look different than the default, you may use a custom style name to call a different function:

alert.styleNameList.add( "custom-alert" );

You can specify the function for the custom style name like this:

getStyleProviderForClass( Alert )
    .setFunctionForStyleName( "custom-alert", setCustomAlertStyles );

Trying to change the alert's styles and skins outside of the theme may result in the theme overriding the properties, if you set them before the alert was added to the stage and initialized. Learn to extend an existing theme to add custom skins.

If you aren't using a theme, then you may set any of the alert's properties directly.

Skinning the header

This section only explains how to access the header sub-component. Please read How to use the Feathers Header component for full details about the skinning properties that are available on Header components.

With a Theme

If you're creating a theme, you can target the Alert.DEFAULT_CHILD_STYLE_NAME_HEADER style name.

getStyleProviderForClass( Header )
    .setFunctionForStyleName( Alert.DEFAULT_CHILD_STYLE_NAME_HEADER, setAlertHeaderStyles );

You can override the default style name to use a different one in your theme, if you prefer:

alert.customHeaderStyleName = "custom-header";

You can set the styling function for the customHeaderStyleName like this:

getStyleProviderForClass( Header )
    .setFunctionForStyleName( "custom-header", setAlertCustomHeaderStyles );

Without a Theme

If you are not using a theme, you can use headerFactory to provide skins for the alert's header:

alert.headerFactory = function():Header
{
    var header:Header = new Header();
    //skin the header here
    header.backgroundSkin = new Scale9Image( headerBackgroundTextures );
    return header;
}

Alternatively, or in addition to the headerFactory, you may use the headerProperties to pass skins to the header.

alert.headerProperties.backgroundSkin = new Scale9Image( headerBackgroundTextures );

In general, you should only pass skins to the alert's header through headerProperties if you need to change skins after the header is created. Using headerFactory will provide slightly better performance, and your development environment will be able to provide code hinting thanks to stronger typing.

Skinning the buttons

This section only explains how to access the button group sub-component. Please read How to use the Feathers ButtonGroup component for full details about the skinning properties that are available on ButtonGroup components.

With a Theme

If you're creating a theme, you can target the Alert.DEFAULT_CHILD_STYLE_NAME_BUTTON_GROUP style name.

getStyleProviderForClass( ButtonGroup )
    .setFunctionForStyleName( Alert.DEFAULT_CHILD_STYLE_NAME_BUTTON_GROUP, setAlertButtonGroupStyles );

You can override the default style name to use a different one in your theme, if you prefer:

alert.customButtonGroupStyleName = "custom-button-group";

You can set the styling function for the customButtonGroupStyleName like this:

getStyleProviderForClass( ButtonGroup )
    .setFunctionForStyleName( "custom-button-group", setAlertCustomButtonGroupStyles );

Without a Theme

If you are not using a theme, you can use buttonGroupFactory to provide skins for the alert's button group:

alert.buttonGroupFactory = function():Header
{
    var group:ButtonGroup = new ButtonGroup();
    //skin the button group here
    group.gap = 20;
    return group;
}

Alternatively, or in addition to the buttonGroupFactory, you may use the buttonGroupProperties to pass skins to the button group.

alert.buttonGroupProperties.gap = 20;

In general, you should only pass skins to the alert's button group through buttonGroupProperties if you need to change skins after the button group is created. Using buttonGroupFactory will provide slightly better performance, and your development environment will be able to provide code hinting thanks to stronger typing.

Skinning the message text renderer

This section only explains how to access the message text renderer sub-component. Please read Introduction to Feathers Text Renderers for full details about how to style different kinds of Feathers text renderers.

With a Theme

If you're creating a theme, you can target the Alert.DEFAULT_CHILD_STYLE_NAME_MESSAGE style name. In the following examples, we'll use a BitmapFontTextRenderer, but other text renderers may be used instead, if desired.

getStyleProviderForClass( BitmapFontTextRenderer )
    .setFunctionForStyleName( Alert.DEFAULT_CHILD_STYLE_NAME_MESSAGE, setAlertMessageStyles );

Without a Theme

If you are not using a theme, you can use messageFactory to provide skins for the alert's message:

alert.messageFactory = function():ITextRenderer
{
    var message:BitmapFontTextRenderer = new BitmapFontTextRenderer();
    //skin the message here
    message.textFormat = new BitmapFontTextFormat( bitmapFont );
    return message;
}

Alternatively, or in addition to the messageFactory, you may use the messageProperties to pass properties to the text renderer.

alert.messageProperties.textFormat = new BitmapFontTextFormat( bitmapFont );

In general, you should only pass skins to the alert's message text renderer through messageProperties if you need to change skins after the message text renderer is created. Using messageFactory will provide slightly better performance, and your development environment will be able to provide code hinting thanks to stronger typing.

Customizing the Alert factories

If you're not using a theme, you can specify a factory to create the alert, including setting skins, in a couple of different ways. The first is to set the Alert.alertFactory static property to a function that provides skins for the alert. This factory will be called any time that Alert.show() is used to create an alert.

function skinnedAlertFactory():Alert
{
    var alert:Alert = new Alert();
    alert.backgroundSkin = new Scale9Image( myTextures );
    // etc...
    return alert;
};
Alert.alertFactory = skinnedAlertFactory;

Another option is to pass an alert factory to Alert.show(). This allows you to create a specific alert differently than the default global Alert.alertFactory.

function skinnedAlertFactory():Alert
{
    var alert:Alert = new Alert();
    alert.backgroundSkin = new Scale9Image( myTextures );
    // etc...
    return alert;
};
Alert.show( message, title, buttons, isModal, isCentered, skinnedAlertFactory );

You should generally always skin the alerts with a factory or with a theme instead of passing the skins to the Alert instance returned by calling Alert.show(). If you skin an alert after Alert.show() is called, it may not be positioned or sized correctly anymore.

Closing and disposal

The alert will automatically remove itself from the display list and dispose itself when one of its buttons is triggered. To manually close and dispose the alert without triggering a button, you may simply remove the alert from its parent:

alert.removeFromParent( true );