Chapter 11: Using Menu-Based Controls--Menu control

The Menu control is a pop-up control that contains a menu of individually selectable choices. You use Action-
Script to create a Menu control that pops up in response to a user action, typically as part of an event listener.
Because you create a Menu control in response to an event, it does not have an MXML tag; you can create Menu
controls in ActionScript only.

 

About the Menu Control
The following example shows a Menu control:

In this example, the MenuItem A and MenuItem D items open submenus. Submenus open when the user moves
the mouse pointer over the parent item or accesses the parent item by using keyboard keys.
The default location of the Menu control is the upper-left corner of your application, at x, y coordinates 0,0. You
can pass
x and y arguments to the show() method to control the position relative to the application.
After a Menu opens, it remains visible until the user selects an enabled menu item, the user selects another
component in the application, or a script closes the menu.
To create a static menu that stays visible all the time, use the MenuBar control or PopUpMenuButton control. For
more information on the MenuBar control, see MenuBar control– on page 3. For more information on the
PopUpMenuButton control, see PopUpMenuButton control– on page 3.
Create a Menu control
You cannot create a Menu control by using an MXML tag; you must create it in ActionScript.
1 Create an instance of the Menu control by calling the static ActionScript Menu.createMenu() method and
passing the method an instance of the data provider that contains the information that populates the control as
the second parameter; for example:
var myMenu:Menu = Menu.createMenu(null, myMenuData);
(The first parameter can optionally specify the parent container of the menu.)
If you do not display the root node of the data provider, for example, if the data provider is an XML document
in E4X format, use a third parameter with the value
false. This parameter sets the menusshowRoot
property. The following example creates a menu that does not show the data provider root:
var myMenu:Menu = Menu.createMenu(null, myMenuData, false);
Note: To hide the root node, you must set the showRoot property in the createMenu method. Setting the property
after you create the menu has no effect.
2 Display the Menu instance by calling the ActionScript Menu.show() method; for example:
myMenu.show(10, 10);
Note: Menus displayed by using the Menu.popUpMenu() method are not removed automatically; you must call the
PopUpManager.removePopUp() method on the Menu object. The show() method automatically adds the Menu
object to the display list, and the
hide() method automatically removes it from the display list. Clicking outside the
menu (or pressing Escape) also hides the Menu object and removes it from the display list.

 

Example: Creating a simple Menu control
The following example uses the <mx:XML> tag to define the data for the Menu control and a Button control to
trigger the event that opens the Menu control:
 <?xml version="1.0"?> <!-- menus/SimpleMenuControl.mxml --> <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" > <mx:Script> <!--[CDATA[ // Import the Menu control. import mx.controls.Menu; // Create and display the Menu control. private function createAndShow():void { var myMenu:Menu = Menu.createMenu(null, myMenuData, false); myMenu.labelField="@label"; myMenu.show(10, 10); } ]]--> </mx:Script> <!-- Define the menu data. --> <mx:XML format="e4x" id="myMenuData"> <root> <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> </root> </mx:XML> <mx:VBox> <!-- Define a Button control to open the menu --> <mx:Button id="myButton" label="Open Menu" click="createAndShow();"/> </mx:VBox> </mx:Application>

 

You can assign any name to node tags in the XML data. In the previous sample, each node is named with the
generic
<menuitem> tag, but you can have used <node>, <subNode>, <person>, <address> and so on.
Because this example uses an E4X XML data source, you must specify the label field by using the E4X @ attribute
specifier syntax, and you tell the control not to show the data provider root node.
Several attributes or fields, such as the
type attribute, have meaning to the Menu control. For information on how
Flex interprets and uses the data provider data, see Specifying and using menu entry information– on page 3.

 

Menu control user interaction
You can use the mouse or the keyboard to interact with a Menu control. Clicking selects a menu item and closes
the menu, except with the following types of menu items:
Disabled items or separators Rolling over or clicking menu items has no effect and the menu remains visible.
Submenu anchors Rolling over the items activates the submenu; clicking them has no effect; rolling onto any
menu item other than one of the submenu items closes the submenu.

When a Menu control has focus, you can use the following keys to control it:

Key	Description
Down Arrow Up Arrow	Moves the selection down and up the rows of the menu. The selection loops at the top or bottom row.
Right Arrow	Opens a submenu, or moves the selection to the next menu in a menu bar.
Left Arrow	Closes a submenu and returns focus to the parent menu (if a parent menu exists), or moves the selection to the previous menu in a menu bar (if the menu bar exists).
Enter	Opens a submenu, has the effect of clicking and releasing the mouse on a row if a submenu does not exist.
Escape	Closes a menu level.