Documentation Center

  • Trial Software
  • Product Updates

uigetfile

Open standard dialog box for retrieving files

Syntax

filename = 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

filename = uigetfile displays a modal dialog box that lists files in the current folder and enables you to select or enter the name of a file. If the file name is valid and the file exists, uigetfile returns the file name as a string when you click Open. Otherwise uigetfile displays an appropriate error message, after which control returns to the dialog box. You can then enter another file name or click Cancel. If you click Cancel or close the dialog window, uigetfile returns 0.

    Note:   Successful execution of uigetfile does not open a file; it only returns the name of an existing file that you identify.

[FileName,PathName,FilterIndex] = uigetfile(FilterSpec) displays only those files with extensions that match FilterSpec. On some platforms uigetfile also displays in gray the files that do not 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 file name, that file name displays, selected in the File name field. The extension of the file is the default filter.

  • FilterSpec can include a path. That path can contain '.','..', \, '/', or '~'. For example, '../*.m' lists all code files in the folder above the current folder.

  • If FilterSpec is a folder name, uigetfile displays the contents of that folder, the File name field is empty, and no filter applies. To specify a folder name, make the last character of FilterSpec either '\' or '/'.

  • If FilterSpec is a cell array of strings, it can include two columns. 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. The second and third examples illustrate use of a cell array as FilterSpec.

If FilterSpec is missing or empty, uigetfile uses the default list of file types (for example, all MATLAB® files).

After you click Open and if the file name exists,uigetfile returns the name of the file in FileName and its path in PathName. If you click Cancel or close the dialog window, the function sets FileName and PathName to 0.

FilterIndex is the index of the filter selected in the dialog box. Indexing starts at 1. If you click Cancel or close the dialog window, the function sets FilterIndex 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 file name 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 folder specified by the path. You can use '.','..', \, or '/' in the DefaultName argument. To specify a folder name, make the last character of DefaultName either '\' or '/'. If the specified path does not exist, uigetfile opens the dialog box in the current folder.

[FileName,PathName,FilterIndex] = uigetfile(...,'MultiSelect',selectmode)opens the dialog box in multiselect mode. Valid values for selectmode are 'on' and 'off' (the default, which allows single selection only). If 'MultiSelect' is 'on' and you select more than one file in the dialog box, then FileName is a cell array of strings. Each array element contains the name of a selected file. File names in the cell array are sorted in the order your platform uses. If you select multiple files, they must be in the same folder, otherwise MATLAB displays a warning dialog box. Be aware that Microsoft® Windows® libraries can span multiple folders. PathName is a string identifying the folder containing the files.

If you include either of the wildcard characters, '*' or '?', in a file name, uigetfile does not respond to clicking Open. 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.

For Windows platforms, the dialog box is the Windows dialog box native to your platform. Depending on your version of Windows, dialogs you see can differ from the figures shown in following examples.

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

Examples

The following statement displays a dialog box for retrieving a file. The dialog box lists all MATLAB code files within a selected directory. uigetfile returns the name and path of the selected file in FileName and PathName. uigetfile appends All Files(*.*) to the file types when FilterSpec is a string.

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

The following figure shows the dialog box with the file type drop-down list open.

 

To create a list of file types that appears in the file type drop-down list, separate the file extensions with semicolons, as in the following code. uigetfile displays a default description for each known file type, such as "Model files" for Simulink® .slx and .mdl files.

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

 

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' and 'Models' descriptions.

[filename, pathname] = uigetfile( ...
{'*.m;*.fig;*.mat;*.slx;*.mdl',...
 'MATLAB Files (*.m,*.fig,*.mat,*.slx,*.mdl)';
   '*.m',  'Code files (*.m)'; ...
   '*.fig','Figures (*.fig)'; ...
   '*.mat','MAT-files (*.mat)'; ...
   '*.mdl;*.slx','Models (*.slx, *.mdl)'; ...
   '*.*',  'All Files (*.*)'}, ...
   'Pick a file');

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

 

The following code lets you select a file and then displays a message in the Command Window that summarizes the result.

[filename, pathname] = uigetfile('*.m', 'Select a MATLAB code file');
if isequal(filename,0)
   disp('User selected Cancel')
else
   disp(['User selected ', fullfile(pathname, filename)])
end
 

This code creates a list of file types and gives them descriptions that are different from the defaults. It also enables multiple-file selection. Select multiple files by holding down the Shift or Ctrl key and clicking on additional file names.

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

As mentioned previously, uigetfile does not open the file or files you select.

 

You can use the DefaultName argument to specify a start path and a default file name for the dialog box.

uigetfile({'*.jpg;*.tif;*.png;*.gif','All Image Files';...
          '*.*','All Files' },'mytitle',...
          'C:\myfiles\my_examples\gbtools\setpos1.png')

Alternatives

Use the dir function to return a filtered or unfiltered list of files in your current folder or a folder you specify. dir also can return file attributes.

See Also

| |

Was this topic helpful?