Package | com.ghostwire.ui.controls |
Class | public class uiMenu |
Inheritance | uiMenu ![]() ![]() |
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:
Attribute | Type | Description |
---|---|---|
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
Property | Defined by | ||
---|---|---|---|
![]() | alignX : Number
Indicates how the component would like to be aligned horizontally within its allocated space.
| uiComponent | |
![]() | alignY : Number
Indicates how the component would like to be aligned vertically within its allocated space.
| uiComponent | |
![]() | background : Object
Indicates the style of the background for this component.
| uiComponent | |
![]() | container : uiComponent
Indicates the
uiComponent instance that contains this instance. | uiComponent | |
![]() | depth : int
Indicates how deep the component is in the containment hierarchy.
| uiComponent | |
![]() | desiredAllocationHeight : int
Indicates the vertical space this component would like to be allocated.
| uiComponent | |
![]() | desiredAllocationWidth : int
Indicates the horizontal space this component would like to be allocated.
| uiComponent | |
![]() | enabled : Boolean
Indicates whether the component is enabled for user interaction.
| uiComponent | |
![]() | fillX : Boolean
Indicates whether or not the component should automatically expand or shrink to fill its allocated
horizontal space.
| uiComponent | |
![]() | fillY : Boolean
Indicates whether or not the component should automatically expand or shrink to fill its allocated
vertical space.
| uiComponent | |
![]() | focusPadding : Object
Indicates the thickness of the interior space from the edge of the component to the focus
rectangle.
| uiComponent | |
![]() | focusRect : Object
Indicates the class to use when rendering the rectangle around the component to indicate that it
is in focus.
| uiComponent | |
![]() | height : Number
Indicates the current
height of the component. | uiComponent | |
![]() | margin : Object
Indicates the thickness of the space surrounding the component.
| uiComponent | |
![]() | maxHeight : int
Indicates the upper limit for
height . | uiComponent | |
![]() | maxWidth : int
Indicates the upper limit for
width . | uiComponent | |
![]() | minHeight : int
Indicates the lower limit for
height . | uiComponent | |
![]() | minWidth : int
Indicates the lower limit for
width . | uiComponent | |
model : uiModel
Indicates the
uiModel that holds the items of this uiMenu instance. | uiMenu | ||
![]() | padding : 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 | |
![]() | skin : String
Indicates the name of the skin to use for this component instance.
| uiComponent | |
![]() | stretch : Boolean
Indicates whether surplus space available in the parent container should be allocated to this
component.
| uiComponent | |
![]() | textStyle : String
Indicates the style to use for
uiText instances contained in this component. | uiComponent | |
![]() | toolTip : Object
Indicates the content (text) of the tooltip that should be shown when the mouse hovers
over this control.
| uiComponent | |
![]() | uiskin : uiBitmapImage
Returns the
uiBitmapImage rendered as the skin - for advanced users only. | uiComponent | |
![]() | visible : Boolean
Indicates whether or not the component is visible within its container.
| uiComponent | |
![]() | width : Number
Indicates the current
width of the component. | uiComponent |
Method | Defined by | ||
---|---|---|---|
hide():void
[static]
Closes the currently shown popup menu.
| uiMenu | ||
![]() |
invalidate(type:String):void
Invalidates this component's "size", "display", "layout" or "textstyle".
| uiComponent | |
![]() |
move(x:Number, y:Number, noEvent:Boolean = false):void
Moves the component to the specified position, disregarding its allocation.
| uiComponent | |
[static]
Creates a new
uiMenu instance, populates it with the specified model ,
and displays it below the specified context . | uiMenu | ||
![]() |
removeAllChildren(all:Boolean = false):void
Removes all children from this component.
| uiComponent | |
![]() |
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 | |
![]() |
setSize(width:Number, height:Number, noEvent:Boolean = false):void
Sets this component's size to the specified
width and height . | uiComponent | |
![]() |
setVisible(value:Boolean, noEvent:Boolean = false):void
Sets the visibility of this component instance, dispatching a "show" or "hide" event accordingly.
| uiComponent | |
![]() |
validateNow():void
Validates and render the component instance, and any component instances with
depth higher than itself in the validation queue, immediately. | uiComponent |
Event | Summary | Defined by | ||
---|---|---|---|---|
![]() |
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 | |||
![]() |
Dispatched when the component's position within its parent container has changed via calling the
move() method. | uiComponent | ||
![]() |
Dispatched when the component's size has changed via calling the setSize() method. | uiComponent | ||
![]() |
Dispatched when the component's visible property is changed from false to
true via calling the setVisible() method. | uiComponent |
model | property |
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
.
public function get model():uiModel
public function set model(value:uiModel):void
See also
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.
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).
|
uiMenu —
The uiMenu instance created and displayed. This allows you to register
event listeners.
|
menuHide | event |
flash.events.uiMenuEvent
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:
Property | Value |
---|---|
bubbles | false |
cancelable | false ; there is no default behavior to cancel. |
currentTarget | The 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. |
target | The 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. |
item | null . This property is not set for this type of event. |
menu | The popup uiMenu that is closed. |
menuSelect | event |
flash.events.uiMenuEvent
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:
Property | Value |
---|---|
bubbles | false |
cancelable | false ; there is no default behavior to cancel. |
currentTarget | The 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. |
target | The 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. |
item | A data object representing the menu item selected. |
menu | The uiMenu containing the menu item that has been selected. |
menuShow | event |
flash.events.uiMenuEvent
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:
Property | Value |
---|---|
bubbles | false |
cancelable | false ; there is no default behavior to cancel. |
currentTarget | The 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. |
target | The 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. |
item | A data object representing the menu item in the parent menu that owns this submenu. |
menu | The submenu uiMenu instance that is created and displayed. |