MATLAB Function Reference

uigetfile - Open standard dialog box for retrieving files

Syntax

uigetfile [FileName,PathName,FilterIndex] = uigetfile(FilterSpec) [FileName,PathName,FilterIndex] = uigetfile(FilterSpec,DialogTitle) [FileName,PathName,FilterIndex] = uigetfile(FilterSpec,DialogTitle,DefaultName) [FileName,PathName,FilterIndex] = uigetfile(...,'MultiSelect',selectmode)

Description

uigetfile displays a modal dialog box that lists files in the current directory and enables the user to select or type the name of a file to be opened. If the filename is valid and if the file exists, uigetfile returns the filename when the user clicks Open. Otherwise uigetfile displays an appropriate error message from which control returns to the dialog box. The user can then enter another filename or click Cancel. If the user clicks Cancel or closes the dialog window, uigetfile returns 0.

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

[FileName,PathName,FilterIndex] = uigetfile(FilterSpec) displays only those files with extensions that match FilterSpec. The uigetfile 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.

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 Files of type field. A description cannot be an empty string. Example 2 and Example 3 illustrate use of a cell array as FilterSpec.

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

After the user clicks Open and if the filename exists,uigetfile returns the name of the file in FileName and its path in PathName. If the user clicks Cancel or closes the dialog window, 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 Cancel or closes the dialog window, FilterIndex is set to 0.

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

uigetfile('',DialogTitle)

[FileName,PathName,FilterIndex] = uigetfile(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, uigetfile 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, uigetfile opens the dialog box in the current directory.

[FileName,PathName,FilterIndex] = uigetfile(...,'MultiSelect',selectmode) sets the multiselect mode to specify if multiple file selection is enabled for the uigetfile dialog. Valid values for selectmode are 'on' and 'off' (default). If 'MultiSelect' is 'on' and the user selects more than one file in the dialog box, then FileName is a cell array of strings, each of which represents the name of a selected file. Filenames in the cell array are in the sort order native to your platform. Because multiple selections are always in the same directory, PathName is always a string that represents a single 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 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 that enables the user to retrieve a file. The statement lists all MATLAB M-files within a selected directory. The name and path of the selected file are returned in FileName and PathName. Note that uigetfile appends All Files(*.*) to the file types when FilterSpec is a string.

[FileName,PathName] = uigetfile('*.m','Select the M-file');

The dialog box is shown in the following figure.

Example 2

To create a list of file types that appears in the Files of type list box, separate the file extensions with semicolons, as in the following code. Note that uigetfile displays a default description for each known file type, such as "Simulink Models" for .mdl files.

[filename, pathname] = ...
     uigetfile({'*.m';'*.mdl';'*.mat';'*.*'},'File Selector');

Example 3

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] = uigetfile( ...
{'*.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 (*.*)'}, ...
   'Pick a file');

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 4

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

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

Example 5

This example creates a list of file types and gives them descriptions that are different from the defaults, then enables multiple file selection. The user can select multiple files by holding down the Shift or Ctrl key and clicking on a file.

[filename, pathname, filterindex] = uigetfile( ...
{  '*.mat','MAT-files (*.mat)'; ...
   '*.mdl','Models (*.mdl)'; ...
   '*.*',  'All Files (*.*)'}, ...
   'Pick a file', ...
   'MultiSelect', 'on');

Example 6

This example uses the DefaultName argument to specify a start path and a default filename for the dialog box.

uigetfile({'*.jpg;*.tif;*.png;*.gif','All Image Files';...
          '*.*','All Files' },'mytitle',...
          'C:\Work\myfile.jpg')