How to use the Alert component (Starling version)

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 text and an optional icon. A set of buttons to select different actions appears at the bottom of the alert.

Screenshot of Feathers a Alert component
An Alert component skinned with MetalWorksMobileTheme

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 ArrayCollection(
	[
		{ 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 collection 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.

Icon

An optional icon may be displayed next to the alert's message. We'll use a starling.display.Image in the following example, but the icon may be any Starling display object:

var icon:Image = new Image( iconTexture );
Alert.show( message, title, buttons, icon );

Pass in the icon after the alert's buttons.

Modality

Following the icon 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
{
	var tiledBackground:Image = new Image( texture );
	tiledBackground.tileGrid = new Rectangle();
	return tiledBackground;
};

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 ArrayCollection({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

A number of styles may be customized on an alert, including the message font styles, the background skin, and an optional icon. Additionally, alert has some sub-components that may be styled, including the header and the button group. For full details about which properties are available, see the Alert API reference. We'll look at a few of the most common ways of styling an alert below.

Font styles

The font styles of the alert's message may be customized using the fontStyles and disabledFontStyles properties:

alert.fontStyles = new TextFormat( "Helvetica", 20, 0x3c3c3c );
alert.disabledFontStyles = new TextFormat( "Helvetica", 20, 0x9a9a9a );

Pass in a starling.text.TextFormat object, which will work with any type of text renderer.

The font styles of the alert's title may be customized on the alert's Header component. See How to use the Header component for details.

The font styles of the alert's buttons may be customized through the alert's ButtonGroup component. See How to use the ButtonGroup component for details.

Background skin

The background skin fills the full width and height of the alert. In the following example, we pass in a starling.display.Image, but the skin may be any Starling display object:

var skin:Image = new Image( enabledTexture );
skin.scale9Grid = new Rectangle( 2, 4, 3, 8 );
alert.backgroundSkin = skin;

It's as simple as setting the backgroundSkin property.

A separate backgroundDisabledSkin may be provided to display when the alert is disabled:

var disabledSkin:Image = new Image( disabledTexture );
disabledSkin.scale9Grid = new Rectangle( 2, 4, 3, 8 );
alert.backgroundDisabledSkin = disabledSkin;

If the backgroundDisabledSkin isn't provided to a disabled alert, it will fall back to using the default backgroundSkin in the disabled state.

Layout

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;

If an optional icon is displayed, you may use the gap property to add some space between the message and the icon:

alert.gap = 12;

Skinning the header

This section only explains how to access the header sub-component. Please read How to use the 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 );

The styling function might look like this:

private function setAlertHeaderStyles( header:Header ):void
{
	header.backgroundSkin = new Image( headerBackgroundTexture );
	header.fontStyles = new TextFormat( "Helvetica", 16, 0x3c3c3c );
}

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, if you're not using a theme
	header.backgroundSkin = new Image( headerBackgroundTexture );
	header.fontStyles = new TextFormat( "Helvetica", 16, 0x3c3c3c );

	return header;
}

Skinning the buttons

This section only explains how to access the button group sub-component. Please read How to use the 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 );

The styling function might look like this:

private function setAlertButtonGroupStyles( group:ButtonGroup ):void
{
	group.gap = 20;
}

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, if you're not using a theme
	group.gap = 20;

	return group;
}

Using a factory to skin an Alert without a theme

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 Image( texture );
	// 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 Image( texture );
	// 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 necessarily 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. In most cases, you don't need to do any kind of cleanup.

To manually close and dispose the alert without triggering a button, you may simply remove the alert from its parent:

alert.removeFromParent( true );