Packagecom.ghostwire.ui.controls
Classpublic class uiMenu
InheritanceuiMenu Inheritance uiComponent Inheritance flash.display.Sprite

The uiMenu control creates a popup menu of individually selectable choices, similar to the File or Edit menu found in most software applications. The popup menu can have as many levels of submenus as needed.

You do not use the new operator to create a uiMenu instance. Instead, you must use the uiMenu.popup() method to display a popup menu.

There can be only one popup menu at any one time - if one currently exists, it will be closed before a new one is created and displayed.

A popup menu will remain visible until it is closed by the end-user via
- selecting an enabled menu item; or
- clicking anywhere outside the tree of the popup menu and its submenus; or
- pressing the TAB or ESCAPE key.

To close the currently shown popup menu programmatically, call the uiMenu.hide() method.

Typically, you would not instantiate popup menus using this class directly; you would use the uiMenuBar control instead. There may be times however where it would be useful to create a popup menu using a specific context, eg. listening to a button click and using the uiMenu.popup() method to show a popup menu below the button.

You must define a data model for populating the uiMenu control. You may easily define the data model using XML:

var menuXML:XML = 
<menu>
    <item label="ItemA" />
    <item label="ItemB" enabled="false" />
    <item label="ItemC" >
        <!-- comment: a group of radio items -->
        <item label="ItemCSubMenuItemA" group="RadioGroup1" />
        <item label="ItemCSubMenuItemB" group="RadioGroup1" />
        <item label="ItemCSubMenuItemC" group="RadioGroup1" checked="true" />
    </item>
    <!-- comment: empty item denotes a separator -->
    <item />
    <!-- comment: a check item -->
    <item label="ItemD" checked="false" />
    <item />
    <item label="ItemE" />
</menu>

var menuModel:uiModel = new uiModel(menuXML);

// you can then feed the menuModel to the uiMenu.popup() method

Each menu item can specify several attributes that determine how the item is displayed and behave. The following table lists the attributes you can specify:

AttributeTypeDescription
checked Boolean Applicable only for check and radio items. Specifies whether a check or radio item is selected. If the checked property is defined, but the group property is undefined, the item is treated as a check item.
enabled Boolean Specifies whether the user can select the menu item (true), or not (false). If not specified, a default value of true is used.
group String If defined, the item is treated as a radio item. If undefined, the item is a normal menu item.
icon String Specifies the source of an image asset to display in the menu item (will be displayed to the left of the text label). This property is ignored for check and radio items.
id String Optional. If defined, the data object can be accessed via the getItemById() method of the model. This property should be unique (no two item should use the same identifier). This is useful in case you need to access deeply nested items in your application code.
label String Specifies the text to display in the menu item.

Notice that a type attribute is absent and unnecessary since the following rules apply:
- all menu items are created as normal menu items by default;
- if an item has the checked property defined, it is created as a check item;
- if an item has the group property defined, it is created as a radio item;
- if an item is empty or does not define the label property, it is created as a separator.

Where an item has child nodes (submenu items), the data object created from the parsing of the XML will also contain a child property indicating an Array of the child menu items. An item with submenu items is non-selectable (clicking on it does not dispatch a uiMenuEvent.SELECT event).

"skin" Property
The default value is "Menu" and the asset(s) used are:

 Menu.png
 MenuItem.png
 

~ This class is available in Aspire UI Components Standard Edition ~

See also

com.ghostwire.ui.controls.uiMenuBar


Public Properties
 PropertyDefined by
 InheritedalignX : Number
Indicates how the component would like to be aligned horizontally within its allocated space.
uiComponent
 InheritedalignY : Number
Indicates how the component would like to be aligned vertically within its allocated space.
uiComponent
 Inheritedbackground : Object
Indicates the style of the background for this component.
uiComponent
 Inheritedcontainer : uiComponent
Indicates the uiComponent instance that contains this instance.
uiComponent
 Inheriteddepth : int
Indicates how deep the component is in the containment hierarchy.
uiComponent
 InheriteddesiredAllocationHeight : int
Indicates the vertical space this component would like to be allocated.
uiComponent
 InheriteddesiredAllocationWidth : int
Indicates the horizontal space this component would like to be allocated.
uiComponent
 Inheritedenabled : Boolean
Indicates whether the component is enabled for user interaction.
uiComponent
 InheritedfillX : Boolean
Indicates whether or not the component should automatically expand or shrink to fill its allocated horizontal space.
uiComponent
 InheritedfillY : Boolean
Indicates whether or not the component should automatically expand or shrink to fill its allocated vertical space.
uiComponent
 InheritedfocusPadding : Object
Indicates the thickness of the interior space from the edge of the component to the focus rectangle.
uiComponent
 InheritedfocusRect : Object
Indicates the class to use when rendering the rectangle around the component to indicate that it is in focus.
uiComponent
 Inheritedheight : Number
Indicates the current height of the component.
uiComponent
 Inheritedmargin : Object
Indicates the thickness of the space surrounding the component.
uiComponent
 InheritedmaxHeight : int
Indicates the upper limit for height.
uiComponent
 InheritedmaxWidth : int
Indicates the upper limit for width.
uiComponent
 InheritedminHeight : int
Indicates the lower limit for height.
uiComponent
 InheritedminWidth : int
Indicates the lower limit for width.
uiComponent
  model : uiModel
Indicates the uiModel that holds the items of this uiMenu instance.
uiMenu
 Inheritedpadding : Object
Indicates the thickness of the interior space from the edge of the component to the content area, which is where child components, if any, are contained.
uiComponent
 Inheritedskin : String
Indicates the name of the skin to use for this component instance.
uiComponent
 Inheritedstretch : Boolean
Indicates whether surplus space available in the parent container should be allocated to this component.
uiComponent
 InheritedtextStyle : String
Indicates the style to use for uiText instances contained in this component.
uiComponent
 InheritedtoolTip : Object
Indicates the content (text) of the tooltip that should be shown when the mouse hovers over this control.
uiComponent
 Inheriteduiskin : uiBitmapImage
Returns the uiBitmapImage rendered as the skin - for advanced users only.
uiComponent
 Inheritedvisible : Boolean
Indicates whether or not the component is visible within its container.
uiComponent
 Inheritedwidth : Number
Indicates the current width of the component.
uiComponent
Public Methods
 MethodDefined by
  
hide():void
[static] Closes the currently shown popup menu.
uiMenu
 Inherited
invalidate(type:String):void
Invalidates this component's "size", "display", "layout" or "textstyle".
uiComponent
 Inherited
move(x:Number, y:Number, noEvent:Boolean = false):void
Moves the component to the specified position, disregarding its allocation.
uiComponent
  
popup(model:uiModel, context:DisplayObject, initObj:Object = null):uiMenu
[static] Creates a new uiMenu instance, populates it with the specified model, and displays it below the specified context.
uiMenu
 Inherited
removeAllChildren(all:Boolean = false):void
Removes all children from this component.
uiComponent
 Inherited
setFocus(flag:Boolean = true):void
Gives this component instance the focus; the component must be on the display list and has its tabEnabled property set to true, otherwise this method will fail silently.
uiComponent
 Inherited
setSize(width:Number, height:Number, noEvent:Boolean = false):void
Sets this component's size to the specified width and height.
uiComponent
 Inherited
setVisible(value:Boolean, noEvent:Boolean = false):void
Sets the visibility of this component instance, dispatching a "show" or "hide" event accordingly.
uiComponent
 Inherited
validateNow():void
Validates and render the component instance, and any component instances with depth higher than itself in the validation queue, immediately.
uiComponent
Events
 EventSummaryDefined by
 Inherited Dispatched when the component's visible property is changed from true to false via calling the setVisible() method.uiComponent
   Dispatched when the popup menu is closed.uiMenu
   Dispatched when an enabled menu item is selected by the end-user, either by clicking on the item or pressing the SPACEBAR when the item is highlighted.uiMenu
   Dispatched when a submenu is opened by the end-user moving the mouse over a menu item that has child menu items.uiMenu
 Inherited Dispatched when the component's position within its parent container has changed via calling the move() method.uiComponent
 Inherited Dispatched when the component's size has changed via calling the setSize() method.uiComponent
 Inherited Dispatched when the component's visible property is changed from false to true via calling the setVisible() method.uiComponent
Property detail
modelproperty
model:uiModel  [read-write]

Indicates the uiModel that holds the items of this uiMenu instance.

This property should be set when calling uiMenu.popup().

The default value is an empty uiModel object.

Implementation
    public function get model():uiModel
    public function set model(value:uiModel):void

See also

Method detail
hide()method
public static function hide():void

Closes the currently shown popup menu.

popup()method 
public static function popup(model:uiModel, context:DisplayObject, initObj:Object = null):uiMenu

Creates a new uiMenu instance, populates it with the specified model, and displays it below the specified context.

There can be only one popup menu at any one time - if one currently exists, it will be closed before the new one is created and displayed.

To close the currently shown popup menu, use the uiMenu.hide() method.

Parameters
model:uiModel — Indicates the uiModel object that defines the items in this menu.
 
context:DisplayObject — Indicates the DisplayObject instance that "owns" this popup menu. Typically, this would mean the object that the end-user interacts with to bring up the menu. This DisplayObject instance must already be on the display list when this method is called. This context does not mean that the menu will be contained within that DisplayObject (in fact, this context need not be a container).
 
initObj:Object (default = null) — Optional. An Object containing property values to apply to the popup menu instance. This is used to set iconWidth, menuMaxWidth and/or menuItemHeight values. For example, to set an iconWidth of 24, you would call uiMenu.popup(model,context,{iconWidth:24}). The iconWidth indicates the space to allocate to icons on the left side of the menu items. The menuMaxWidth indicates the maximum width of the popup menu. The menuItemHeight indicates the height of each menu item (by default, this value is zero which means the component will compute the desired height automatically).

Returns
uiMenu — The uiMenu instance created and displayed. This allows you to register event listeners.
Event detail
menuHideevent 
Event object type: flash.events.uiMenuEvent
uiMenuEvent.type property = com.ghostwire.ui.events.uiMenuEvent.MENU_HIDE

Dispatched when the popup menu is closed. The menu property of the uiMenuEvent object dispatched will contain a reference to this popup menu instance.

Dispatched when the currently shown popup uiMenu is closed.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the event object with an event listener. For example, if you use myMenuBar.addEventListener() to register an event listener, myMenuBar is the value of the currentTarget.
targetThe object that dispatched the event. The target is not always the object listening for the event. Use the currentTarget property to access the object that is listening for the event.
itemnull. This property is not set for this type of event.
menuThe popup uiMenu that is closed.
menuSelectevent  
Event object type: flash.events.uiMenuEvent
uiMenuEvent.type property = com.ghostwire.ui.events.uiMenuEvent.MENU_SELECT

Dispatched when an enabled menu item is selected by the end-user, either by clicking on the item or pressing the SPACEBAR when the item is highlighted. An item with submenu items is non-selectable.

Dispatched when a user selects an enabled menu item from a uiMenu instance.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the event object with an event listener. For example, if you use myMenuBar.addEventListener() to register an event listener, myMenuBar is the value of the currentTarget.
targetThe object that dispatched the event. The target is not always the object listening for the event. Use the currentTarget property to access the object that is listening for the event.
itemA data object representing the menu item selected.
menuThe uiMenu containing the menu item that has been selected.
menuShowevent  
Event object type: flash.events.uiMenuEvent
uiMenuEvent.type property = com.ghostwire.ui.events.uiMenuEvent.MENU_SHOW

Dispatched when a submenu is opened by the end-user moving the mouse over a menu item that has child menu items. The menu property of the uiMenuEvent object dispatched will contain a reference to the submenu opened.

Dispatched when a submenu uiMenu instance is created and displayed.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the event object with an event listener. For example, if you use myMenuBar.addEventListener() to register an event listener, myMenuBar is the value of the currentTarget.
targetThe object that dispatched the event. The target is not always the object listening for the event. Use the currentTarget property to access the object that is listening for the event.
itemA data object representing the menu item in the parent menu that owns this submenu.
menuThe submenu uiMenu instance that is created and displayed.