uiDialog

uiDialog

Required: Aspire UI Components Standard Edition

The uiDialog control is used to create and show simple modal windows. For example, you may use this control to:

show an important message that must be acknowledged by clicking a button (an “alert” dialog);
ask a question that must be answered by selecting a button (a “confirmation” dialog); or
ask a question that must be answered by typing into an input text field (a “prompt” dialog).

Using uiDialog

The uiDialog control is a subclass of uiWindow. To use uiWindow containers in your application, you must first initialize the uiWindow class at the beginning of your application:

uiWindow.initialize(stage);

To display a uiDialog control, call the show() method passing the text to show as a parameter:

var alertDialog:uiDialog = new uiDialog();
alertDialog.show("This is the message.","Title");

Although you may create multiple instances of the uiDialog control via the new operator, it is unlikely that you would need more than one instance in your application. Therefore, it is recommended that you use a shared instance by referencing uiDialog.instance:

uiDialog.instance.show("This is the message.","Title");

Note: Calling open() (from the uiWindow class) will do nothing; you must call show() instead.

The show() method has the following signature:

show(textString, titleString, iconString, buttonsArray, promptBoolean, customSprite);

Alert Dialog

To show a simple pop-up message with a single button, call the show() method passing the text to display:

uiDialog.instance.show("This is a simple Alert Dialog.","Warning!");

NOTE: The label on the OK button is specified in the static property okLabel. Alternatively, you may specify the desired label in the buttons parameter.

Confirmation Dialog

To show a dialog with multiple buttons, call the show() method passing the labels of the buttons as an Array for the buttons parameter:

uiDialog.instance.show("Save changes to document?","Proceed?",null,["Yes","No","Cancel"]);

Prompt Dialog

To show a dialog with an input text field, call the show() method passing true for the prompt parameter:

uiDialog.instance.show("Please enter your name:", "Full Name", null, null, true);

Note: The buttons parameter is not used if the prompt parameter is set to true. For a prompt dialog, there will always be two buttons, the labels of which are specified by the static properties okLabel and cancelLabel.

(Version 1.2.6+) To pre-populate the input text field with a default value, you can set the response property after calling show():

uiDialog.instance.show("Please enter your name:", "Full Name", null, null, true);
uiDialog.instance.response = "Anonymous"; // populate the input field

Checking Response

A uiDialog control closes when a button in the control is selected, or the Escape key is pressed. As with other uiWindow instances, the uiDialog control will dispatch an Event.CLOSE event when it is closing.

The response property returns the label (text) on the button that was pressed when the dialog was last closed. If the dialog was shown with an input text field, the text in the input text field would be returned if the OK button or the ENTER key is pressed. If the instance was closed using the close button on the title bar or by pressing the Escape key, this property will return null. This property is reset to null when the show() method is called and updated before the Event.CLOSE event is dispatched so you can query this property in your listener.

Icon Source

The image to show within the uiDialog control can be specified via the icon parameter when calling the show() method.

If the parameter is null, the control will choose either of two default images to display. If there is only one button, the asset specified by the static property uiDialog.alertIcon will be used. If more than one button is displayed, the asset specified by the static property uiDialog.confirmIcon will be used.

If no image is intended, you must set the parameter to an empty string ”” instead of null.

MyDialogExample

For a live demo, please look at uiDialog Example

ActionScript 3.0 MyDialogExample class

  1: package
  2: {
  3:
  4:     import com.ghostwire.ui.containers.*;
  5:     import com.ghostwire.ui.controls.*;
  6:     import com.ghostwire.ui.data.*;
  7:     import com.ghostwire.ui.events.*;
  8:     import com.ghostwire.ui.enums.*;
  9:     import com.ghostwire.ui.managers.*;
 10:
 11:     import flash.display.Sprite;
 12:     import flash.events.*;
 13:     import flash.system.Capabilities;
 14:
 15:     public class MyDialogExample extends Sprite
 16:     {
 17:         // ** instances **
 18:         private var responseText:uiText;
 19:
 20:         public function MyDialogExample()
 21:         {
 22:             // ** make sure stage is not null **
 23:             addEventListener(Event.ADDED_TO_STAGE,init);
 24:         }
 25:
 26:         private function init(evt:Event):void
 27:         {
 28:             // ** let assets preload before starting application **
 29:             uiSkins.manager.addEventListener(Event.INIT,main);
 30:
 31:             // ** initializes uiWindow class **
 32:             uiWindow.initialize(stage);
 33:         }
 34:
 35:         private function main(evt:Event):void
 36:         {
 37:             // ** main application code **
 38:
 39:             // ** topLevelPane **
 40:             var topLevelPane:uiPane = new uiPane();
 41:             topLevelPane.padding    = 4;
 42:             topLevelPane.setSize(stage.stageWidth,stage.stageHeight);
 43:             addChild(topLevelPane);
 44:
 45:             var titleText:uiText    = new uiText("Aspire UI Components Example");
 46:             titleText.alignX        = ALIGN.CENTER;
 47:             titleText.background    = {color:0x819A98,cornerRadius:12}
 48:             titleText.padding        = "6,12";
 49:             titleText.textStyle        = "title";
 50:             topLevelPane.addChild(titleText);
 51:
 52:             var versionText:uiText    = new uiText("Flash Player Version "+Capabilities.version);
 53:             versionText.alignX        = ALIGN.CENTER;
 54:             versionText.y            = 450;
 55:             topLevelPane.addChild(versionText);
 56:
 57:             var footerText:uiText    = new uiText("© 2008-2009 GhostWire Studios")
 58:             footerText.background    = {color:0x819A98};
 59:             footerText.padding        = 3;
 60:             footerText.alignX        = ALIGN.CENTER;
 61:             footerText.fillX        = true;
 62:             footerText.textStyle    = "footer";
 63:             footerText.y            = 480;
 64:             topLevelPane.addChild(footerText);
 65:
 66:             var ghostwireMark:uiImage    = new uiImage("GhostWireStudiosMark");
 67:             ghostwireMark.alignX    = ALIGN.CENTER;
 68:             ghostwireMark.alignY    = ALIGN.BOTTOM;
 69:             topLevelPane.addChild(ghostwireMark);
 70:
 71:             var buttons:uiBox    = new uiBox();
 72:             buttons.alignX        = ALIGN.CENTER;
 73:             buttons.y            = 100;
 74:             buttons.spacing        = 20;
 75:
 76:             var winButtonA:uiLabelButton = new uiLabelButton("Dialog A");
 77:             var winButtonB:uiLabelButton = new uiLabelButton("Dialog B");
 78:             var winButtonC:uiLabelButton = new uiLabelButton("Dialog C");
 79:
 80:             winButtonA.addEventListener(MouseEvent.CLICK,on_click,false,0,true);
 81:             winButtonB.addEventListener(MouseEvent.CLICK,on_click,false,0,true);
 82:             winButtonC.addEventListener(MouseEvent.CLICK,on_click,false,0,true);
 83:
 84:             buttons.addChild(winButtonA);
 85:             buttons.addChild(winButtonB);
 86:             buttons.addChild(winButtonC);
 87:
 88:             topLevelPane.addChild(buttons);
 89:
 90:             responseText        = new uiText();
 91:             responseText.alignX = ALIGN.CENTER;
 92:             responseText.y        = 150;
 93:             topLevelPane.addChild(responseText);
 94:             // ** end topLevelPane **
 95:         }
 96:
 97:         /**
 98:         @private
 99:         */
100:         private function on_click(evt:MouseEvent):void
101:         {
102:             switch (uiLabelButton(evt.target).text)
103:             {
104:                 case "Dialog A":
105:                     uiDialog.instance.show("This is a simple Alert Dialog.","Warning!");
106:                     break;
107:                 case "Dialog B":
108:                     uiDialog.instance.show("Save changes to document?","Proceed?",null,["Yes","No","Cancel"]);
109:                     break;
110:                 case "Dialog C":
111:                     uiDialog.instance.show("Please enter your name:","Full Name",null,null,true);
112:                     break;
113:                 default:
114:                     // no default action
115:             }
116:             responseText.text = "uiDialog.instance.response property value:\n\n"+uiDialog.instance.response;
117:             uiDialog.instance.addEventListener(Event.CLOSE,on_dialogClose);
118:         }
119:
120:         /**
121:         @private
122:         */
123:         private function on_dialogClose(evt:Event):void
124:         {
125:             responseText.text = "uiDialog.instance.response property value:\n\n"+uiDialog.instance.response;
126:         }
127:         // ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
128:         // ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
129:     }
130: }

MyDialogExample.as

API Reference

For more information on the members of the com.ghostwire.ui.controls.uiDialog class, please refer to the API Reference.