3.5.7Displaying a settings dialog

The framework provides an AskSettings() function which lets you display a list of settings such as a combination of numeric and text fields. Note: 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.

The settings which you display can potentially be long and complicated, divided up into multiple sections or even multiple pages. A simple example is as follows:

Framework.AskSettings([

{type: "int", caption: "A number field", value: 23},

{type: "text", caption: "A text field", value: "Some text"},

{type: "instrumentId", caption: "A market", value: "GBP/USD"},

{type: "list", caption: "A list of options", value: "value2", options: [

{k: "value1", v: "Option 1"},

{k: "value2", v: "Option 2"}

]}

], function (MsgResult) {

…

});

Each individual field in the settings can have the following properties:

Property	Description
id	Optional, but helps to identify the field when you receive the results back from the dialog
caption	Label to display next to the field
type	Type of field: one of text, textarea, yesno, list, int, float, color, time, email, instrumentId, timeframe
value	Initial value to pre-populate into the field: · For a list, this should be the k value of one of the options For a chart timeframe, this should be the usual ID; a number of seconds. For a color, this should be a CSS color value such as "darkolivegreen" or "#FF0000" For a time, this should be a string in the form hh:ss such as "14:18"
options	Only used for a list field. As in the above example, an array of objects which have k and v properties (key, and text to display to the user)

The configuration which you pass into AskSettings() can be any of the following:

An array of fields, as in the example above

An object with a fields[] array

An object with a sections[] array

An object with a pages[] array

If you pass an object rather than a bare array, then you can set a title plus standard dialog options such as noCancel.

Passing an object with a sections[] array lets you break up a large set of fields into multiple sections, to make it easier for the user to understand. For example:

Framework.AskSettings({

sections: [

{

caption: "Section 1",

fields: [

{type: "int", caption: "A number field", value: 17},

]

}, {

caption: "Section 2",

fields: [

{type: "int", caption: "Another number field", value: 46},

]

}

]

}, function (MsgResult) {

…

});

Your settings can even be split up into multiple pages; a pages[] array. Each page must have a caption and a sections[] array.

What you get back in your asynchronous callback function depends on the input you provide. The Msg which is passed to the callback is always an FXB.Result object. The code will be FXB.ErrorCodes.CANCELLED if the user cancelled the dialog.

If the user saves the settings, then you will receive one of the following inside the Msg object, depending on the input your provided for the dialog:

A pages[] array, repeating the pages[] array which you passed in, and filling in the selected values for each field

A sections[] array, repeating the sections[] array which you passed in, and filling in the selected values for each field

Or, just a fields[] array