Packagecom.ghostwire.ui.controls
Classpublic class uiMenuBar
InheritanceuiMenuBar Inheritance uiTabViewBar Inheritance uiComponent Inheritance flash.display.Sprite

The uiMenuBar control is used to display a horizontal, top-level menu bar that contains one or more menu items. Clicking on a top-level menu item opens a popup menu that is an instance of the uiMenu control.

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

var menuXML:XML = 
<menu>
    <item label="File" >
        <item label="New..." />
        <item label="Open..." />
        <item label="Open Recent" >
            <item label="Document 1" />
            <item label="Document 2" />
            <item label="Document 3" />
        </item>
        <!-- comment: empty item denotes a separator -->
        <item />
        <item label="Save" enabled="false" />
        <item />
        <item label="Exit" />
    </item>
    <item label="Edit" >
        <item label="Undo" />
        <item label="Redo" enabled="false" />
        <item />
        <item label="Cut" enabled="false" />
        <item label="Copy" enabled="false" />
        <item label="Paste" enabled="false" />
    </item>
    <item label="View" >
        <!-- comment: check items -->
        <item label="Line Numbers" checked="true" />
        <item label="Word Wrap" checked="false" />
        <item />
        <item label="Language" >
            <!-- comment: a group of radio items -->
            <item label="English" group="Lang" checked="true" />
            <item label="French" group="Lang" />
            <item label="Japanese" group="Lang" />
        </item>
    </item>
    <item label="Help" >
        <item label="About..." />
    </item>
</menu>

var menuModel:uiModel = new uiModel(menuXML);

myMenuBar.model = menuModel;

NOTE: each top-level item must have one or more child submenu items and must also define a label.

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 "MenuBar" and the asset(s) used are:

 MenuBar.png
 MenuBarItem.png (this asset is typically mapped to MenuItem.png)
 

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

See also

com.ghostwire.ui.controls.uiMenu


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
 InheriteddataMap : Object
Indicates an object used to map properties in the renderers to properties in the data objects (items).
uiTabViewBar
 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
  iconWidth : int = 16
Indicates the space, in pixels, to allocate to the icons (leftmost area of the menu items).
uiMenuBar
 InheriteditemRenderer : Class
Indicates the class to use to paint the "face" of the item.
uiTabViewBar
 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
  menuItemHeight : int
Indicates the height of menu items.
uiMenuBar
  menuMaxWidth : int
Indicates the maximum width that popup menus opened by this uiMenuBar control should have.
uiMenuBar
 InheritedminHeight : int
Indicates the lower limit for height.
uiComponent
 InheritedminWidth : int
Indicates the lower limit for width.
uiComponent
 Inheritedmodel : uiModel
Indicates the uiModel used to populate this uiTabViewBar.
uiTabViewBar
 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
 InheritedselectedIndex : int
Indicates the index position of the currently selected tab.
uiTabViewBar
 Inheritedskin : String
Indicates the name of the skin to use for this component instance.
uiComponent
 Inheritedspacing : int
Indicates the spacing between tab buttons.
uiTabViewBar
 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
 Inheriteduistepper : uiStepper
Returns the embedded uiStepper instance - for advanced users only.
uiTabViewBar
 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
  
Constructor - creates a new uiMenuBar instance.
uiMenuBar
  
activate():void
Activates this menu bar, selecting the first menu item and popping up its submenu.
uiMenuBar
 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
 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 current selected tab has changed.uiTabViewBar
 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.uiMenuBar
   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.uiMenuBar
   Dispatched when a submenu is opened by the end-user moving the mouse over a menu item that has child menu items.uiMenuBar
 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
iconWidthproperty
public var iconWidth:int = 16

Indicates the space, in pixels, to allocate to the icons (leftmost area of the menu items). This value is applied to all submenus so the size of the icon area is the same throughout.

The default value is 16.

menuItemHeightproperty 
public var menuItemHeight:int

Indicates the height of menu items. This value is applied to all menu items including those in submenus so the height of all menu items is the same throughout.

Leave this value as zero (default value) to let the component decide on the height to use based on the contents of the menu items. This means that the menu items in each menu/submenu will have the same height, but this height can be different in each submenu.

The default value is 0.

menuMaxWidthproperty 
public var menuMaxWidth:int

Indicates the maximum width that popup menus opened by this uiMenuBar control should have. The width of a menu depends on its widest item. Use this property to limit the width if desired (the limit has an inherent minimum value of the equivalent of 64 + iconWidth which is 80 by default).

If set to zero, a limit is not imposed.

Note: the uiMenu class scans through the items in its data model to look for the widest item, but it may not scan through the whole model if the list is huge - to balance asthetics and performance, the uiMenu will only spend up to 250 milliseconds for the scanning. If a list is huge, you should attempt to place the widest item at the top of the list so that it gets scanned first.

The default value is 0.

Constructor detail
uiMenuBar()constructor
public function uiMenuBar()

Constructor - creates a new uiMenuBar instance.

Method detail
activate()method
public function activate():void

Activates this menu bar, selecting the first menu item and popping up its submenu.

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.

Note: clicking on a top-level menu item in the menu bar does not dispatch this event; an Event.CHANGE event is dispatched instead.

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.