Friday, October 12, 2012

AdvAlert AS3 class - Download and How To Use: Part 1

In this article you'll learn how to use the Advanced Alert AS3 library.

The AdvancedAlert (AdvAlert) library is a set of classes used for creating, styling and customizing alert windows using AS3. These windows can be used for notifications/warnings/forms in all kinds of Flash/Flex/AIR applications and games.

Download the library here.

Alert windows are stackable, can be navigated through using mouse or keyboard (Tab and Enter keys).

Creating the Alert manager:

An alert manager is an object of AdvAlertManager class, which is needed to be able to spawn new alert windows.

An example of a simple alert manager (pass reference to the container and stage):

AlertManager = new AdvAlertManager(this, stage);

The constructor of this class has 11 parameters in total, only 2 of which are required. Below is the list of all the parameters for AdvAlertManager:

  • defaultWindowContainer Parent container of alert windows.
  • stage Stage reference.
  • windowSkin (Optional) Default skin for alert windows.
  • buttonSkin (Optional) Default skin for buttons in this window.
  • openSound (Optional) Default window open sound.
  • disableTab (Optional) Disable tab focusing on the parent container when an alert window is visible. This also enables tab navigation for the alert window's buttons.
  • defaultWidth (Optional) Set default width for all window alerts. 300 by default.
  • defaultHeight (Optional) Set default height for all window alerts. 0 by default. If 0, the window is auto-sized based on the text length.
  • defaultMinHeight (Optional) Set default minimal height for all window alerts. 0 by default.
  • defaultMaxHeight (Optional) Set default maximal height for all window alerts. 0 by default. If 0, automatically set to the height of the stage.
  • defaultMaxWidth (Optional) Set default maximal width for all window alerts. 0 by default. If 0, automatically set to the width of the stage.

Creating alert windows:

After AdvAlertManager object is created, you can display alerts using its alert() method.

AlertManager = new AdvAlertManager(this, stage);
AlertManager.alert("Simple message!", "Title");



The alert() method has 14 parameters, with only 2 required ones. Full list of parameters below:

  • text Text value of the alert window.
  • title Title value of the alert window.
  • buttons (Optional) Array of AdvAlertButton objects that represent buttons in the alert window.
  • defaultButton (Optional) Index of the default button (used for tab navigation).
  • closeHandler (Optional) Close handling function. Must receive a string value as parameter (which will hold the label of the button that was clicked).
  • width (Optional) Width of the alert window. If 0, set to default.
  • height (Optional) Height of the alert window. If 0, set to default. If default is 0, window will be auto sized.
  • position (Optional) Coordinates of top-left corner of the alert window. If not specified - the window is centered.
  • minHeight (Optional) The minimum height value of the alert window. If 0, set to default.
  • maxHeight (Optional) The maximum height value of the alert window. If 0, set to default.
  • maxWidth (Optional) The maximum width value of the alert window. If 0, set to default.
  • horizontalStretch (Optional) If set to true, will stretch the window horizontally if the text doesn't fit and the height has already reached maxHeight.
  • openSound (Optional) Sound to play when the window opens. Specified default sound plays by default.

Adding and handling buttons:

To add custom buttons to an alert window, simply pass an array of AdvAlertButton objects as the third parameter of alert() method:

AlertManager.alert("Simple message!", "Title", [new AdvAlertButton("OK"), new AdvAlertButton("Cancel")]);

The user can press a button and close the window using Enter key. To set which button is pressed, if the user hits Enter and hasn't changed button focus with Tab before, set the value of the 4th parameter.

AlertManager.alert("Simple message!", "Title", [new AdvAlertButton("OK"), new AdvAlertButton("Cancel")], 0);

To add a button listener, create a function which receives a string value as parameter and refer to it in the 5th parameter of the alert() function. The function will return the string value of the label of the button that was pressed.

private function init(evt:Event):void {
AlertManager = new AdvAlertManager(this, stage);
AlertManager.alert("Simple message!", "Title",
[new AdvAlertButton("OK"), new AdvAlertButton("Cancel")],
0, onClose);
}

private function onClose(btn:String):void {
trace(btn);
}



Keyboard navigation:

By default, the user is able to navigate through all window buttons using Tab and Enter. Moreover, all other buttons in the application are unfocusable if at least 1 alert window is displayed. To disable this feature, set disableTab parameter of the AdvAlertManager object to false:

AlertManager = new AdvAlertManager(this, stage, null, null, null, false);

Closing the last window:

It is possible to close the top alert window that is currently visible using closeLast() method of AdvAlertManager:

AlertManager.closeLast();

Reconfiguring the manager:

You can reset all the manager parameters by calling a function called reset(), which has the same parameters as the constructor of the class:

AlertManager.reset(this, stage, null, null, null, false);

In the next part, I'll show you how to skin and further customize alert windows.

Thanks for reading!

No comments:

Post a Comment