3.5.6Menu-list dialogs (with icons, sub-menus etc)

On small screens such as mobile phones, the framework modifies pop-up menus in widgets so that they are instead displayed as a list in a dialog. This way of presenting a choice of values is also available as the Framework.MenuListDialog() function, letting you display a list with multiple levels and with options such as icons for each item.

MenuListDialog() takes two parameters: a definition of the dialog, and a callback function which is notified about initial creation of the dialog and the user's selection (or cancellation of the dialog). For example:

Framework.MenuListDialog({

title: "My list",

items: [

{text: "Item 1", actionData: "some value"},

{text: "Item 2", checkbox: true, separator: true, id: 98},

{text: "Disabled item", disabled: true},

{text: "Has a sub-menu", icon: "xf002", items: [

{text: "Sub item 1", color: "red", id: 37},

{text: "Sub item 2", icon: "xf00d", id: 43}

]},

]

}, function (Msg) {

if (Msg.result && Msg.result.itemData) {

// User made a selection. Selected item is in Msg.result.itemData

}

});

The definition of the list can have a title, and the standard dialog settings such as width and height. It should also have an items[] array, as in the example above, defining the options to display to the user.

Each entry in the items[] array can have the following properties.

Property	Description
text	Text to display for the item
items:[]	Optional array of sub-items, as in the example above. The menu can have any level of nesting: sub-menus which have sub-menus which have sub-menus etc.
disabled	If true, the item cannot be selected, and is visually styled as disabled
unselectable	If true, the item cannot be selected, but without being visually styled as disabled
separator	If true, the framework displays a separator bar between this item and the one before it.
separatorAfter	If true, the framework displays a separator bar between this item and the one after it.
icon	Icon to display next to the item. This can be the hexadecimal code of any Font Awesome icon, prefaced with x. For example, xf34e to display an alarm-clock icon.
checkbox	If not null, the item is given either a ticked (checkbox:false) or unticked (checkbox:true) checkbox icon. If both checkbox and icon are set, then icon takes precedence.
checked	If not null, the item is given either a unfilled (checked:false) or filled (checked:true) radio-button icon. If both checked and icon are set, then icon takes precedence.
color	Overrides the text colour using a normal CSS colour value such as "red" or "#FF0000"
iconColor	Overrides the icon colour using a normal CSS colour value such as "red" or "#FF0000"
backgroundColor	Overrides the background colour for the item's row using a normal CSS colour value such as "red" or "#FF0000"

Each entry in the array can also have any number of other properties for your own reference, such as id, value, action etc. When an item is selected, the full data for the item, including any extra properties such as these, is passed into your asynchronous callback function (as Msg.result.itemData).

Your callback function is called twice: once with initialisation data which gives you the ID of the dialog, and a second time with the result of the dialog: either the user's selection, or cancellation.

The final result callback has a result member, an FXB.Result object, in the Msg. The code of Msg.result will be FXB.ErrorCodes.CANCELLED if the user closed the dialog without a response. If the user selected one of the items then the code will be FXB.ErrorCodes.OKAY and the FXB.Result will have an itemData property which gives you the full data of the selected item from the items[] array. The simplest way to check for a user selection versus cancellation or an initial update from the dialog is therefore like the example above:

if (Msg.result && Msg.result.itemData) {

// User has made a selection

} else {

// Initial update message, or user cancelled the dialog without response

}