Settings dialog

Set or change arbitrary structure via a dialog

The function settingsdlg() is a GUI-dialog much like MATLAB's default errordlg(), questiondlg() and warndlg(), which provides a standardized way to assign specific values to a structure. This structure can then be used to insert specific settings
into one of MATLAB's many standard algorithms, or your own. The most basic usage is as follows:

[ settings, button] = settingsdlg(...
'TolX' , 1e-6,...
'TolFun', 1e-6);
which will produce a nice dialog box with the fields and edit boxes as you'd expect them. After pressing OK or Cancel, the structure settings will be

settings =

TolX: 1.0000e-006
TolFun: 1.0000e-006
button =
'ok'

or any relevant values you have assigned. Naturally, you can add as many fields as you want; the dialog will automatically adjust its size to match your input. If you would like the user to not just insert numeric values, but select values from a
string list, use

settings = settingsdlg(...
'TolX' , 1e-6,...
'TolFun' , 1e-6,...
'Algorithm', {'active-set','interior-point'});

which will produce the same dialog, with a popup-list added. The resulting structure in this case is:

settings =

TolX: 1.0000e-006
TolFun: 1.0000e-006
Algorithm: 'active-set'

Of course, it isn't always convenient to have the text for each option in the dialog box equal to the fieldname in the resulting structure. If you want the fieldname to be different from the displayed string, you can use something like:

settings = settingsdlg(...
{'Tolerance X' ;'TolX' }, 1e-6,...
{'Tolerance Fun';'TolFun'}, 1e-6,...
'Algorithm', {'active-set','interior-point'});

which produces the dialog displaying the *first* entries in the cell-arrays, but the associated structure has the fieldnames

settings =

TolX: 1.0000e-006
TolFun: 1.0000e-006
Algorithm: 'active-set'

Also, you can add separators, a different dialog title, and a brief description:

settings = settingsdlg(...
'Description', 'This dialog will set the parameters used by FMINCON()',...
'title' , 'FMINCON() options',...
'separator' , 'Unconstrained/General',...
{'Tolerance X' ;'TolX' }, 1e-6,...
{'Tolerance on Function';'TolFun'}, 1e-6,...
'Algorithm' , {'active-set','interior-point'},...
'separator' , 'Constrained',...
{'Tolerance on Constraint';'TolCon'}, 1e-6);

The 'title' and 'description' options can appear anywhere in the argument list, they will not affect the fields in the output structure. The order of the 'separator' option of course *does* matter, but, it will *not* be added as a field to the output structure. You can also use logicals, which produce checkboxes:

settings = settingsdlg(...
'Description', 'This dialog will set the parameters used by FMINCON()',...
'title' , 'FMINCON() options',...
'separator' , 'Unconstrained/General',...
{'Tolerance X';'TolX'}, 1e-6,...
{'Tolerance on Function';'TolFun'}, 1e-6,...
'Algorithm' , {'active-set','interior-point'},...
'separator' , 'Constrained',...
{'This is a checkbox'; 'Check'}, true,...
{'Tolerance on Constraints';'TolCon'}, 1e-6);

which results in

settings =

TolX: 1.0000e-006
TolFun: 1.0000e-006
Algorithm: 'active-set'
Check: 1
TolCon: 1.0000e-006

You can also assign multiple (logical!) values to a single checkbox, in which case the fields below the checkbox are all disabled/enabled when you check it:

settings = settingsdlg(...
'Description', 'This dialog will set the parameters used by FMINCON()',...
'title' , 'FMINCON() options',...
'separator' , 'Unconstrained/General',...
{'This is a checkbox'; 'Check'}, [true, true],...
{'Tolerance X';'TolX'}, 1e-6,...
{'Tolerance on Function';'TolFun'}, 1e-6,...
'Algorithm' , {'active-set','interior-point'},...
'separator' , 'Constrained',...
{'Tolerance on Constraints';'TolCon'}, 1e-6);

Setting the checkbox value to [true, true] will cause the dialog box to appear with all fields below the appropriate separator disabled, whereas a value of [true, false] will have all fields initially enabled. Checking or un-checking the checkbox will simply swap the enabled/disabled states.

Finally, you can insert a single structure as a (single!) argument, which produces a dialog box according to its settings and fieldnames:

settings = struct(...
'TolX' , 1e-6,...
'TolFun', 1e-6);
settings = settingsdlg(settings);

Naturally, since all other information is absent in this last example, the functionality in this case is rather limited. But if the intent is to change a fairly simple structure, it certainly suffices.