Quantcast

Documentation Center

  • Trial Software
  • Product Updates

uiputfile

Open standard dialog box for saving files

Syntax

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

Description

    Note:   Successful execution of uiputfile does not create a file; it only returns the name of a new or existing file that you designate.

FileName = uiputfile displays a modal dialog box for selecting or specifying a file you want to create or save. The dialog box lists the files and folders in the current folder. If the selected or specified file name is valid, uiputfile returns it in FileName.

[FileName,PathName] = uiputfile also returns the path to FileName in PathName, or if you cancel the dialog, returns 0 for both arguments. If you do not provide any output arguments, the file name alone is returned in ans.

[FileName,PathName,FilterIndex] = uiputfile(FilterSpec)displays only those files with extensions that match FilterSpec. On some platforms uiputfile also displays in gray any files that do not 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 * and ? wildcard characters. For example, '*.m' lists all MATLAB® program files in a folder.

FilterSpec can be a string that contains a file name. uiputfile displays the file name selected in the File name field and uses the file extension as the default filter. The FilterSpec string can include a path, or consist of a path only. To specify a folder only, make the last character in DefaultName '\' or '/'. A path can contain special path characters, such as '.', '..', '/', '\', or '~'. For example, '../*.m' lists all program files in the folder above the current folder. 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 the default descriptions in the Save as type pop-up menu. A description cannot be an empty string. See the Examples for illustration of using cell arrays as FilterSpec. If you do not specify FilterSpec, uiputfile uses the default list of file types (all MATLAB files). FilterIndex is the index of the filter selected in the dialog box. Indexing starts at 1. If you click the Cancel button, close the dialog window, or if the file does not exist, uiputfile returns FilterIndex as 0.

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

[FileName,PathName,FilterIndex] = uiputfile(FilterSpec,DialogTitle,DefaultName)displays a dialog box in which the file name specified by DefaultName appears in the File name field. DefaultName can also be a path or a path+filename. To specify a folder only, make the last character in DefaultName '\' or '/'. In this case, uiputfile opens the dialog box in the folder specified by the path. If you specify a path in DefaultName that does not exist, uiputfile opens the dialog box in the current folder. You can use '.','..', '\', '/', or ~ in the DefaultName argument.

When typing into the dialog box, if you include either of the wildcard characters '*' or '?' in a file name, uiputfile does not respond to clicking Save. The dialog box remains open until you cancel it or remove the wildcard characters. This restriction applies to all platforms, even to file systems that permit these characters in file names.

If you select or specify an existing file name, a warning dialog box opens stating that the file already exists and asks if you want to replace it.

Select Yes to replace the existing file or No to return to the dialog to select another file name. Selecting Yes returns the name of the file. Selecting No returns 0.

For Microsoft® Windows® platforms, the dialog box is the Windows dialog box native to your platform, and thus can differ from what you see in the examples that follow.

For UNIX® platforms, the dialog box is like the one shown in the following figure.

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

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

Examples

The following statement displays a dialog box entitled 'Save file name', setting the File name field to animinit.m and the filter to program files (*.m). Because FilterSpec is a string, the filter also includes All Files (*.*)

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

 

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

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

 

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

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

 

To create a list of file types and give them descriptions that are different from the defaults, use a cell array. This example also associates multiple file types with the 'MATLAB Files' and 'Models' descriptions.

[filename, pathname, filterindex] = uiputfile( ...
{'*.m;*.fig;*.mat;*.slx;*.mdl',...
 'MATLAB Files (*.m,*.fig,*.mat,*.slx,*.mdl)';
 '*.m', 'program files (*.m)';...
 '*.fig','Figures (*.fig)';...
 '*.mat','MAT-files (*.mat)';...
 '*.slx;*.mdl','Models (*.slx,*.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. The first entry of column one contains several extensions separated by semicolons. These file types all associate with the description 'MATLAB Files (*.m,*.fig,*.mat,*.slx,*.mdl)'. The code produces the dialog box shown in the following figure.

 

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

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

Select or enter a file name for saving a figure as an image in one of four formats, described in a cell array.

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

See Also

| | |

Was this topic helpful?