The PopUpButton control consists of two horizontal buttons: a main button, and a smaller button called the pop-up button, which only has an icon. The main button is a Button control.

The pop-up button, when clicked, opens a second control called the pop-up control. Clicking anywhere outside the PopUpButton control, or in the pop-up control, closes the pop-up control

The PopUpButton control adds a flexible pop-up control interface to a Button control. One common use for the PopUpButton control is to have the pop-up button open a List control or a Menu control that changes the function and label of the main button, as the following example shows by using a Menu control:

In this example, the user can choose whether the button puts mail in the Inbox, the Sent Items folder, or the Trash folder, by selecting from the pop-up menu that appears when the user clicks the small pop-up button to the right of the main button. The text on the main button indicates the action it performs, and the text changes each time the user selects a different item from the menu.

The PopUpButton control is not limited to displaying menus; it can display any Flex control as the pop-up control. A workflow application that lets users send a document for review, for example, could use a Tree control as a visual indication of departmental structure. The PopUpButton control's pop-up button would display the tree, from which the user could pick the message recipients.

The control that pops up does not have to affect the main button's appearance or action; it can have an independent action instead. You could create an undo PopUpButton control, for example, where the main button undoes only the last action, and the pop-up control is a List control that lets users undo multiple actions by selecting them.

The PopUpButton control is a subclass of the Button control and inherits all of its properties, styles, events, and methods, with the exception of the toggle property and the styles used for a selected button.

The control has the following characteristics:

• The popUp property specifies the pop-up control (for example, List or Menu).
• The open() and close() methods lets you open and close the pop-up control programmatically, rather than by using the pop-up button.
• The open and close events are dispatched when the pop-up control opens and closes.
• You use the popUpSkin and arrowButtonWidth style properties to define the PopUpButton control's appearance.

For detailed descriptions, see PopUpButton in Adobe Flex Language Reference.

Creating a PopUpButton control

You use the <mx:PopUpButton> tag to define aPopUpButton control in MXML, as the following example shows. Specify an id value if you intend to refer to a component elsewhere in your MXML, either in another tag or in an ActionScript block.

In the following example, you use the PopUpButton control to open a Menu control. Once opened, the Menu control, or any pop-up control, functions just as it would normally. You define an event listener for the Menu control's change event to recognize when the user selects a menu item, as the following example shows:

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

    <mx:Script>
        <![CDATA[
            import mx.controls.*;
            import mx.events.*;

            private var myMenu:Menu;

            // Initialize the Menu control, 
            // and specify it as the pop up object
            // of the PopUpButton control. 
            private function initMenu():void {
                myMenu = new Menu();
                var dp:Object = [
                  {label: "New Folder"}, 
                  {label: "Sent Items"}, 
                  {label: "Inbox"}
                ];        
                myMenu.dataProvider = dp;
                myMenu.addEventListener("itemClick", changeHandler);
                popB.popUp = myMenu;
            }

            // Define the event listener for the Menu control's change event. 
            private function changeHandler(event:MenuEvent):void {
                var label:String = event.label;        
                popTypeB.text=String("Moved to " + label);
                popB.label = "Put in: " + label;
                popB.close();
            }
        ]]>
    </mx:Script>

    <mx:VBox>
        <mx:Label text="Main button mimics the last selected menuItem."/>
        <mx:PopUpButton id="popB" 
            label="Edit"  
            width="135"
            creationComplete="initMenu();"/>
        
        <mx:Spacer height="50"/>
        <mx:TextInput id="popTypeB"/>
    </mx:VBox>
</mx:Application>
The executing SWF file for the previous example is shown below:

User interaction

You navigate the PopUpButton control in the following ways:

• Moving the mouse over any part of the PopUpButton control highlights the button border and the main button or the pop-up button.
• Clicking the button dispatches the click event.
• Clicking the pop-up button pops up the pop-up control and dispatches an open event.
• Clicking anywhere outside the PopUpButton control, or in the pop-up control, closes the pop-up control and dispatches a close event.

The following keystrokes let users navigate the PopUpButton control: