3.5.5Selecting from a list

The framework provides a SelectFromList() function to display a standard dialog for selecting from a simple list of options. A couple of notes:

This function only gives you a final result. You don't get an initial creation message from the dialog which gives you the ability to destroy it.

You can display a more complex list, with multiple levels and with additional options such as icons, using Framework.MenuListDialog()

SelectFromList() takes two parameters: the list to display, and an asynchronous callback function which receives the user's selection (or cancellation). For example:

Framework.SelectFromList([

{value: "close", caption: "Close"},

{value: "reverse", caption: "Reverse"},

{value: "double", caption: "Double", someExtraData: "x2"}

], function (selection) {

// Either null, or one of the objects in the array

});

You can pass three types of list as the first parameter:

A simple array of values, such as [1, 2, 3, 4, 5] or ["Red", "Green", "Blue"]. What you get back as the selection is simply the selected item in the array, such as 3 or "Green".

An array of objects, like the example above. Each object must have a caption, which is what is displayed to the user. What you get back is the entire selected object, such as {value: "double", caption: "Double", someExtraData: "x2"}

Full dialog initialisation, including the ability to set standard properties such as noCancel, containing an items[] array which is then like the example above.

As an example of the third type, the following code displays the same list of options as the example above, but customises the title and adds the noCancel style into the dialog which is displayed to the user:

Framework.SelectFromList({

title: "What shall we do?",

noCancel: true,

items: [

{value: "close", caption: "Close"},

{value: "reverse", caption: "Reverse"},

{value: "double", caption: "Double", someExtraPrivateData: "x2"}

]

}, function (selection) {

// Either null, or one of the objects in the array

});