uiputfile

Open dialog box for saving files

collapse all in page

Syntax

file = uiputfile
[file,path] = uiputfile
[file,path,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,path] = uiputfile returns the selected or specified file path to path. If the user cancels the dialog box, then MATLAB returns 0 to both output arguments.

[file,path,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.

example

___ = 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.

example

___ = 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')

example

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

Examples

collapse all

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,path,indx] = uiputfile('animinit.m');

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, path] = uiputfile(filter);

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 (*.m,*.mlx,*.fig,*.mat,*.slx,*.mdl)'.

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

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

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

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,name,path] = uiputfile('*.*','File Selection','test.m');

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,path] = uiputfile('*.m');
if isequal(file,0) || isequal(path,0)
   disp('User clicked Cancel.')
else
   disp(['User selected ',fullfile(path,file),...
         ' and then clicked Save.'])
end

Input Arguments

collapse all

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'

File type filter specification, specified as a character vector, a cell array of character vectors, or a string array. MATLAB appends All Files to the list of file types presented in the dialog box. The filter value can include the wildcard character (*).

Example: *.m

Example: 'MATLAB Files (*.m,*.mlx,*.fig,*.mat,*.slx,*.mdl)'

Dialog box title, specified as a character vector or string scalar. To filter using the default file filter, but specify a custom title, use empty quotes for the filter value. For example:

uiputfile(' ','Select File')

Example: 'File Selector'

Output Arguments

collapse all

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.

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

  • If the user types a file name in the dialog box File name field that includes the asterisk character (*) or the question mark character (?), then MATLAB does not respond to clicking the Save button. The dialog box remains open until the user cancels it or removes the wildcard or question mark characters. This restriction applies to all platforms, even on platforms that permit these characters in file names.

  • If the user specifies an existing file name, then a warning dialog box opens stating that the file already exists and provides an option to replace the file.

    • If the user clicks Yes in the warning dialog box, then MATLAB replaces the existing file and returns the file name.

    • If the user clicks No in the warning dialog box, then control returns to the uiputfile dialog box, enabling the user to specify a different file name.

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

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

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

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

  • 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,path] = uiputfile('*.xlsx');
filename = fullfile(path,file);
xlswrite(filename,A);

See Also

| | |

Introduced before R2006a

MATLAB Documentation

Support