class Menu
package feathers.controls
extends BaseScrollContainer › FeathersControl › MeasureSprite › ValidatingSprite
implements IFocusContainer, IDataSelector<Dynamic>, IIndexSelector
Displays a pop-up menu of items.
The following example creates a menu, gives it a data provider, tells the item renderer how to interpret the data, and listens for when an item is triggered:
var menu = new Menu();
menu.dataProvider = new ArrayHierarhicalCollection<MenuItemData>([
{ text: "New" },
{ text: "Open" },
{ separator: true },
{ text: "Save" },
{ separator: true },
{ text: "Quit" }
], (item:MenuItemData) -> item.children);
menu.itemToText = (item:MenuItemData) -> {
return item.text;
};
menu.itemToSeparator = (item:MenuItemData) -> {
return item.separator;
};
menu.addEventListener(MenuEvent.ITEM_TRIGGER, (event:MenuEvent) -> {
var menu = cast(event.currentTarget, Menu);
trace("Menu item triggered: " + event.state.index + " " + event.state.text);
});
menu.showAtPosition(10.0, 20.0);The example above uses the following custom Haxe typedef.
typedef MenuItemData = {
?text:String,
?children:Array<MenuItemData>,
?separator:Bool
}Events:
feathers.events.MenuEvent.ITEM_TRIGGER | Dispatched when the user taps or clicks an item renderer in the menu. The pointer must remain within the bounds of the item renderer on release, and the menu cannot scroll before release, or the gesture will be ignored. |
|---|---|
openfl.events.Event.CLOSE | Dispatched when the menu closes. |
1.4.0
.See also:
Static variables
staticfinalread onlyCHILD_VARIANT_ITEM_RENDERER:String = "menu_itemRenderer"
The variant used to style the menu's item renderers in a theme.
To override this default variant, set the
Menu.customItemRendererVariant property.
1.4.0
.See also:
Constructor
new(?dataProvider:IHierarchicalCollection<Dynamic>, ?itemTriggerListener:MenuEvent ‑> Void)
Creates a new Menu object.
1.4.0
.Variables
customItemRendererVariant:String
A custom variant to set on all item renderers, instead of
Menu.CHILD_VARIANT_ITEM_RENDERER.
The customItemRendererVariant will be not be used if the result of
itemRendererRecycler.create() already has a variant set.
1.4.0
.See also:
dataProvider:IHierarchicalCollection<Dynamic>
The collection of data displayed by the menu.
Items in the collection must be class instances or anonymous structures. Do not add primitive values (such as strings, booleans, or numeric values) directly to the collection.
Additionally, all items in the collection must be unique object instances. Do not add the same instance to the collection more than once because a runtime exception will be thrown.
The following example passes in a data provider and tells the item renderer how to interpret the data:
menu.dataProvider = new ArrayCollection([
{ text: "Milk" },
{ text: "Eggs" },
{ text: "Bread" },
{ text: "Chicken" },
]);
menu.itemToText = (item:Dynamic) -> {
return item.text;
};1.4.0
.See also:
forceItemStateUpdate:Bool
Forces the itemRendererRecycler.update() method to be called with the
MenuItemState when the menu validates, even if the item's state has
not changed since the previous validation.
Before Feathers UI 1.2, update() was called more frequently, and this
property is provided to enable backwards compatibility, temporarily, to
assist in migration from earlier versions of Feathers UI.
In general, when this property needs to be enabled, its often because of
a missed call to dataProvider.updateAt() (preferred) or
dataProvider.updateAll() (less common).
The forceItemStateUpdate property may be removed in a future major
version, so it is best to avoid relying on it as a long-term solution.
1.4.0
.itemRendererRecycler:AbstractDisplayObjectRecycler<Dynamic, MenuItemState, DisplayObject>
Manages item renderers used by the menu.
In the following example, the menu uses a custom item renderer class:
menu.itemRendererRecycler = DisplayObjectRecycler.withClass(CustomItemRenderer);1.4.0
.See also:
layout:ILayout
The layout algorithm used to position and size the menu's items.
By default, if no layout is provided by the time that the menu initializes, a default layout that displays items vertically will be created.
The following example tells the menu to use a horizontal layout:
var layout = new HorizontalListLayout();
layout.gap = 20.0;
layout.padding = 20.0;
menu.layout = layout;1.4.0
.pointerSelectionEnabled:Bool = true
Indicates if selection is changed with MouseEvent.CLICK or
TouchEvent.TOUCH_TAP when the item renderer does not implement the
IToggle interface. If set to false, all item renderers must control
their own selection manually (not only ones that implement IToggle).
The following example disables pointer selection:
menu.pointerSelectionEnabled = false;1.4.0
.separatorRecycler:AbstractDisplayObjectRecycler<Dynamic, MenuItemState, DisplayObject>
Manages separator renderers used by the menu.
In the following example, the menu uses a custom item renderer class:
menu.separatorRecycler = DisplayObjectRecycler.withClass(CustomItemRenderer);1.4.0
.See also:
virtualLayout:Bool
Indicates if the menu's layout is allowed to virtualize items or not.
The following example disables virtual layouts:
menu.virtualLayout = false;1.4.0
.itemRendererRecyclerIDFunction:(state:MenuItemState) ‑> String
When a menu requires multiple item renderer types, this function is used
to determine which type of item renderer is required for a specific item.
Returns the ID of the item renderer recycler to use for the item, or
null if the default itemRendererRecycler should be used.
The following example provides an itemRendererRecyclerIDFunction:
var regularItemRecycler = DisplayObjectRecycler.withClass(ItemRenderer);
var firstItemRecycler = DisplayObjectRecycler.withClass(MyCustomItemRenderer);
menu.setItemRendererRecycler("regular-item", regularItemRecycler);
menu.setItemRendererRecycler("first-item", firstItemRecycler);
menu.itemRendererRecyclerIDFunction = function(state:MenuItemState):String {
if(state.index == 0) {
return "first-item";
}
return "regular-item";
};1.4.0
.See also:
`Menu.itemRendererRecycler
itemToEnabled:Dynamic ‑> Bool
Determines if an item should be enabled or disabled. By default, all
items are enabled, unless the Menu is disabled. This method
may be replaced to provide a custom value for enabled.
For example, consider the following item:
{ text: "Example Item", disable: true }If the Menu should disable an item if the disable field is
true, a custom implementation of itemToEnabled() might look like
this:
menu.itemToEnabled = (item:Dynamic) -> {
return !item.disable;
};1.4.0
.itemToSeparator:Dynamic ‑> Bool
Determines if an item represents a separator menu item.
For example, consider the following item:
var fileItems:Array<Dynamic> = [
{ text: "Open" },
{ separator: true },
{ text: "Quit" },
];If the Menu should display some items as separators, a custom
implementation of itemToSeparator() might look like this:
menu.itemToSeparator = (item:Dynamic) -> {
return Reflect.hasField(item, "separator") && Reflect.field(item, "separator") == true;
};1.4.0
.itemToText:Dynamic ‑> String
Converts an item to text to display within menu. By default, the
toString() method is called to convert an item to text. This method
may be replaced to provide custom text.
For example, consider the following item:
{ text: "Example Item" }If the Menu should display the text "Example Item", a custom
implementation of itemToText() might look like this:
menu.itemToText = (item:Dynamic) -> {
return item.text;
};1.4.0
.Methods
close():Void
Closes the menu, if opened.
When the menu closes, it will dispatch an event of type
Event.CLOSE.
1.4.0
.See also:
getItemRendererRecycler(id:String):DisplayObjectRecycler<Dynamic, MenuItemState, DisplayObject>
Returns the item renderer recycler associated with a specific ID.
Returns null if no recycler is associated with the ID.
1.4.0
.See also:
indexToItemRenderer(index:Int):DisplayObject
Returns the current item renderer used to render the item at the
specified index in the data provider. May return null if an item
doesn't currently have an item renderer.
Note: Most menus use "virtual" layouts, which means that only the currently-visible subset of items will have an item renderer. As the menu scrolls, the items with item renderers will change, and item renderers may even be re-used to display different items.
1.4.0
.itemRendererToItem(itemRenderer:DisplayObject):Dynamic
Returns the current item from the data provider that is rendered by a specific item renderer.
1.4.0
.itemToItemRenderer(item:Dynamic):DisplayObject
Returns the current item renderer used to render a specific item from
the data provider. May return null if an item doesn't currently have
an item renderer.
Note: Most menus use "virtual" layouts, which means that only the currently-visible subset of items will have an item renderer. As the menu scrolls, the items with item renderers will change, and item renderers may even be re-used to display different items.
1.4.0
.itemToItemState(item:Dynamic):MenuItemState
Returns a MenuItemState representing a specific item.
1.4.0
.scrollToIndex(index:Int, ?animationDuration:Float):Void
Scrolls the menu so that the specified item renderer is completely visible. If the item renderer is already completely visible, does not update the scroll position.
A custom animation duration may be specified. To update the scroll
position without animation, pass a value of 0.0 for the duration.
1.4.0
.setItemRendererRecycler(id:String, recycler:AbstractDisplayObjectRecycler<Dynamic, MenuItemState, DisplayObject>):Void
Associates an item renderer recycler with an ID to allow multiple types
of item renderers may be displayed in the menu. A custom
itemRendererRecyclerIDFunction may be specified to return the ID of
the recycler to use for a specific item in the data provider.
To clear a recycler, pass in null for the value.
1.4.0
.See also:
showAtOrigin(origin:DisplayObject):Void
Shows the menu relative to the specified origin display object.
1.4.0
.See also:
showAtPosition(stageX:Float, stageY:Float, ?context:DisplayObject):Void
Shows the menu relative to the specified position, in stage coordinates.
An optional context display object may be passed in to determine the
Stage instance where the menu will be displayed. If null, the
context will default to the Application.topLevelApplication value. If
there is no top-level application, `openfl.Lib.curent
1.4.0
.See also: