uiputfile

Open dialog box for saving files

Syntax

file = uiputfile

[file,location] = uiputfile

[file,location,indx] = uiputfile

___ = uiputfile(filter)

___ = uiputfile(filter,title)

___ = uiputfile(filter,title,defname)

Description

file = uiputfile opens a modal dialog box for selecting or specifying a file. The dialog box lists the files and folders in the current folder.

• If the user specifies a valid file name and clicks Save, then MATLAB^® returns that file name in file.

• If the user cancels the dialog box, then MATLAB returns 0 to file.

Note

• Successful execution of uiputfile returns the name of a new or existing file that the user specifies. It does not create a file.

• The visual characteristics of the dialog box depend on the operating system that runs your code. For instance, some operating systems do not show title bars on dialog boxes. If you pass a dialog box title to the uiputfile function, those operating systems do not display the title.

[file,location] = uiputfile returns the selected or specified file path to location. If the user cancels the dialog box, then MATLAB returns 0 to both output arguments.

[file,location,indx] = uiputfile returns the index of the Save as type value selected in the dialog box. Indexing starts at 1. If the user clicks the Cancel button or the window close button (X), then MATLAB returns 0 to all output arguments.

___ = uiputfile(filter) displays only those files with extensions that match filter. On some platforms uiputfile also displays any files that do not match filter, but they are dimmed. The uiputfile function appends All Files to the list of file types.

If filter is a file name, then uiputfile displays the file name in the File name field and uses the file extension as the default filter.

Use this syntax with any of the output argument combinations in the previous syntaxes.

___ = uiputfile(filter,title) opens a dialog box with the specified title. To filter using the default file filter, but specify a custom title, use empty quotes for the filter value.

file = uiputfile('','Select a File')

___ = uiputfile(filter,title,defname) opens a dialog box where the file name specified by defname appears in the File name field.

Examples

Specify File Name and Type

Create a dialog box and specify the filter as animinit.m. When the code runs, the File name field contains the specified file name and the Save as type field is set to *.m.

[file,location,indx] = uiputfile('animinit.m');

Display Several File Types as Filters

Display several file types in the Save as type list box, by separating each file extension in the filter input argument with a semicolon.

filter = {'*.m';'*.slx';'*.mat';'*.*'};
[file, location] = uiputfile(filter);

Specify File Types with Custom Descriptions

Create a list of file types and give them descriptions that are different from the defaults by using a cell array for the filter input value. Associate multiple file types with the 'MATLAB Files' and 'Models' descriptions.

The first column of the input filter cell array contains the file extensions, and the second contains the descriptions of the file types. For example, the first entry of column 1 contains several extensions separated by semicolons. These file types are all associated with the description 'MATLAB Files'.

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

Specify Dialog Box Title and File Type

Create a dialog box entitled 'Workspace File' with the Save as type field set to MAT-files.

[file,location] = uiputfile('*.mat','Workspace File');

Specify Filter and Default File Name

Specify a wildcard for the filter and a default file name to display a default file in the File name field, but enable users to view files of all types in the dialog box.

[file,location,indx] = uiputfile('*.*','File Selection','test.m');

Display User Action in Command Window

Open the Select a File to Write dialog box, and then select a file. MATLAB automatically opens a Confirm Save As dialog box.

• If you click OK in the confirmation dialog box, then MATLAB closes both dialog boxes and displays your selection in the Command Window.

• If you click No in the confirmation dialog box and click Cancel in the Select a File to Write dialog box, then the Command Window displays User clicked Cancel.

[file,location] = uiputfile('*.m');
if isequal(file,0) || isequal(location,0)
   disp('User clicked Cancel.')
else
   disp(['User selected ',fullfile(location,file),...
         ' and then clicked Save.'])
end

Input Arguments

filter — File filter

All MATLAB Files (default) | character vector | cell array of character vectors | string array

File filter, specified as a character vector, a cell array of character vectors, or a string array. The table below lists the types of inputs you can pass to the filter argument and the corresponding behavior of the dialog box.

Input	Behavior	Examples
File name	The file name appears in the File name field of the dialog box. The extension of the file is the default filter value. If the file name contains a path, the dialog box opens to the specified folder. Otherwise, it opens to the current folder. If the specified folder does not exist, then uiputfile opens the dialog box to the current folder.	'icon.png' 'C:\Documents\icon.png' '..\icon.png'
Folder	The dialog box displays the contents of the folder. The File name field is empty, and no filter applies. To specify a folder name, the last character of filter must be either a backslash (\) or a slash (/). If the specified folder does not exist, then uiputfile opens the dialog box to the current folder.	'C:\Documents\'
File extension filters	The dialog box displays only the files with a matching file extension. To create a filter with more than one file extension, specify the extensions within a single character vector or string, separated by a semicolon (;). To allow users to choose between multiple filters, specify a cell array or string array with an item for each filter. The filters appear in the filter field drop-down menu in the dialog box. If MATLAB recognizes the list of file extensions in a filter, it displays a standard description in the filter field. MATLAB automatically adds an All Files filter to the bottom of the filter list.	'*.m' {'*.m';'*.mlx'} {'*.m;*.mlx';'*.png;*.jpeg'}
File extension filters with descriptions	The dialog box displays the extensions with their descriptions in the filter field. Users can choose between filters. To display filter descriptions, specify two columns in the cell array or string array. The first column contains a list of file extensions. The second column contains a corresponding list of descriptions. These descriptions replace standard descriptions in the filter field. A description cannot be empty. MATLAB automatically adds an All Files filter to the bottom of the filter list.	{'*.m;*.mlx','Code files';'*.png;*.jpeg','Image files'}

If the file filter contains a path, that path can contain these characters:

• .

• ..

• \

• /

• ~

For example, '../*.m' lists all code files with a .m extension in the folder above the current folder.

To use the default file filter, specify empty quotes for the filter value. For example, to use the default file filter and specify a custom title, use this syntax:

uiputfile('','Select File')

title — Dialog box title

Select File to Write (default) | character vector | string scalar

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

To use the default dialog box title, use empty quotes for the title value. For example, to specify a file filter, the default title, and a File name field value, use this syntax:

uiputfile('*.m','','myFile.m')

Example: 'File Selector'

defname — Default file name

character vector | string scalar

Default file name to display in the File name field when the dialog box opens, specified as a character vector or a string scalar.

The value of defname can include a path or consist of a path only. You can use any of these characters in the defname argument:

.

..

\

/

~

To specify defname as a folder only, specify the last character in defname as a backslash \ or a forward slash /. When you do so, MATLAB opens the dialog box in the folder specified by the path. If you specify a path that does not exist, then MATLAB opens the dialog box in the current folder.

Example: 'myfile.m'

Example: '../myfile.m'

Output Arguments

file — User-specified file name

character vector | string scalar

User-specified file name, returned as a character vector or string scalar. The user can specify the file name by selecting it in the dialog box, typing a file name in the File name field, or accepting the default file name (if you provide one). If the user cancels the dialog box, then MATLAB returns file as 0.

location — Path to the user-specified file name

character vector | 0

Path to the user-specified file name, returned as a character vector or 0. If the user cancels the dialog box, then MATLAB returns path as 0.

indx — Save as type index

integer

Save as type index, returned as an integer. As shown in this figure, the index corresponds to the Save as type row selection. Indexing starts at 1.

If the user clicks the Cancel button or the dialog box close button (X), or if the file does not exist, then MATLAB returns indx as 0.

More About

Modal Dialog Box

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

File Dialog Boxes in Web Apps

When you deploy an app as a web app (requires MATLAB Compiler™), there are some differences in how uiputfile accesses the app user's local file system and how the dialog box appears. These differences exist because the app is hosted on a server rather than running on the app user's local machine.

The function creates a dialog box in the app that lets an app user enter a filename and format.

[file,loc] = uiputfile;

When a user clicks Download, uiputfile returns the specified filename and a temporary file location that the web app can access. You can use this information to write data to the file. For example, if the file is a text file, you can construct the path to the file using the file and loc outputs and then write lines of text to the file. When you write to the file, the web app downloads a copy of the file to the user's system. The app downloads the file to the default download location of the web browser running the app.

f = fullfile(loc,file);
lines = ["Line 1","Line 2"];
writelines(lines,f);

Avoid writing to the file in a loop, which can trigger multiple file downloads. Instead, prepare all of the data to write, and then write to the file using a single operation.

Because the deployed web app is hosted on a server, you cannot specify the default path or filename when you call uiputfile from a web app.

Tips

• To write data to a user-specified file and location using MATLAB and MATLAB toolbox functions, use the path and file name that uiputfile returns. For example:

  • fprintf for writing data to a text file.

  • imwrite for writing an image to a graphics file.

  • xlswrite for writing a matrix to a Microsoft^® Excel^® spreadsheet. For example, this code creates a matrix, A, creates a dialog box to get a file name from the user, builds a full file name from the returned values, and then writes the matrix to the user-specified Excel file.

    A = [12.7 5.02 -98 63.9 0 -.2 56];
    [file,location] = uiputfile('*.xlsx');
    filename = fullfile(location,file);
    xlswrite(filename,A);
    

Version History

Introduced before R2006a