A TitleWindow layout container is a Panel container that is optimized for use as a pop-up window. The container consists of a title bar, a caption and status area in the title bar, a border, and a content area for its children. Unlike the Panel container, it can display a Close button, and is designed to work as a pop-up window that users can drag around the screen the application window.

A pop-up TitleWindow container can be modal, which means that it takes all keyboard and mouse input until it is closed, or nonmodal, which means other windows can accept input while the pop-up window is still open.

One typical use for a TitleWindow container is to hold a form. When the user completes the form, you can close the TitleWindow container programmatically, or let the user request the application to close it by using the close icon (a box with an x inside it) in the upper-right corner of the window.

Because you pop up a Title window, you do not create it directly in MXML, as you do most controls; instead you use the PopUpManager.

The following example shows a TitleWindow container with a Form container as its child:

For complete reference information, see TitleWindow in the Adobe Flex Language Reference.

Using the PopUpManager to create a TitleWindow container

To create and remove a pop-up TitleWindow container, you use methods of the PopUpManager. The PopUpManager is in the mx.managers package.

Creating a pop-up window

To create a pop-up window, use the PopUpManager createPopUp() method. The createPopUp() method has the following signature:

public static createPopUp(parent:DisplayObject, class:Class,
    modal:Boolean = false):IFlexDisplayObject

The method has the following arguments.

You can also create a pop-up window by passing an instance of a TitleWindow class or custom component to the PopUpManager addPopUp() method. For more information, see Using the addPopUp() method.

Defining a custom TitleWindow component

One of the most common ways of creating a TitleWindow container is to define it as a custom MXML component.

• You define the TitleWindow container, its event handlers, and all of its children in the custom component.
• You use the PopUpManager createPopUp() and removePopUp() methods to create and remove the TitleWindow container.

The following example code defines a custom MyLoginForm TitleWindow component that is used as a pop-up window:

<?xml version="1.0"?>
<!-- containers\layouts\myComponents\MyLoginForm.mxml -->
<mx:TitleWindow xmlns:mx="http://www.adobe.com/2006/mxml">
    
    <mx:Script>
        <![CDATA[
            import mx.managers.PopUpManager;
            
            private function processLogin():void {
                // Check credentials (not shown) then remove pop up.
                PopUpManager.removePopUp(this);
            }
        ]]>
    </mx:Script>

    <mx:Form>
        <mx:FormItem label="User Name">
            <mx:TextInput id="username" width="100%"/>
        </mx:FormItem> 
        <mx:FormItem label="Password">
            <mx:TextInput id="password" 
                displayAsPassword="true" 
                width="100%"/>
        </mx:FormItem> 
    </mx:Form>
    <mx:HBox> 
        <mx:Button click="processLogin();" label="OK"/> 
        <mx:Button 
            label="Cancel"
            click="PopUpManager.removePopUp(this);"/> 
    </mx:HBox> 
</mx:TitleWindow>

This file, named MyLoginForm.mxml, defines a TitleWindow container by using the <mx:TitleWindow> tag. The TitleWindow container defines two TextInput controls, for user name and password, and two Button controls, for submitting the form and for closing the TitleWindow container. This example does not include the code for verifying the user name and password in the submitForm() event listener.

In this example, you process the form data in an event listener of the MyLoginForm.mxml component. To make this component more reusable, you can define the event listeners in your main application. This lets you create a generic form that leaves the data handling to the application that uses the form. For an example that defines the event listeners in the main application, see Using TitleWindow and PopUpManager events.

Using the PopUpManager to create the pop-up TitleWindow

To create a pop-up window, you call the PopUpManager createPopUp() method and pass it the parent, the name of the class that creates the pop-up, and the modal Boolean value. The following main application code creates the TitleWindow container defined in Defining a custom TitleWindow component:

<?xml version="1.0"?>
<!-- containers\layouts\MainMyLoginForm.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            import mx.managers.PopUpManager;
            import mx.core.IFlexDisplayObject;
            import myComponents.MyLoginForm;

            private function showLogin():void {
                // Create a non-modal TitleWindow container.
                var helpWindow:IFlexDisplayObject =
                    PopUpManager.createPopUp(this, MyLoginForm, false);
            }
        ]]>
    </mx:Script>
    
    <mx:VBox width="300" height="300">  
        <mx:Button click="showLogin();" label="Login"/>
    </mx:VBox>
</mx:Application>
The executing SWF file for the previous example is shown below:

In this example, when the user selects the Login button, the event listener for the click event uses the createPopUp() method to create a TitleWindow container, passing to it the name of the MyLoginForm.mxml file as the class name.

Often, you cast the return value of the createPopUp() method to TitleWindow so that you can manipulate the properties of the pop-up TitleWindow container, as the following version of the showLogin() method from the preceding example shows:

<?xml version="1.0"?>
<!-- containers\layouts\MainMyLoginFormCast.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
          import mx.managers.PopUpManager;
          import mx.core.IFlexDisplayObject;
          import myComponents.MyLoginForm;

          // Additional import statement to use the TitleWindow container.
          import mx.containers.TitleWindow;

          private function showLogin():void {
            // Create the TitleWindow container.
            var helpWindow:TitleWindow = 
          TitleWindow(PopUpManager.createPopUp(this, MyLoginForm, false));

            // Add title to the title bar.
            helpWindow.title="Enter Login Information";

            // Make title bar slightly transparent.
            helpWindow.setStyle("borderAlpha", 0.9);

            // Add a close button.
            // To close the container, your must also handle the close event.
            helpWindow.showCloseButton=true;
          }
        ]]>
    </mx:Script>
    
    <mx:VBox width="300" height="300">  
        <mx:Button click="showLogin();" label="Login"/>
    </mx:VBox>
</mx:Application>
The executing SWF file for the previous example is shown below:

Removing a pop-up window

To remove a pop-up TitleWindow, use the PopUpManager removePopUp() method. You pass the object created with the PopUpManager.createPopUp() method to the removePopUp() method. The following modification to the example from Using the PopUpManager to create the pop-up TitleWindow removes the pop-up when the user clicks the Done button:

<?xml version="1.0"?>
<!-- containers\layouts\MainMyLoginFormRemove.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
          import mx.managers.PopUpManager;
          import myComponents.MyLoginForm;
          import mx.core.IFlexDisplayObject;

          private var helpWindow:IFlexDisplayObject;

          private function showLogin():void {
            // Create the TitleWindow container.
            helpWindow = PopUpManager.createPopUp(this, MyLoginForm, false);
          }

          private function removeForm():void {
            PopUpManager.removePopUp(helpWindow);
          }
        ]]>
    </mx:Script>
    
    <mx:VBox width="300" height="300">  
        <mx:Button click="showLogin();" label="Login"/>
        <mx:Button id="b2" label="Remove Form" click="removeForm();"/>
    </mx:VBox>
</mx:Application>
The executing SWF file for the previous example is shown below:

You commonly call the removePopUp() method from a TitleWindow close event and the PopUpManager mouseDownOutside event, as described in Passing data using events.

Using TitleWindow and PopUpManager events

You can add a close icon (a small x in the upper-right corner of the TitleWindow title bar) to make it appear similar to dialog boxes in a GUI environment. You do this by setting the showCloseButton property to true, as the following example shows:

<mx:TitleWindow xmlns:mx="http://www.adobe.com/2006/mxml" showCloseButton="true">

The default value for showCloseButton is false.

The TitleWindow broadcasts a close event when the user clicks the close icon. You must create a handler for that event and close the TitleWindow from within that event handler. Flex does not close the window automatically.

In the simplest case, you can call the PopUpManager removePopUp() method directly in the TitleWindow close event property specify, as the following line shows:

<mx:TitleWindow xmlns:mx="http://www.adobe.com/2006/mxml"showCloseButton="true" 
    close="PopUpManager.removePopUp(this);">

If you need to clean up, before closing the TitleWindow control, create an event listener function for the close event and close the TitleWindow from within that handler, as the following example shows:

<?xml version="1.0"?>
<!-- containers\layouts\myComponents\MyLoginFormRemoveMe.mxml -->
<mx:TitleWindow xmlns:mx="http://www.adobe.com/2006/mxml" 
    showCloseButton="true" 
    close="removeMe();">

    <mx:Script>
        <![CDATA[
            import mx.managers.PopUpManager;

            private function removeMe():void {
                // Put any clean-up code here.
                PopUpManager.removePopUp(this);
            }
        ]]>
    </mx:Script>

</mx:TitleWindow>

You can also use the PopUpManager mouseDownOutside event to close the pop-up window when a user clicks the mouse outside the TitleWindow. To do this, you add an event listener to the TitleWindow instance for the mouseDownOutside event, as the following example shows:

<?xml version="1.0"?>
<!-- containers\layouts\MainMyLoginFormMouseDown.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            import mx.managers.PopUpManager;
            import mx.containers.TitleWindow;
            import myComponents.MyLoginForm;
            import mx.events.FlexMouseEvent;

            private var helpWindow:TitleWindow;

            private function showLogin():void {
                // Create the TitleWindow container.
                helpWindow = TitleWindow(PopUpManager.createPopUp(this,
                    MyLoginForm, false));
                helpWindow.addEventListener("mouseDownOutside", removeForm);
            }

            private function removeForm(event:FlexMouseEvent):void {
                PopUpManager.removePopUp(helpWindow);
            }
        ]]>
    </mx:Script>
    
    <mx:VBox width="300" height="300">  
        <mx:Button click="showLogin();" label="Login"/>
    </mx:VBox>
</mx:Application>
The executing SWF file for the previous example is shown below:

You define the event listener in the main application, and then assign it to the pop-up window when you create it. This technique lets you use a generic pop-up window, defined by the component MyLoginForm.mxml, and then modify the behavior of the component by assigning event listeners to it from the main application.

Centering a pop-up window

Call the centerPopUp() method of the PopUpManager to center the pop-up within another container. The following custom MXML component centers itself in its parent container:

<?xml version="1.0"?>
<!-- containers\layouts\myComponents\MyLoginFormCenter.mxml -->
<mx:TitleWindow xmlns:mx="http://www.adobe.com/2006/mxml" 
    creationComplete="handleCreationComplete();">
    
    <mx:Script>
        <![CDATA[
            import mx.managers.PopUpManager;
            
            private function handleCreationComplete():void {
                // Center the TitleWindow container 
                // over the control that created it.
                PopUpManager.centerPopUp(this);
            }
            
            private function processLogin():void {
                // Check credentials (not shown) then remove pop up.
                PopUpManager.removePopUp(this);
            }
        ]]>
    </mx:Script>
    <mx:Form>
        <mx:FormItem label="User Name">
            <mx:TextInput id="username" width="100%"/>
        </mx:FormItem> 
        <mx:FormItem label="Password">
            <mx:TextInput id="password" 
                width="100%"
                displayAsPassword="true"/>
        </mx:FormItem> 
    </mx:Form>
    <mx:HBox> 
        <mx:Button click="processLogin();" label="OK"/> 
        <mx:Button 
            label="Cancel"
            click="PopUpManager.removePopUp(this);"/> 
    </mx:HBox> 
</mx:TitleWindow>

Creating a modal pop-up window

The createPopUp() method takes an optional modal parameter. You can set this parameter to true to make the window modal. When a TitleWindow is modal, you cannot select any other component while the window is open. The default value of modal is false.

The following example creates a modal pop-up window:

var pop1:IFlexDisplayObject = PopUpManager.createPopUp(this, MyLoginForm,
    true);

Passing data to and from a pop-up window

To make your pop-up window more flexible, you might want to pass data to it or return data from it. To do this, use the following guidelines:

• Create a custom component to be your pop-up. In most circumstances, this component is a TitleWindow container.
• Declare variables in your pop-up that you will set in the application that creates the pop-up.
• Cast the pop-up to be the same type as your custom component.
• Pass a reference to that component to the pop-up window, if the pop-up window is to set a value on the application or one of the application's components.

For example, the following application populates a ComboBox in the pop-up window with an Array defined in the main application.

When creating the pop-up, the application casts the pop-up to be of type ArrayEntryForm, which is the name of the custom component that defines the pop-up window. If you do not do this, the application cannot access the properties that you create.

The application passes a reference to the TextInput component in the Application container to the pop-up window so that the pop-up can write its results back to the container. The application also passes the Array of file extensions for the pop-up ComboBox control's data provider, and sets the pop-up window's title. By setting these in the application, you can reuse the pop-up window in other parts of the application without modification, because it does not have to know the name of the component it is writing back to or the data that it is displaying, only that its data is in an Array and it is writing to a TextArea.

<?xml version="1.0"?>
<!-- containers\layouts\MainArrayEntryForm.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            import mx.managers.PopUpManager;
            import myComponents.ArrayEntryForm;
            
            public var helpWindow:Object;
    
            public function displayForm():void {
                /* Array with data for the custom control ComboBox control. */
                var doctypes:Array = ["*.as", "*.mxml", "*.swc"]
                
                /* Create the pop-up and cast the 
                   return value of the createPopUp()
                   method to the ArrayEntryForm custom component. */
                var pop1:ArrayEntryForm = ArrayEntryForm(
                    PopUpManager.createPopUp(this, ArrayEntryForm, true));
                
                /* Set TitleWindow properties. */
                pop1.title="Select File Type";
                pop1.showCloseButton=true;
    
                /* Set properties of the ArrayEntryForm custom component. */
                pop1.targetComponent = ti1;
                pop1.myArray = doctypes;
                PopUpManager.centerPopUp(pop1);
            }
        ]]>
    </mx:Script>

    <mx:TextInput id="ti1" text=""/>
    <mx:Button id="b1" label="Select File Type" click="displayForm();"/>
</mx:Application>
The executing SWF file for the previous example is shown below:

The following custom component, ArrayEntryForm.mxml, declares two variables. The first one is for the Array that the parent application passes to the pop-up window. The second holds a reference to the parent application's TextInput control. The component uses that reference to update the parent application:

<?xml version="1.0"?>
<!-- containers\layouts\myComponents\ArrayEntryForm.mxml -->
<mx:TitleWindow xmlns:mx="http://www.adobe.com/2006/mxml"
        showCloseButton="true" 
        width="200" borderAlpha="1"
        close="removeMe();">
 
    <mx:Script>
        <![CDATA[
            import mx.controls.TextInput;
            import mx.managers.PopUpManager;
            
            // Variables whose values are set by the main application.
            // Data provider array for the component's ComboBox control.
            [Bindable]
            public var myArray:Array;
            // A reference to the TextInput control 
            // in which to put the result.
            public var targetComponent:TextInput;

            // OK button click event listener.
            // Sets the target component in the application to the 
            // selected ComboBox item value.
            private function submitData():void {
                targetComponent.text = String(cb1.selectedItem);
                removeMe();
            }

            // Cancel button click event listener.
            private function removeMe():void {
                PopUpManager.removePopUp(this);
            }
        ]]>
    </mx:Script>

    <mx:ComboBox id="cb1" dataProvider="{myArray}"/>
    <mx:HBox>
        <mx:Button label="OK" click="submitData();"/>
        <mx:Button label="Cancel" click="removeMe();"/>
    </mx:HBox>
</mx:TitleWindow> 

From within a pop-up custom component, you can also access properties of the parent application by using the parentApplication property. For example, if the application has a Button control named b1, you can get the label of that Button control, as the following example shows:

myLabel = parentApplication.b1.label;

This technique, however, uses a hard-coded value in the pop-up component for both the target component id in the parent and the property in the component.

Passing data using events

The following example modifies the example from the previous section to use event listeners defined in the main application to handle the passing of data back from the pop-up window to the main application. This example shows the ArrayEntryFormEvents.mxml file with no event listeners defined within it.

<?xml version="1.0"?>
<!-- containers\layouts\myComponents\ArrayEntryFormEvents.mxml -->
<mx:TitleWindow xmlns:mx="http://www.adobe.com/2006/mxml"
    showCloseButton="true" 
    width="200" 
    borderAlpha="1">
 
    <mx:Script>
        <![CDATA[
            import mx.managers.PopUpManager;
            
            // Variables whose values are set by the main application.
            // Data provider array for the component's ComboBox control.
            [Bindable]
            public var myArray:Array;

        ]]>
    </mx:Script>

    <mx:ComboBox id="cb1" dataProvider="{myArray}"/>
    <mx:HBox>
        <mx:Button id="okButton" label="OK"/>
        <mx:Button id="cancelButton" label="Cancel"/>
    </mx:HBox>
</mx:TitleWindow> 

The main application defines the event listeners and registers them with the controls defined within the pop-up window:

<?xml version="1.0"?>
<!-- containers\layouts\MainArrayEntryFormEvents.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            import mx.managers.PopUpManager;
            import flash.events.Event;
            import myComponents.ArrayEntryFormEvents;
            
            public var pop1:ArrayEntryFormEvents; 
    
            public function displayForm():void {
                // Array with data for the custom control ComboBox control.
                var doctypes:Array = ["*.as", "*.mxml", "*.swc"]
                
                // Create the pop-up and cast the return value 
                // of the createPopUp()
                // method to the ArrayEntryFormEvents custom component.
                pop1 = ArrayEntryFormEvents(
              PopUpManager.createPopUp(this, ArrayEntryFormEvents, true));
                // Set TitleWindow properties.
                pop1.title="Select File Type";
                pop1.showCloseButton=true;
    
                // Set the event listeners for 
                // the ArrayEntryFormEvents component.
                pop1.addEventListener("close", removeMe);
                pop1["cancelButton"].addEventListener("click", removeMe);   
                pop1["okButton"].addEventListener("click", submitData); 
    
                // Set properties of the ArrayEntryFormEvents custom control.
                pop1.myArray = doctypes;
                PopUpManager.centerPopUp(pop1);
            }
            
            // OK button click event listener.
            // Sets the target component in the application to the 
            // selected ComboBox item value.
            private function submitData(event:Event):void {
                ti1.text = String(pop1.cb1.selectedItem);
                removeMe(event);
            }

            // Cancel button click event listener.
            private function removeMe(event:Event):void {
                PopUpManager.removePopUp(pop1);
            }           
        ]]>
    </mx:Script>

    <mx:VBox> 
        <mx:TextInput id="ti1" text=""/>
    </mx:VBox>
    <mx:Button id="b1" label="Select File Type" click="displayForm();"/>
</mx:Application>
The executing SWF file for the previous example is shown below:

Using the addPopUp() method

You can use the addPopUp() method of the PopUpManager to create a pop-up window without defining a custom component. This method takes an instance of any class that implements IFlexDisplayObject. Because it takes a class instance, not a class, you can use ActionScript code in an <mx:Script> block to create the component instance to pop up, rather than as a separate custom component.

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 reused elsewhere. However, it is not the best coding practice if the pop-up is complex or cannot be reused elsewhere.

The following example creates a pop-up with addPopUp() method and adds a Button control to that window that closes the window when you click it:

<?xml version="1.0"?>
<!-- containers\layouts\MyPopUpButton.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    height="600" width="600" >

    <mx:Script>
        <![CDATA[
            import mx.containers.TitleWindow;
            import flash.events.*;
            import mx.managers.PopUpManager;
            import mx.controls.Button;
            import mx.core.IFlexDisplayObject;
            
            // The variable for the TitleWindow container
            public var myTitleWindow:TitleWindow = new TitleWindow();

            // Method to instantiate and display a TitleWindow container.
            // This is the initial Button control's click event handler.
            public function openWindow(event:MouseEvent):void {
                // Set the TitleWindow container properties.
                myTitleWindow = new TitleWindow();
                myTitleWindow.title = "My Window Title";
                myTitleWindow.width= 220;
                myTitleWindow.height= 150;
                // Call the method to add the Button control to the 
                // TitleWindow container.
                populateWindow();
                // Use the PopUpManager to display the TitleWindow container.
                PopUpManager.addPopUp(myTitleWindow, this, true);
            }
        
            // The method to create and add the Button child control to the
            // TitleWindow container.
            public function populateWindow():void {
                var btn1:Button = new Button();
                btn1.label="close";
                btn1.addEventListener(MouseEvent.CLICK, closeTitleWindow);
                myTitleWindow.addChild(btn1);   
            }
            
            // The method to close the TitleWindow container.
            public function closeTitleWindow(event:MouseEvent):void {
                PopUpManager.removePopUp(event.currentTarget.parent);
            }
        ]]>
    </mx:Script>
    <mx:Button label="Open Window" click="openWindow(event);"/>
</mx:Application>
The executing SWF file for the previous example is shown below:

You can make any component pop up. The following example pops up a TextArea control. The example resizes the control, and listens for a Shift-click to determine when to close the TextArea. Whatever text you type in the TextArea is stored in a Label control in the application when the pop-up window is removed.

<?xml version="1.0"?>
<!-- containers\layouts\MyPopUpTextArea.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            import mx.managers.PopUpManager;
            import mx.controls.TextArea;
            import mx.core.IFlexDisplayObject;
 
            public var myPopUp:TextArea
            
            public function openWindow(event:MouseEvent):void {
                myPopUp = new TextArea();
                myPopUp.width= 220;
                myPopUp.height= 150;
                myPopUp.text = "Hold down the Shift key, and " + 
                    "click in the TextArea to close it.";
                myPopUp.addEventListener(MouseEvent.CLICK, closeWindow);
                PopUpManager.addPopUp(myPopUp, this, true);
                PopUpManager.centerPopUp(myPopUp);
            }
    
            public function closeWindow(event:MouseEvent):void {
                if (event.shiftKey) {
                    label1.text = myPopUp.text;
        PopUpManager.removePopUp(IFlexDisplayObject(event.currentTarget));
                }
            }
        ]]>
    </mx:Script>

    <mx:VBox>
        <mx:Button id="b1" label="Create TextArea Popup"
            click="openWindow(event);"/>
        <mx:Label id="label1"/>
    </mx:VBox>
</mx:Application>
The executing SWF file for the previous example is shown below: