Description StructDlg(struct_def) creates a modal dialog box that contains a user interface (UI) control for each of the struct_def fields.
In its simple form, StructDlg serves as a structure-based alternative to INPUTDLG and it is a convenient method for
browsing and changing structure values (e.g. when the structure contains parameters).
In its advanced form, StructDlg allows for a quick and convenient text based definition of a GUI that may contain many styles of UI controls such as edit, popup menus, radio buttons, toggles and more.
When structdlg is called the GUI is created and the user can set the values of the different UI controls (such as edit controls, radio buttons, popup menus, etc.)
When the user is satisfied with his selections, he presses an OK button which closes the GUI. structdlg then returns a structure with the
same field names as struct_def. The value of each field in the returned structure contains the value of the UI control of the same name.
The title of the dialog box may be specified by adding a second string argument. The dflt_P argument is a structure
that contains default values for the fields' values.
These values will override the default values specified in struct_def.
Note that the dflt_P argument should contain the default values ONLY, not the entire
definition as specified in struct_def. This is useful for allowing user-specific defaults that override the
'factory defaults'. A 4-element position vector can be specified by the forth argument. Position units are given in characters.
NOTE: A cancel button was added alongside the OK and reset buttons.
When the cancel button is pressed StructDlg returns an empty matrix, [].
The cancel button was added after the figures for this manual were prepared. Therefore, it does not appear in the following examples.
Examples
The name of each field of struct_def is the default label of the corresponding input field (underscores are presented as spaces).
In their simple form, struct_def fields may contain numeric values (limited to 2D matrixes) or single line strings.
For example:
The above example creates the following dialog box:
After the user makes some changes to the fields' values and presses the OK button StructDlg returns the following structure:
disp(P)
Duration: 12
Time_Out: 21
Weight_Matrix: [3x2 double]
Comment: 'This is a test'
For allowing more UI control styles and options the value of each struct_def field can be set to a cell array of up to four elements:
{ value/definition labels limits protected_flag }
The first element determines the type (edit, radio button, pop-up menu and more) of the control and its default value.
The second element allows overriding the default label (the field name). Any occurrence of an asterisk ('*') in the label is replaced with the field name.
This is useful when you want to add a text to the default label. For example, '* (kHz)' will add the unit KHz to the label.
This field is optional and merely changes the label of the UI control.
The empty string can be used to indicate that the default label should be used.
The third element can be used to specify limits to legal values that can be entered by the user. This is useful for numerical edit fields (see below.)
The forth element is a logical element (0/1). Setting this element to 1 causes the UI control to be protected (disabled.)
The user can right-click
on that control to unprotect (enable) it. This is useful when you want to indicate that the user should think before changing the current value
of the control.
Below are detailed examples of how to create all the styles and types of controls that structdlg supports.
Numeric values: Limited to 2D matrixes of any size (including the empty matrix). The default value can
be a numeric vector/matrix or a string that contains a valid Matlab expression whose evaluation yields a numeric
2D matrix. In the later case, you must specify the limits so StructDlg will interpret the field as a numeric field instead of a free string.
Note that both [] and [-Inf Inf] indicate unlimited values.
S.center_frequency = { 2000 '* (Hz)' [30 50000] };% default of 2000, allowed range:[30 50000].
S.my_parameter = 43 ; % default of 43, no limits.
S.size_of_matrix = { [4 12] '' [1 Inf] }; % default of [4 12], allowed range:[1 Inf].
P = StructDlg(S,'My title')
The above example creates the following dialog box:
Placing the cursor over any of the numeric fields shows the allowed range:
The dialog box prevents typing invalid input:
Clicking the right mouse button over any field allows for undoing the last edit or reseting to the default value:
StructDlg returns a structure with the same field names as the definition structure, not the label names. The value of each field reflects the input value entered by the user.
P =
center_frequency: 2000
my_parameter: 43
size_of_matrix: [4 12]
Note: The values the user enters to the dialog box for numeric fields are being 'eval'-uated, so inputs such as (sin(0.34)+2)^my_func(34.2) or zeros(3,3) are possible.
As described before numeric UI controls may be also defined using the short notation:
S.my_parameter = 5;
S.my_matrix = [1 3; 4 5];
Free Strings: Limited to a one line string (no string arrays). If no default is required, use the empty
string (''), otherwise the field will be treated as a numeric field.
S.User_name = {''};
S.Comment = 'No comment';
Radio buttons
: The definition includes a string that contains the options separated by '|'. The option that the user chooses will become the value of that field in the returned structure. A Default option can be specified by enclosing it with curly
brackets. The chosen option is converted to a numeric value if possible.
: The definition includes a Cell-array of single strings. The chosen option will be the value
of that field in P. A default option can be specified by enclosing it with curly brackets. The chosen
string is converted to a numeric value if possible.
: The definition is in the form: {'0' '1'}.
A default value may be specified by the curly brackets.
S.use_filter = { {'0','{1}'} };
File Name Dialogs
: The definition includes a cell of one string that must start with one of the following command identifiers: 'uigetfile', 'uiputfile' or 'uigetdir'.
The command identifier may be followed by any arguments that are allowed by that Matlab command.
Use 'help uigetfile', 'help uiputfile' and 'help uigetdir' to learn more about those options.
The user is able to specify the file name directly by typing it, or to press a small push-button that
pops up the appropriate Matlab's dialog box.
If the user made a multi-file selection, the returned value of that field will be a cell array whose elements are the file names selected concatenated with their directory name.
clear S
S.parameters_file = { {'uigetfile(''c:\temp\*.mat'')'} };
P = StructDlg(S);
uigetfile is called after the push-button is pressed:
Dependent Fields
: (For numeric fields only) A numeric field may include a reference to the value of
another numeric field. This is done using a reserved word 'this' to refer to the structure.
clear S
S.Window_size = { 512 '' [10 1000] };
S.Overlap = {'this.Window_size / 2''' [0 Inf]}; % Note that a non-empty limits indicator is needed in order to indicate that this is a numeric field.
P = structdlg(S);
Notes: The value of the dependent field will be automatically updated when the values of the referenced
fields changes. The automatically changed value will blink twice to alert the user. The user is then able
to undo the automatic change using the mouse's right-click.
The current values of the sub-structure can be viewed by placing the mouse over the push-button.
The user can press a push-button that calls 'StructDlg' recursively for the sub-structure.
After a while, we can ask again for user input.
This time, the default values will be the ones the user specified previously.
new_P = StructDlg(S,'Populattion analysis',P);
Note
: It is not possible for
a sub-structure field to reference fields in other sub-structures, or in other structure levels. It is
possible for a field to reference fields in sub-structures of lower levels; however, this is highly
discouraged.
