User interaction with a Menu or menu-based control is event-driven; that is, applications typically handle events generated when the user opens, closes, or selects within a menu, or submenu or rolls over or out of menu items. For detailed information on events and how to use them, see Using Events.

The Menu and MenuBar controls dispatch an identical set of menu-specific events. Event handling with PopUpMenuButton controls differs from the other two controls, but shares many elements in common with the others.

Menu control events

The Menu control defines the following menu-specific event types, of the MenuEvent class:

change 

(MenuEvent.CHANGE) Dispatched when a user changes current menu selection by using the keyboard or mouse.

itemClick 

(MenuEvent.ITEM_CLICK) Dispatched when a user selects an enabled menu item of type normal, check, or radio. This event is not dispatched when a user selects a menu item of type separator, a menu item that opens a submenu, or a disabled menu item.

itemRollOut  

(MenuEvent.ITEM_ROLL_OUT) Dispatched when the mouse pointer rolls off of a Menu item.

itemRollOver 

(MenuEvent.ITEM_ROLL_OVER) Dispatched when the mouse pointer rolls onto a Menu item.

menuHide 

(MenuEvent.MENU_HIDE) Dispatched when the entire menu or a submenu closes.

menuShow 

(MenuEvent.MENU_SHOW) Dispatched when the entire menu or a submenu opens.

The event object passed to the event listener is of type MenuEvent and contains one or more of the following menu-specific properties:

To access properties and fields of an object-based menu item, you specify the menu item field name, as follows:

ta1.text = event.item.label

To access attributes of an E4X XML-based menu item, you specify the menu item attribute name in E4X syntax, as follows:

ta1.text = event.item.@label

The following example shows a menu with a simple event listener. For a more complex example, see Example: Using Menu control events.

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

    <mx:Script>
        <![CDATA[
            import mx.controls.Menu;
            import mx.events.MenuEvent;
    
            // Function to create and show a menu.
            private function createAndShow():void {
                var myMenu:Menu = Menu.createMenu(null, myMenuData, false);
                myMenu.labelField="@label"
                // Add an event listener for the itemClick event.
                myMenu.addEventListener(MenuEvent.ITEM_CLICK, 
                    itemClickInfo);
                // Show the menu.
                myMenu.show(225, 10);
            }
    
            // The event listener for the itemClick event.
            private function itemClickInfo(event:MenuEvent):void {
                ta1.text="event.type: " + event.type;
                ta1.text+="\nevent.index: " + event.index;
                ta1.text+="\nItem label: " + event.item.@label
                ta1.text+="\nItem selected: " + event.item.@toggled;
                ta1.text+= "\nItem type: " + event.item.@type;
            }
        ]]>
    </mx:Script>

    <!-- The XML-based menu data provider. -->
    <mx:XML id="myMenuData">
            <xmlRoot>
            <menuitem label="MenuItem A" >
                <menuitem label="SubMenuItem A-1" enabled="false"/>
                <menuitem label="SubMenuItem A-2"/>
            </menuitem>
            <menuitem label="MenuItem B" type="check" toggled="true"/>
            <menuitem label="MenuItem C" type="check" toggled="false"/>
            <menuitem type="separator"/>     
            <menuitem label="MenuItem D" >
                <menuitem label="SubMenuItem D-1" type="radio" 
                    groupName="one"/>
                <menuitem label="SubMenuItem D-2" type="radio" 
                    groupName="one" toggled="true"/>
                <menuitem label="SubMenuItem D-3" type="radio" 
                    groupName="one"/>
            </menuitem>
            </xmlRoot>
    </mx:XML>

    <!-- Button controls to open the menus. -->
    <mx:Button x="10" y="5" 
        label="Open Menu" 
        click="createAndShow();"/>
    <!-- Text area to display the event information -->
    <mx:TextArea x="10" y="40" 
        width="200" height="100" 
        id="ta1"/>
</mx:Application>
The executing SWF file for the previous example is shown below:

MenuBar events

The following figure shows a MenuBar control:

For the menu bar, the following events occur:

change 

(MenuEvent.CHANGE) Dispatched when a user changes current menu bar selection by using the keyboard or mouse. This event is also dispatched when the user changes the current menu selection in a pop-up submenu. When the event occurs on the menu bar, the menu property of the MenuEvent object is null.

itemRollOut  

(MenuEvent.ITEM_ROLL_OUT) Dispatched when the mouse pointer rolls off of a menu bar item.

itemRollOver 

(MenuEvent.ITEM_ROLL_OVER) Dispatched when the mouse pointer rolls onto a menu bar item.

menuHide 

(MenuEvent.MENU_HIDE) Dispatched when a pop-up submenu closes.

menuShow 

(MenuEvent.MENU_SHOW) Dispatched when a pop-up submenu opens, or the user selects a menu bar item with no drop-down menu.

For each pop-up submenu, the MenuBar dispatches the change, itemClick, itemRollOut, itemRollOver, menuShow, and menuHide events in the same way it does for the Menu control. Handle events triggered by the pop-up menus as you would handle events from Menu controls. For more information, see Menu control events.

The following example handles events for the menu bar and for the pop-up submenus.

<?xml version="1.0"?>
<!-- menus/MenuBarEventInfo.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    creationComplete="initCollections();">
    
    <mx:Script>
        <![CDATA[
            import mx.events.MenuEvent;
            import mx.controls.Alert;
            import mx.collections.*;

            [Bindable]
            public var menuBarCollection:XMLListCollection;
    
            private var menubarXML:XMLList =<>
                <menuitem label="Menu1">
                    <menuitem label="MenuItem 1-A" data="1A"/>
                    <menuitem label="MenuItem 1-B" data="1B"/>
                </menuitem>
                <menuitem label="Menu2">
                    <menuitem label="MenuItem 2-A" data="2A"/>
                    <menuitem label="MenuItem 2-B" data="2B"/>
                </menuitem>
                <menuitem label="Menu3" data="M3"/>
                </>
                
            // Event handler to initialize the MenuBar control.
            private function initCollections():void {
                menuBarCollection = new XMLListCollection(menubarXML);
            }
            
            // Event handler for the MenuBar control's change event.
            private function changeHandler(event:MenuEvent):void  {
                // Only open the Alert for a selection in a pop-up submenu.
                // The MenuEvent.menu property is null for a change event 
                // dispatched by the menu bar.
                if (event.menu != null) {
                    Alert.show("Label: " + event.item.@label + "\n" + 
                        "Data: " + event.item.@data, "Clicked menu item");
                }                    
            }

            // Event handler for the MenuBar control's itemRollOver event.
            private function rollOverHandler(event:MenuEvent):void {
                rollOverTextArea.text = "type: " + event.type + "\n";
                rollOverTextArea.text += "target menuBarIndex: " + 
                    event.index + "\n";
            }           

            // Event handler for the MenuBar control's itemClick event.
            private function itemClickHandler(event:MenuEvent):void {
                itemClickTextArea.text = "type: " + event.type + "\n";
                itemClickTextArea.text += "target menuBarIndex: " + 
                    event.index + "\n";
            }           
        ]]>
    </mx:Script>

    <mx:Panel title="MenuBar Control Example" 
        height="75%" width="75%" 
        paddingTop="10" paddingLeft="10">

        <mx:Label 
            width="100%" 
            color="blue" 
            text="Select a menu item."/>
        <mx:MenuBar labelField="@label"  
            dataProvider="{menuBarCollection}"
            change="changeHandler(event);" 
            itemClick="itemClickHandler(event);" 
            itemRollOver="rollOverHandler(event);"/>        
        <mx:TextArea id="rollOverTextArea" 
            width="200" height="100"/>
        <mx:TextArea id="itemClickTextArea" 
            width="200" height="100"/>         
    </mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:

Example: Using Menu control events

The following example lets you experiment with Menu control events. It lets you display two menus, one with an XML data provider and one with an Array data provider. A TextArea control displays information about each event as a user opens the menus, moves the mouse, and selects menu items. It shows some of the differences in how you handle XML and object-based menus, and indicates some of the types of information that are available about each Menu event.

<?xml version="1.0"?>
<!-- menus/ExtendedMenuExample.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
    <mx:Script>
        <![CDATA[    
        /* Import the Menu control and MenuEvent class. */
        import mx.controls.Menu;
        import mx.events.MenuEvent;
        
        /* Define a variable for the Menu control. */
        private var myMenu:Menu;

        /* The event listener that creates menu with an XML data 
           provider and adds event listeners for the menu. */
        private function createAndShow():void {
            /* Clear the event output display. */
            ta1.text="";
            /* Don't show the (single) XML root node in the menu. */
            myMenu = Menu.createMenu(null, myMenuData, false);
            /* Set the labelField explicitly for XML data providers. */
            myMenu.labelField="@label" 
            myMenu.addEventListener(MenuEvent.ITEM_CLICK, menuShowInfo);
            myMenu.addEventListener(MenuEvent.MENU_SHOW, menuShowInfo);
            myMenu.addEventListener(MenuEvent.MENU_HIDE, menuShowInfo);
            myMenu.addEventListener(MenuEvent.ITEM_ROLL_OUT, menuShowInfo);
            myMenu.addEventListener(MenuEvent.ITEM_ROLL_OVER, menuShowInfo);
            myMenu.show(275, 10);
        }

        /* The event listener for the menu events.
           Retain information on all events for a menu instance. */
        private function menuShowInfo(event:MenuEvent):void {
            ta1.text="event.type: " + event.type;
            ta1.text+="\nevent.label: " + event.label;
            /* The index value is -1 for menuShow and menuHide events. */
            ta1.text+="\nevent.index: " + event.index;
            /* The item field is null for show and hide events. */
            if (event.item) {
                ta1.text+="\nItem label: " + event.item.@label
                ta1.text+="\nItem selected: " + event.item.@toggled;
                ta1.text+= "\nItem type: " + event.item.@type;
            }
        }

        /* The event listener that creates an object-based menu 
           and adds event listeners for the menu. */
        private function createAndShow2():void {
            /* Show the top (root) level objects in the menu. */
            myMenu = Menu.createMenu(null, menuData, true);
            myMenu.addEventListener(MenuEvent.ITEM_CLICK, menuShowInfo2);
            myMenu.addEventListener(MenuEvent.MENU_SHOW, menuShowInfo2);
            /* The following line is commented out so that you can see the 
               results of an ITEM_CLICK event. 
               (The menu hides immediately after the click.)
               myMenu.addEventListener(MenuEvent.MENU_HIDE, menuShowInfo2); */
            myMenu.addEventListener(MenuEvent.ITEM_ROLL_OVER, menuShowInfo2);
            myMenu.addEventListener(MenuEvent.ITEM_ROLL_OUT, menuShowInfo2);
            myMenu.show(275, 10);
        }

        /* The event listener for the object-based Menu events. */
        private function menuShowInfo2(event:MenuEvent):void {
            ta1.text="event.type: " + event.type;
            ta1.text+="\nevent.label: " + event.label;
            /* The index value is -1 for menuShow and menuHide events. */
            ta1.text+="\nevent.index: " + event.index;
            /* The item field is null for show and hide events. */
            if (event.item) {
                ta1.text+="\nItem label: " + event.item.label
                ta1.text+="\nItem selected: " + event.item.toggled;
                ta1.text+= "\ntype: " + event.item.type;
            }
        }

        /* The object-based data provider, an Array of objects.
           Its contents is identical to that of the XML data provider. */
        [Bindable] 
        public var menuData:Array = [
            {label: "MenuItem A", children: [
                {label: "SubMenuItem A-1", enabled: false},
                {label: "SubMenuItem A-2", type: "normal"} 
            ]},
            {label: "MenuItem B", type: "check", toggled: true},
            {label: "MenuItem C", type: "check", toggled: false},
            {type: "separator"},
            {label: "MenuItem D", children: [
                {label: "SubMenuItem D-1", type: "radio", groupName: "g1"},
                {label: "SubMenuItem D-2", type: "radio", groupName: "g1", toggled: true}, 
                {label: "SubMenuItem D-3", type: "radio", groupName: "g1"} 
            ]} 
        ];
    ]]>
    </mx:Script>

    <!-- The XML-based menu data provider. The XML tag requires a single root. -->
    <mx:XML id="myMenuData">
        <xmlRoot>
            <menuitem label="MenuItem A" >
                <menuitem label="SubMenuItem A-1" enabled="false"/>
                <menuitem label="SubMenuItem A-2"/>
            </menuitem>
            <menuitem label="MenuItem B" type="check" toggled="true"/>
            <menuitem label="MenuItem C" type="check" toggled="false"/>
            <menuitem type="separator"/>     
            <menuitem label="MenuItem D" >
                <menuitem label="SubMenuItem D-1" type="radio" groupName="one"/>
                <menuitem label="SubMenuItem D-2" type="radio" groupName="one" toggled="true"/>
                <menuitem label="SubMenuItem D-3" type="radio" groupName="one"/>
            </menuitem>
        </xmlRoot>
    </mx:XML>
    <!-- Text area to display the event information. -->
    <mx:TextArea id="ta1" width="264" height="168" x="11" y="38"/>
    
    <!-- Button controls to open the menus. -->
    <mx:Button id="b1"
        label="Open XML Popup" 
        click="createAndShow();" x="10" y="10"
    />
    <mx:Button id="b2"
        label="Open Object Popup" 
        click="createAndShow2();" x="139" y="10"
    />
</mx:Application>
The executing SWF file for the previous example is shown below:

PopUpMenuButton control events

Because the PopUpMenuButton is a subclass of the PopUpButton control, it supports all of that control's events. When the user clicks the main button, the PopUpMenuButton control dispatches a click (MouseEvent.CLICK) event.

When the user clicks the PopUpMenuButton main button, the control dispatches an itemClick (MenuEvent.ITEM_CLICK) event that contains information about the selected menu item. Therefore, the same itemClick event is dispatched when the user clicks the main button or selects the current item from the pop-up menu. Because the same event is dispatched in both cases, clicking on the main button produces the same behavior as clicking on the last selected menuItem, so the main button plays the role of a frequently used menu item.

The following example shows how the PopUpMenuButton generates events and how an application can handle them.

When the user selects an item from the pop-up menu, the following things occur:

• The PopUpMenuButton dispatches an itemClick event.
• The application's itemClickHandler() event listener function handles the itemClick event and displays the information about the event in an Alert control.

When the user clicks the main button, the following things occur:

• The PopUpMenuButton control dispatches a click event.
• The PopUpMenuButton control dispatches an itemClick event.
• The application's itemClickHandler() event listener function handles the itemClick event and displays information about the selected Menu item in an Alert control.
• The application's clickHandler() event listener function also handles the MouseEvent.CLICK event, and displays the Button label in an Alert control.

<?xml version="1.0"?>
<!-- menus/PopUpMenuButtonEvents.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    height="600" width="600" 
    creationComplete="initData();">

    <mx:Script>
        <![CDATA[
        import mx.events.*;
        import mx.controls.*;
            
        // Set the Inbox (fourth) item in the menu as the button item.
        private function initData():void {
            Menu(p1.popUp).selectedIndex=3;
        }
            
        // itemClick event handler, invoked when you select from the menu.
        // Shows the event's label, index properties, and the values of the 
        // label and data fields of the data provider entry specified by 
        // the event's item property.
        public function itemClickHandler(event:MenuEvent):void {
            Alert.show("itemClick event label: " + event.label
                + "  \nindex: " + event.index
                + "  \nitem.label: " + event.item.label 
                + "  \nitem.data: " + event.item.data); 
        }
        
        //Click event handler for the main button.
        public function clickHandler(event:MouseEvent):void {
            Alert.show(" Click Event currentTarget.label: " 
                + event.currentTarget.label);
        }
            
        //The menu data provider
        [Bindable] 
        public var menuDP: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="{menuDP}"
        click="clickHandler(event)"
        itemClick="itemClickHandler(event);"
    />
</mx:Application>
The executing SWF file for the previous example is shown below: