Packagecom.ghostwire.ui.controls
Classpublic class uiDialog
InheritanceuiDialog Inheritance uiWindow Inheritance uiComponent Inheritance flash.display.Sprite

The uiDialog class is used to create and show simple modal windows. This is typically used to show important messages that end-users must acknowledge by clicking a button, or questions that they must answer by selecting a button (from two or more buttons), before the application may continue.

The uiDialog control is a subclass of the uiWindow container. To use uiWindow containers in your application, you must 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() will do nothing; you must call show() instead.

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, or null if the Escape key was pressed to close the dialog. 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.

~ This class is available in Aspire UI Components Standard Edition ~

See also

com.ghostwire.ui.containers.uiWindow.initialize()


Public Properties
 PropertyDefined by
  alertIcon : String = "icons/alert_32"
[static] Indicates the default image source if only one button is displayed in the control.
uiDialog
 InheritedalignX : Number
Indicates how the component would like to be aligned horizontally within its allocated space.
uiComponent
 InheritedalignY : Number
Indicates how the component would like to be aligned vertically within its allocated space.
uiComponent
 InheritedalwaysOnTop : Boolean
Indicates if this uiWindow instance is always on top of other sibling uiWindow instances.
uiWindow
 Inheritedbackground : Object
Indicates the style of the background for this component.
uiComponent
  cancelLabel : String = "Cancel"
[static] Indicates the default label for the Cancel button.
uiDialog
  confirmIcon : String = "icons/confirm_32"
[static] Indicates the default image source if more than one button is displayed in the control.
uiDialog
 Inheritedcontainer : uiComponent
Indicates the uiComponent instance that contains this instance.
uiComponent
 Inheritedcontent : uiForm
Returns the uiForm instance that is used as the content container.
uiWindow
 InheritedcontentPadding : Object
Indicates the padding to apply to the content (uiForm child).
uiWindow
 Inheriteddepth : int
Indicates how deep the component is in the containment hierarchy.
uiComponent
 InheriteddesiredAllocationHeight : int
Indicates the vertical space this component would like to be allocated.
uiComponent
 InheriteddesiredAllocationWidth : int
Indicates the horizontal space this component would like to be allocated.
uiComponent
 Inheritedenabled : Boolean
Indicates whether the component is enabled for user interaction.
uiComponent
 InheritedfillX : Boolean
Indicates whether or not the component should automatically expand or shrink to fill its allocated horizontal space.
uiComponent
 InheritedfillY : Boolean
Indicates whether or not the component should automatically expand or shrink to fill its allocated vertical space.
uiComponent
 InheritedfocusPadding : Object
Indicates the thickness of the interior space from the edge of the component to the focus rectangle.
uiComponent
 InheritedfocusRect : Object
Indicates the class to use when rendering the rectangle around the component to indicate that it is in focus.
uiComponent
 Inheritedheight : Number
Indicates the current height of the component.
uiComponent
 Inheritedicon : String
Indicates the source of the image to display in the title bar of this uiWindow instance.
uiWindow
  instance : uiDialog
[static][read-only] Returns a shared instance of the uiDialog control.
uiDialog
 InheritedliveDragging : Boolean
Indicates whether the uiWindow instance should resize itself (and its contents) immediately when the end-user drags the edges of the window.
uiWindow
 Inheritedmargin : Object
Indicates the thickness of the space surrounding the component.
uiComponent
 InheritedmaxHeight : int
Indicates the upper limit for height.
uiComponent
 Inheritedmaximized : Boolean
Indicates whether this uiWindow instance is currently maximized.
uiWindow
 InheritedmaxWidth : int
Indicates the upper limit for width.
uiComponent
 InheritedmenuModel : uiModel
Indicates the uiModel object to use to populate the menu bar of this uiWindow instance.
uiWindow
 InheritedminHeight : int
Indicates the lower limit for height.
uiComponent
 Inheritedminimized : Boolean
Indicates whether this uiWindow instance is currently minimized/collapsed.
uiWindow
 InheritedminWidth : int
Indicates the lower limit for width.
uiComponent
 InheritedmodalAlpha : Number
[static] Indicates the transparency level of the background when a modal window is displayed.
uiWindow
 InheritedmodalColor : Number
[static] Indicates the color of the background when a modal window is displayed.
uiWindow
 Inheritedmode : int
Indicates whether the uiWindow instance is modal and/or can be closed, maximized, minimized or resized by end-users.
uiWindow
  okLabel : String = "OK"
[static] Indicates the default label for the OK button.
uiDialog
 Inheritedowner : uiWindow
Indicates the parent uiWindow instance.
uiWindow
 Inheritedpadding : Object
Indicates the thickness of the interior space from the edge of the component to the content area, which is where child components, if any, are contained.
uiComponent
  response : String
Indicates the label (text) on the button that was pressed when the dialog was last closed.
uiDialog
 Inheritedskin : String
Indicates the name of the skin to use for this component instance.
uiComponent
 Inheritedstatus : Object
Indicates the text to display in the status bar of this uiWindow instance.
uiWindow
 Inheritedstretch : Boolean
Indicates whether surplus space available in the parent container should be allocated to this component.
uiComponent
 InheritedtextStyle : String
Indicates the style to use for uiText instances contained in this component.
uiComponent
 Inheritedtitle : String
Indicates the text to display in the title bar of this uiWindow instance.
uiWindow
 InheritedtoolTip : Object
Indicates the content (text) of the tooltip that should be shown when the mouse hovers over this control.
uiComponent
 Inheriteduimenubar : uiMenuBar
Returns the embedded uiMenuBar instance, if any - for advanced users only.
uiWindow
 Inheriteduiskin : uiBitmapImage
Returns the uiBitmapImage rendered as the skin - for advanced users only.
uiComponent
 Inheritedvisible : Boolean
Indicates whether or not the component is visible within its container.
uiComponent
 Inheritedwidth : Number
Indicates the current width of the component.
uiComponent
Public Methods
 MethodDefined by
 Inherited
close():Boolean
Closes this uiWindow instance (and its child windows if any).
uiWindow
 Inherited
getWindow(child:DisplayObject):uiWindow
[static] Returns a reference to the uiWindow container within which the specified child is contained.
uiWindow
 Inherited
initialize(stage:Stage):void
[static] Initializes the uiWindow class, registering the stage of the document (so that we know where to place the windows).
uiWindow
 Inherited
invalidate(type:String):void
Invalidates this component's "size", "display", "layout" or "textstyle".
uiComponent
 Inherited
move(x:Number, y:Number, noEvent:Boolean = false):void
Moves the component to the specified position, disregarding its allocation.
uiComponent
 Inherited
open(x:int = -1, y:int = -1):void
Opens this uiWindow instance, making it the current active window, giving it focus and bringing it to the front of its peer windows (if any).
uiWindow
 Inherited
removeAllChildren(all:Boolean = false):void
Removes all children from this component.
uiComponent
 Inherited
setFocus(flag:Boolean = true):void
Gives this component instance the focus; the component must be on the display list and has its tabEnabled property set to true, otherwise this method will fail silently.
uiComponent
 Inherited
setSize(width:Number, height:Number, noEvent:Boolean = false):void
Sets this component's size to the specified width and height.
uiComponent
 Inherited
setVisible(value:Boolean, noEvent:Boolean = false):void
Sets the visibility of this component instance, dispatching a "show" or "hide" event accordingly.
uiComponent
  
show(text:String = "", title:String = "", icon:String = null, buttons:Array = null, prompt:Boolean = false, custom:Sprite = null):void
Shows the uiDialog control with the specified message text.
uiDialog
 Inherited
validateNow():void
Validates and render the component instance, and any component instances with depth higher than itself in the validation queue, immediately.
uiComponent
Events
 EventSummaryDefined by
 Inherited Dispatched when the uiWindow container is about to be closed.uiWindow
 Inherited Dispatched when the component's visible property is changed from true to false via calling the setVisible() method.uiComponent
 Inherited Dispatched when the end-user selects an enabled menu item from the menu bar.uiWindow
 Inherited Dispatched when the component's position within its parent container has changed via calling the move() method.uiComponent
 Inherited Dispatched when the uiWindow container is opened.uiWindow
 Inherited Dispatched when the component's size has changed via calling the setSize() method.uiComponent
 Inherited Dispatched when the component's visible property is changed from false to true via calling the setVisible() method.uiComponent
Property detail
alertIconproperty
public static var alertIcon:String = "icons/alert_32"

Indicates the default image source if only one button is displayed in the control.

cancelLabelproperty 
public static var cancelLabel:String = "Cancel"

Indicates the default label for the Cancel button.

confirmIconproperty 
public static var confirmIcon:String = "icons/confirm_32"

Indicates the default image source if more than one button is displayed in the control.

instanceproperty 
instance:uiDialog  [read-only]

Returns a shared instance of the uiDialog control. As you are likely to need only one instance of the uiDialog control, it is recommended that you use this shared instance instead of creating multiple instances of the uiDialog class via the new operator.

Implementation
    public static function get instance():uiDialog
okLabelproperty 
public static var okLabel:String = "OK"

Indicates the default label for the OK button.

responseproperty 
response:String  [read-write]

Indicates 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 instead. 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.

Implementation
    public function get response():String
    public function set response(value:String):void
Method detail
show()method
public function show(text:String = "", title:String = "", icon:String = null, buttons:Array = null, prompt:Boolean = false, custom:Sprite = null):void

Shows the uiDialog control with the specified message text.

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.

Parameters
text:String (default = "") — A String indicating the message text to display in the control.
 
title:String (default = "") — A String indicating the text to display in the title bar.
 
icon:String (default = null) — A String indicating the source to the image to show in the control, on the left of the message text. If undefined, the value indicated by static property uiDialog.alertIcon will be used if there is only one button, or the value indicated by static property uiDialog.confirmIcon will be used if there is more than one button. Set this parameter to an empty String "" if no image is intended.
 
buttons:Array (default = null) — An Array of String values indicating the label (text) to display on the buttons. Corresponding, this also determines how many buttons are displayed. If undefined, a single button with the label indicated by the static property uiDialog.okLabel is shown. Pressing any of the buttons closes the dialog and the label of the button pressed is stored in the control's response property. This parameter is ignored if the prompt parameter is true.
 
prompt:Boolean (default = false) — A Boolean value. If true, the dialog will be shown with the specified message text along with an input text field positioned below the message. There will also be two buttons - OK and Cancel - positioned to the right of the message. The labels on these buttons are taken from the static properties uiDialog.okLabel and uiDialog.cancelLabel respectively. The buttons parameter is ignored if prompt is true. When the dialog is closed, the response property will return the text in the input text field if the dialog is closed by clicking the OK button or pressing the ENTER key (otherwise, the response property returns null).
 
custom:Sprite (default = null) — A Sprite instance to be displayed within the dialog in-lieu of the usual text and icon. If you set this custom content, the text and icon parameters will be ignored. If the custom content contains its own uiPushButton instances and you do not want to use the built-in buttons, you have to set the buttons paramater to an empty Array (not null value, but an empty Array).