Flex Basics - Creating a Popup Window with PopUpManager

Popup windows serve as a handy tool for data collection or display. Popup windows in Flex are frequently implemented as a TitleWindow or a subclass of TitleWindow. TitleWindow is a popular choice as it inherits the capabilities of a Panel (title bar, control bar, border & content area) while adding a nifty close button.



With built-in modal support, popup windows can demand the user's attention or force interaction when necessary. This is possible because windows below a modal popup window cannot receive mouse events until a modal popup window is dismissed.

The PopUpManager class is used to manage popup windows in Flex. You can create, center and remove popup windows by using the static methods of the PopUpManager class.

addPopUp()

public static function addPopUp(window:IFlexDisplayObject, parent:DisplayObject, modal:Boolean = false, childList:String = null):void

createPopUp()

public static function createPopUp(parent:DisplayObject, className:Class, modal:Boolean = false, childList:String = null):IFlexDisplayObject

centerPopUp()

public static function centerPopUp(popUp:IFlexDisplayObject):void

removePopUp()

public static function removePopUp(popUp:IFlexDisplayObject):void

Creating a popup window

Flex provides two distinct, yet very similar, methods for creating a popup window and placing it on a layer above all other visible windows – addPopUp() and createPopUp(). The difference between each method is subtle and determining which to use is mostly a matter of preference.

Note: Adobe documentation states that "using the addPopUp() method may be preferable to using the createPopUp() method if you have to pop up a simple dialog box that is never used elsewhere."

Looking closely at each method signature (addPopUp & createPopUp), the difference dictates how to use the method rather than when to use it. (or so it seems)

Method characteristic	addPopUp()	createPopUp()
Requires a popup window instance as an argument	Yes	No
Returns a value that can be stored in a variable	No	Yes

Here are some guidelines I tend to follow:

If you want to create a quick and dirty simple popup window that you don't plan to reuse, use addPopUp().

<?xml version="1.0" encoding="utf-8"?> <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"     creationComplete="openTitleWindow(event)" >     <mx:Script>         <![CDATA[             import mx.events.CloseEvent;             import mx.controls.Label;             import mx.events.FlexEvent;             import mx.containers.TitleWindow;             import mx.managers.PopUpManager;             // method to open the TitleWindow on creationComplete             private function openTitleWindow(evt:FlexEvent):void {                 // create and configure the TitleWindow                 var tw:TitleWindow = new TitleWindow();                 tw.title = "Title Goes Here";                 tw.showCloseButton = true;                 tw.addEventListener(Event.CLOSE, closeTitleWindow);                 // create and configure a Label                 var label:Label = new Label();                 label.text = "This is a very simple popup window";                 // add the Label to the TitleWindow                 tw.addChild(label);                 // open the TitleWindow as a modal popup window                 PopUpManager.addPopUp(tw, this, true);             }                          // method to close the TitleWindow targeted by a close event             private function closeTitleWindow(evt:CloseEvent):void {                 PopUpManager.removePopUp(TitleWindow(evt.target));             }         ]]>     </mx:Script>      </mx:Application>

If reuse of a popup window is a priority, use createPopUp() and store the returned object in a variable for later use.

<?xml version="1.0" encoding="utf-8"?> <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"     creationComplete="openPopUpWindow(event)" >     <mx:Script>         <![CDATA[             import comps.MyPopUpWindow;             import mx.events.FlexEvent;             import mx.managers.PopUpManager;                          // declare a variable for the reusable custom PopUp Window             private var popup:MyPopUpWindow;             // method to open the PopUp Window on creationComplete             private function openPopUpWindow(evt:FlexEvent):void {                 // open the PopUp Window as a modal popup window                 // and store it in a variable for later use                 popup = PopUpManager.createPopUp(this,MyPopUpWindow,true) as MyPopUpWindow;             }         ]]>     </mx:Script>      </mx:Application>

<?xml version="1.0" encoding="utf-8"?> <!-- custom popup window component - comps/MyPopUpWindow.mxml --> <mx:TitleWindow xmlns:mx="http://www.adobe.com/2006/mxml"          layout="vertical"          title="My Custom PopUp Window"         showCloseButton="true">                   <mx:Form>                      <mx:FormHeading label="User Login"/>                          <mx:FormItem label="Username">                 <mx:TextInput id="un"/>             </mx:FormItem>                          <mx:FormItem label="Password">                 <mx:TextInput id="pd"/>             </mx:FormItem>                          <mx:ControlBar>                 <mx:Button id="save" label="Login"/>                 <mx:Button id="cancel" label="Cancel"/>             </mx:ControlBar>                       </mx:Form>          </mx:TitleWindow>

Centering a popup window

A popup window can be centered in relation to any DisplayObject. When creating a popup window using addPopUp() or createPopUp(), it is important to understand that the parameter named "parent" (datatyped as DisplayObject) will be used to determine the reference point for centering a popup window. In most cases, you’ll want a popup window to be centered over the Application.

<?xml version="1.0" encoding="utf-8"?> <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"     creationComplete="openPopUpWindow(event)" >     <mx:Script>         <![CDATA[             import comps.MyPopUpWindow;             import mx.events.FlexEvent;             import mx.managers.PopUpManager;                          // declare a variable for the reusable custom PopUp Window             private var popup:MyPopUpWindow;             // method to open the PopUp Window on creationComplete             private function openPopUpWindow(evt:FlexEvent):void {                 // open the PopUp Window as a modal popup window                 // and store it in a variable for later use                 popup = PopUpManager.createPopUp(this,MyPopUpWindow,true) as MyPopUpWindow;                 // center the PopUp window                 PopUpManager.centerPopUp(popup);             }         ]]>     </mx:Script>      </mx:Application>

In the previous example, notice that the DisplayObject used to center the popup window was this. In this case, this refers to the Application container, and therefore, the popup window was centered nicely over the Application. In many cases this will not refer to the Application container (i.e. inside custom components). When opening a popup window from within a custom component, use the following code to ensure the popup window is centered over the Application container and not the custom component.

popup =  PopUpManager.createPopUp(DisplayObject(this.parentApplication),MyPopUpWindow,true) as MyPopUpWindow;

Removing a popup window

Once our popup window has been created, displayed and optionally centered, there are a couple of options for removing it from display.

1. A parent removes a popup window from display

<?xml version="1.0" encoding="utf-8"?> <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"     creationComplete="openPopUpWindow(event)">     <mx:Script>         <![CDATA[             import mx.events.FlexMouseEvent;             import comps.MyPopUpWindow;             import mx.events.FlexEvent;             import mx.managers.PopUpManager;                          // declare a variable for the reusable custom popup window             private var popup:MyPopUpWindow;             // method to open the popup window on creationComplete             private function openPopUpWindow(evt:FlexEvent):void {                 // open the popup window as a modal popup window                 // and store it in a variable for later use                 popup = PopUpManager.createPopUp(this,MyPopUpWindow,true) as MyPopUpWindow;                 // register event listeners for closing the popup window                 // when the popup window close button is clicked...                 popup.addEventListener(Event.CLOSE, closePopUpWindow);                 // or when an area outside the popup window is clicked...                 popup.addEventListener(FlexMouseEvent.MOUSE_DOWN_OUTSIDE, closePopUpWindow);                 // center the popup window                 PopUpManager.centerPopUp(popup);             }                          // method to close the popup window on close or mousedownoutside event             private function closePopUpWindow(evt:Event):void {                 PopUpManager.removePopUp(popup);             }         ]]>     </mx:Script>      </mx:Application>

2. A popup window removes itself from display

<?xml version="1.0" encoding="utf-8"?> <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"     creationComplete="openPopUpWindow(event)">     <mx:Script>         <![CDATA[             import mx.events.FlexMouseEvent;             import comps.MyPopUpWindow;             import mx.events.FlexEvent;             import mx.managers.PopUpManager;                          // declare a variable for the reusable custom popup window             private var popup:MyPopUpWindow;             // method to open the popup window on creationComplete             private function openPopUpWindow(evt:FlexEvent):void {                 // open the popup window as a modal popup window                 // and store it in a variable for later use                 popup = PopUpManager.createPopUp(this,MyPopUpWindow,true) as MyPopUpWindow;                 // center the popup window                 PopUpManager.centerPopUp(popup);             }         ]]>     </mx:Script>      </mx:Application>

<?xml version="1.0" encoding="utf-8"?> <!-- custom popup window component - comps/MyPopUpWindow.mxml --> <mx:TitleWindow xmlns:mx="http://www.adobe.com/2006/mxml"          layout="vertical"          title="My Custom PopUp Window"         showCloseButton="true"         close="PopUpManager.removePopUp(this)">                  <mx:Script>             <![CDATA[                 import mx.managers.PopUpManager;             ]]>         </mx:Script>                   <mx:Form>                      <mx:FormHeading label="User Login"/>                          <mx:FormItem label="Username">                 <mx:TextInput id="un"/>             </mx:FormItem>                          <mx:FormItem label="Password">                 <mx:TextInput id="pd"/>             </mx:FormItem>                          <mx:ControlBar>                 <mx:Button id="save" label="Login"/>                 <mx:Button id="cancel" label="Cancel"/>             </mx:ControlBar>                       </mx:Form>          </mx:TitleWindow>

I hope that gives you some ideas about how to use PopUpManager & TitleWindow in your Flex apps. Have fun!