The PopUpMenuButton is a PopUpButton control whose secondary button pops up a Menu control. When the user selects an item from the pop-up menu, the main button of the PopUpButton changes to show the icon and label of the selected menu item. Unlike the Menu and MenuBar controls, the PopUpMenuButton supports only a single-level menu.

For complete reference information, see the Adobe Flex Language Reference. For more information on the Menu control, see Menu control events. For more information on PopUpButton controls, see PopUpButton control.

About the PopUpMenuButton control

The following example shows a PopUpMenuButton control before and after clicking the secondary pop-up button:

The PopUpMenuButton works as follows.

• When you click the smaller button, which by default displays a v icon, the control displays a pop-up menu below the button.
• When you select an item from the pop-up menu, the main PopUpMenuButton button label changes to show the selected item's label and the PopUpMenuButton control dispatches a MenuEvent.CHANGE event.
• When you click the main button, the PopUpMenuButton control dispatches a MenuEvent.CHANGE event and a MouseEvent.ITEM_CLICK event.

For information on handling PopUpMenuButton events, see PopUpMenuButton control events.

The PopUpMenuButton control lets users change the function of the main button by selecting items from the pop-up menu. The most recently selected item becomes the main button item.

This behavior is useful for buttons when there are a number of user actions, users tend to select the same option frequently, and the application developer cannot assume which option should be the default. Text editors often use such controls in their control bar for options, such as spacing, for which a user is likely to have a preferred setting, but the developer cannot determine it in advance. Microsoft Word, for example, uses such controls for specifying line spacing, borders, and text and highlight color.

You can use the PopUpButton control to create pop-up menu buttons with behaviors that differ from those of the PopUpMenuButton; for example, buttons that do not change the default action of the main button when the user selects a menu item. For more information, see PopUpButton control.

Creating a PopUpMenuButton control

You define a PopUpMenuButton control in MXML by using the <mx:PopUpMenuButton> tag. Specify an id value if you intend to refer to a component elsewhere in your MXML application, either in another tag or in an ActionScript block.

You specify the data for the PopUpMenuButton control by using the dataProvider property. For information on valid data providers, including their structure and contents, see Defining menu structure and data.

By default, the initially selected item is the first item in the pop-up menu dataProvider, and the default main button label is the item's label, as determined by the labelField or labelFunction property. To set the initial main button label to a specific item's label and functionality, write a listener for the PopUpMenuButton control's creationComplete event that sets the selectedIndex property of the Menu subcontrol, as follows:

Menu(MyPopUpControl.popUp).selectedIndex=2;

You must cast the PopUpMenuButton control's popUp property to a Menu because the property type is IUIComponent, not Menu.

You can also use the label property of the PopUpMenuButton control to set the main button label, as described in Using the label property.

When a popped up menu closes, it loses its selection and related properties.

Example: Creating a PopUpMenuButton control

The following example creates a PopUpMenuButton control by using an E4X XML data provider.

<?xml version="1.0"?>
<!-- menus/PopUpMenuButtonControl.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            import mx.controls.Menu
            
            // The initData function sets the initial value of the button 
            // label by setting the Menu subcontrol's selectedIndex property.
            // You must cast the popUp property to a Menu.
            private function initData():void {
                Menu(pb2.popUp).selectedIndex=2;
            }
        ]]>
    </mx:Script>

    <mx:XML format="e4x" id="dp2"> 
        <root>
            <editItem label="Cut"/> 
            <editItem label="Copy"/> 
            <editItem label="Paste"/> 
            <separator type="separator"/>
            <editItem label="Delete"/> 
        </root>
    </mx:XML>

    <mx:PopUpMenuButton id="pb2" 
        dataProvider="{dp2}" 
        labelField="@label" 
        showRoot="false" 
        creationComplete="initData();"/>
</mx:Application>
The executing SWF file for the previous example is shown below:

Because this example uses an E4X XML data source, you must specify the label field by using the E4X @ attribute specifier syntax, and you must tell the control not to show the data provider root node.

Using the label property

The label property of the PopUpMenuButton control specifies the contents of the label on the main button, and overrides any label from the pop-up menu that is determined by the labelField or labelFunction property. The label property is useful for creating a main button label with fixed and a variable parts; for example, a mail "Send to:" button where only the destination text is controlled by the pop-up menu, so the main button could say "Send to: Inbox" or "Send to: Trash" based on the selection from a menu that lists "Menu" and "Trash."

To use a dynamic label property, use a PopUpMenuButton control change event listener to set the label based on the event's label property, as in the following example:

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

    <mx:Script>
        <![CDATA[
            import mx.events.MenuEvent;
            
            public function itemClickHandler(event:MenuEvent):void {
                event.currentTarget.label= "Send to: " + event.label;
            }

            [Bindable] 
            public var menuData:Array = [
                {label: "Inbox", data: "inbox"},
                {label: "Calendar", data: "calendar"}, 
                {label: "Sent", data: "sent"},
                {label: "Deleted Items", data: "deleted"},
                {label: "Spam", data: "spam"}
            ];
        ]]>
    </mx:Script>

    <mx:PopUpMenuButton id="p1" 
        showRoot="true" 
        dataProvider="{menuData}" 
        label="Send to: Inbox" 
        itemClick="itemClickHandler(event);"/>    
</mx:Application>
The executing SWF file for the previous example is shown below:

PopUpMenuButton user interaction

The user interaction of the PopUpMenuButton control main button and secondary button is the same as for the PopUpButton control. The user interaction with the pop-up menu is the same as for the Menu control. For more information on the PopUpButton user interaction, see User interaction. For more information on Menu control user interaction, see Menu control user interaction.