MATLAB Function Reference

uiputfile - Open standard dialog box for saving files

Syntax

uiputfile [FileName,PathName,FilterIndex] = uiputfile(FilterSpec) [FileName,PathName,FilterIndex] = uiputfile(FilterSpec,DialogTitle) [FileName,PathName,FilterIndex] = uiputfile(FilterSpec,DialogTitle,DefaultName)

Description

uiputfile displays a modal dialog box used to select or specify a file for saving. The dialog box lists the files and directories in the current directory. If the selected or specified filename is valid, it is returned in ans.

If an existing filename is selected or specified, the following warning dialog box is displayed.

The user can select Yes to replace the existing file or No to return to the dialog to select another filename. If the user selects Yes, uiputfile returns the name of the file. If the user selects No, uiputfile returns 0.

Note A modal dialog box prevents the user from interacting with other windows before responding. To block MATLAB program execution as well, use the uiwait function. For more information about modal dialog boxes, see WindowStyle in the MATLAB Figure Properties.

[FileName,PathName,FilterIndex] = uiputfile(FilterSpec) displays only those files with extensions that match FilterSpec. The uiputfile function appends 'All Files' to the list of file types.FilterSpec can be a string or a cell array of strings, and can include the * wildcard. For example, '*.m' lists all the MATLAB M-files.

If FilterSpec is a string that contains a filename, the filename is displayed and selected in the File name field and the file's extension is used as the default filter.
If FilterSpec is a string, it can include a path. That path can contain '.','..', or '/'. For example, '../*.m' lists all M-files in the directory above the current directory.
If FilterSpec is a cell array of strings, the first column contains a list of file extensions. The optional second column contains a corresponding list of descriptions. These descriptions replace standard descriptions in the Save as type field. A description cannot be an empty string. Example 3 and Example 4 illustrate use of a cell array as FilterSpec.

If FilterSpec is not specified, uiputfile uses the default list of file types (i.e., all MATLAB files).

After the user clicks Save and if the filename is valid,uiputfile returns the name of the selected file in FileName and its path in PathName. If the user clicks the Cancel button, closes the dialog window, or if the filename is not valid, FileName and PathName are set to 0.

FilterIndex is the index of the filter selected in the dialog box. Indexing starts at 1. If the user clicks the Cancel button, closes the dialog window, or if the file does not exist, FilterIndex is set to 0.

If no output arguments are specified, the filename is returned in ans.

[FileName,PathName,FilterIndex] = uiputfile(FilterSpec,DialogTitle) displays a dialog box that has the title DialogTitle. To use the default file types and specify a dialog title, enter

uiputfile('',DialogTitle)

[FileName,PathName,FilterIndex] = uiputfile(FilterSpec,DialogTitle,DefaultName) displays a dialog box in which the filename specified by DefaultName appears in the File name field. DefaultName can also be a path or a path/filename. In this case, uiputfile opens the dialog box in the directory specified by the path. See Example 6. Note that you can use '.','..', or '/' in the DefaultName argument.

If the specified path does not exist, uiputfile opens the dialog box in the current directory.

Remarks

For Windows platforms, the dialog box is the Windows dialog box native to your platform. Because of this, it may differ from those shown in the examples below.

For UNIX platforms, the dialog box is similar to the one shown in the following figure.

For Mac platforms, the dialog box is similar to the one shown in the following figure.

Examples

Example 1

The following statement displays a dialog box titled 'Save file name' with the Filename field set to animinit.m and the filter set to M-files (*.m). Because FilterSpec is a string, the filter also includes All Files (*.*)

[file,path] = uiputfile('animinit.m','Save file name');

Example 2

The following statement displays a dialog box titled 'Save Workspace As' with the filter specifier set to MAT-files.

[file,path] = uiputfile('*.mat','Save Workspace As');

Example 3

To display several file types in the Save as type list box, separate each file extension with a semicolon, as in the following code. Note that uiputfile displays a default description for each known file type, such as "Simulink Models" for .mdl files.

[filename, pathname] = uiputfile(...
 {'*.m';'*.mdl';'*.mat';'*.*'},...
 'Save as');

Example 4

If you want to create a list of file types and give them descriptions that are different from the defaults, use a cell array, as in the following code. This example also associates multiple file types with the 'MATLAB Files' description.

[filename, pathname, filterindex] = uiputfile( ...
{'*.m;*.fig;*.mat;*.mdl','MATLAB Files (*.m,*.fig,*.mat,*.mdl)';
 '*.m', 'M-files (*.m)';...
 '*.fig','Figures (*.fig)';...
 '*.mat','MAT-files (*.mat)';...
 '*.mdl','Models (*.mdl)';...
 '*.*',  'All Files (*.*)'},...
 'Save as');

The first column of the cell array contains the file extensions, while the second contains the descriptions you want to provide for the file types. Note that the first entry of column one contains several extensions, separated by semicolons, all of which are associated with the description 'MATLAB Files (*.m,*.fig,*.mat,*.mdl)'. The code produces the dialog box shown in the following figure.

Example 5

The following code checks for the existence of the file and displays a message about the result of the open operation.

[filename, pathname] = uiputfile('*.m','Pick an M-file');
if isequal(filename,0) || isequal(pathname,0)
   disp('User selected Cancel')
else
   disp(['User selected',fullfile(pathname,filename)])
end

Example 6

uiputfile({'*.jpg;*.tif;*.png;*.gif','All Image Files';...
          '*.*','All Files' },'Save Image',...
          'C:\Work\newfile.jpg')