Settings dialog

Set or change arbitrary structure via a dialog
2.3K Downloads
Updated 2 May 2020

Editor's Note: This file was selected as MATLAB Central Pick of the Week

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.

Cite As

Rody Oldenhuis (2024). Settings dialog (https://github.com/rodyo/FEX-settingsdlg/releases/tag/v1.6), GitHub. Retrieved .

MATLAB Release Compatibility
Created with R2009b
Compatible with any release
Platform Compatibility
Windows macOS Linux
Categories
Find more on Dialog Boxes in Help Center and MATLAB Answers

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!

Versions that use the GitHub default branch cannot be downloaded

Version Published Release Notes
1.6

See release notes for this release on GitHub: https://github.com/rodyo/FEX-settingsdlg/releases/tag/v1.6

1.5.0.0

[linked to Github]

1.4.0.0

- Implemented window positioning option as suggested by Terrance Nearey below
- Begun implementation of treatment of cell-data (Matt J below)
- Updated doc & contact info

1.3.0.0

- Made separators boldface;
- Checkboxes and separators now span the whole width of the window (instead of ControlWidth).

1.2.0.0

- changed button='OK' to button='ok' to make the m-file and documentation agree
- Added "WindowWidth" and "ControlWidth", as suggested by Peter

1.1.0.0

Updated the documentation in the M-file, and added the 'button' feature, as suggested by Peter.

1.0.0.0

To view or report issues in this GitHub add-on, visit the GitHub Repository.
To view or report issues in this GitHub add-on, visit the GitHub Repository.