Main Content

export2wsdlg

Create dialog box for exporting variables to workspace

collapse all in page

Syntax

export2wsdlg(labels,vars,vals)
export2wsdlg(labels,vars,vals,title)
export2wsdlg(labels,vars,vals,title,defs)
export2wsdlg(labels,vars,vals,title,defs,helpfcn)
export2wsdlg(labels,vars,vals,title,defs,helpfcn,flist)
f = export2wsdlg(___)
[f,tf] = export2wsdlg(___)

Description

export2wsdlg(labels,vars,vals) creates a modal dialog box with a series of check boxes and edit fields. For each check box, there is a corresponding edit field. The arguments are:

  • labels – the labels for the check boxes.

    The number of labels determines how many check boxes and edit fields appear in the dialog box. One edit field appears after each check box label; for example:

    Check box with label "Save sum of A to variable named:" followed by an edit field with text "sumA". There is no check box.

  • vars – the default variable names that appear in the edit fields, such as sumA shown in the preceding image.

  • vals – the values to store in the variables.

The labels, vars, and vals must specify the same number of items. If labels, vars, and vals each specify one item, then the dialog box displays a label and an edit field only. For example:

Label with text "Same sum of A to variable named:" followed by an edit field with text "sumA"

example

export2wsdlg(labels,vars,vals,title) specifies a title for the dialog box.

export2wsdlg(labels,vars,vals,title,defs) specifies which check boxes are selected when the dialog box opens.

example

export2wsdlg(labels,vars,vals,title,defs,helpfcn) adds a Help button to the dialog box. The helpfcn is a callback that displays help.

example

export2wsdlg(labels,vars,vals,title,defs,helpfcn,flist) specifies a cell array of functions and optional arguments that calculate, and then return the values to export to vars. When you specify an flist, MATLAB® uses it instead of vals. However, you must specify the vals argument as a syntax placeholder. The flist must be the same length as labels.

example

f = export2wsdlg(___) returns the Figure object in which the dialog box displays to f. You can request this output with any of the input argument combinations in the previous syntaxes.

[f,tf] = export2wsdlg(___) returns tf as 1 (true) if the user clicks OK, or 0 if the user closes the dialog box by clicking Cancel or the close button (X) in the dialog box title bar. When tf is 0, f is returned as an empty array ([]). The export2swdlg function does not return until the user closes the dialog box.

Examples

collapse all

Create a dialog box that enables the user to save the variables sumA, or meanA, or both to the base workspace. 

A = randn(10,1);
labels = {'Save sum of A to variable named:' ...
          'Save mean of A to variable named:'}; 
vars = {'sumA','meanA'}; 
values = {sum(A),mean(A)};
export2wsdlg(labels,vars,values);

Export to Workspace dialog box. The dialog box contains a check box with label "Save sum of A to variable named:" followed by an edit field with text "sumA", another check box with label "Save mean of A to variable named:" followed by an edit field with text "meanA", an OK button, and a Cancel button. Both check boxes are selected.

If the user enters an invalid variable name, such as 2 and clicks OK, then MATLAB automatically returns an error dialog box. After clicking OK in the error dialog box, the user has an opportunity to enter a valid variable name in the Export to Workspace dialog box.

Error dialog box with message "'2' is not a valid MATLAB variable name."

Define the input variable, defs, to specify that no check box is selected when the dialog box opens.

A = randn(10,1);
labels = {'Save sum of A to variable named:' ...
          'Save mean of A to variable named:'}; 
vars = {'sumA','meanA'}; 
vals = {sum(A),mean(A)};
title = ('Save Sums to Workspace');
defs = logical([0 0]);
export2wsdlg(labels,vars,vals,...
             title,defs);

Save Sums to Workspace dialog box. The dialog box contains a check box with label "Save sum of A to variable named:" followed by an uneditable edit field with text "sumA", another check box with label "Save mean of A to variable named:" followed by an uneditable edit field with text "meanA", an OK button, and a Cancel button. No check boxes are selected.

If the user clicks OK when no check boxes are selected, MATLAB automatically returns an error dialog box. After clicking OK in the error dialog box, the user has the opportunity to correct the error in the Export to Workspace dialog box.

Error dialog box with message "You must check a box to export variables"

Add a Help button to the dialog box by specifying a callback input argument. Clicking the Help button runs the callback. In this code, the callback function is smhelp, which creates a Help dialog box. For more information, see Create Callbacks for Apps Created Programmatically.

function expsm
A = randn(10,1);
labels = {'Save sum of A to variable named:' ...
          'Save mean of A to variable named:'}; 
vars = {'sumA','meanA'}; 
vals = {sum(A),mean(A)};
title = ('Save Sums to Workspace');
defs = logical([1 0]);
export2wsdlg(labels,vars,vals,...
             title,defs,{@smhelp});
         
    function smhelp
        helpdlg({'Select one or both check boxes.',...
                 'Change the variable names, if desired,',...
                 'and then click OK.'});
    end
 end

To run this example, copy and paste the preceding code into a text editor. Save the file as exspm.m to a folder on your MATLAB path. When you run the code and click the Help button, the Help Dialog box opens on top of the Save Sums to Workspace dialog box. The following image shows the two dialog boxes side by side.

On the left is a Save Sums to Workspace dialog box with three buttons: OK, Cancel, and Help. On the right is a help dialog box.

Create a dialog box to create and export figure objects to the workspace. Specify a function list to create figure windows in the specified colors when the user selects the corresponding check boxes, and then clicks OK. The vals input argument is a syntax placeholder only. Therefore, the cell array items specified by the value of vals are unused. 

labels = {'Red Figure Window',...
          'Blue Figure Window',...
          'Green Figure Window'};
vars = {'fRed','fBlue','fGreen'};
vals = {0,0,0};
title = 'Figure Color Samples';
defs = [false false false];
flist = {{@figure,'color','r'},...
         {@figure,'color','b'},...
         {@figure,'color','g'}};
export2wsdlg(labels,vars,vals,title,defs,{@doc,'figure'},flist);

Figure Color Samples dialog box. There are three export options: Red Figure Window, Blue Figure Window, and Green Figure Window. Each option has an unselected check box and an uneditable edit field with a variable name. There are three buttons: OK, Cancel, and Help.

After the user makes check box selections and clicks OK, MATLAB does the following for the selected check boxes:

  • Runs the corresponding functions (each of which creates a figure)

  • Returns the figure objects to the vars variables

  • Exports the variables to the base workspace.

Input Arguments

collapse all

Check box labels, specified as a cell array of character vectors or a string array. If there is only one item in the array, then export2wsdlg creates an edit field instead of a check box. The lengths of labels, vars, vals, and defs must all be equal.

Example: {'Temperature (Celsius)','Mass (Grams)'}

Edit field variable names that appear in the edit fields by default when the dialog box opens, specified as a cell array of character vectors or a string array. The number of array elements is the same as the number specified in labels. The lengths of labels, vars, vals, and defs must all be equal.

The variable names in vars must be unique.

The dialog box user can edit the variable names displayed in the edit fields. If the user specifies the same name in multiple edit fields, then MATLAB creates a structure using that name. It then uses the defaultvars items as field names for that structure.

Example: {'Longitude','Latitude'}

Variable values, specified as a cell array. The lengths of labels, vars, vals, and defs must all be equal.

Example: {100,200}

Example: {sin(A),cos(A)}

Dialog box title, specified as a character vector or string scalar.

Example: 'Save to Workspace'

Default check box selections, specified as a logical array. The lengths of labels, vars, vals, and defs must all be equal.

By default all check boxes are selected when the dialog box opens.

Example: [true, false] specifies that when the dialog box opens the first check box is selected and the second is not.

Help button callback specified as a function handle, cell array, or character vector (not recommended). When you specify a Help button callback, MATLAB adds a Help button to the dialog box. For more information, see Create Callbacks for Apps Created Programmatically

Example: @myfun specifies the callback function as a function handle.

Example: {@myfun,x} specifies the callback function as a cell array. In this case, the function accepts the input argument x.

A list of function calls, specified as a cell array of function names and optional arguments that calculate and then return the value to export. flist must be the same length as labels.

Example: {{@myfun1,x},{@myfun2,x,y}}

Output Arguments

collapse all

Figure object in which the dialog box is displayed. If two return arguments are requested, then f is returned as an empty array [] and the export2wsdlg function does not return values until the user closes the dialog box.

True or false result, returned as 1 or 0. The function returns 1 (true) if the user clicks the OK button; otherwise, it returns 0. The export2wsdlg function does not return values until the user closes the dialog box.

More About

collapse all

Modal Dialog Box

A modal dialog box prevents a user from interacting with other MATLAB windows before responding to the dialog box.

Tips

  • MATLAB program execution continues even when a modal Export to Workspace dialog box is active. To block program execution until the user closes the dialog box, use the uiwait function.

Version History

Introduced in R2006b

See Also