Pages

December 7, 2009

Creating a Popup Window with PopUpManager

Posted by Jeremy Mitchell
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 characteristicaddPopUp()createPopUp()
Requires a popup window instance as an argumentYesNo
Returns a value that can be stored in a variableNoYes
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, thistrue);
            }
            
            // 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,trueas 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,trueas 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,trueas 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,trueas 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,trueas 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!