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. If you click Cancel (or the window's close box), uigetfile returns 0.

[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. 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 the window's close box, 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 the window's close box, 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.

    Note:   The visual characteristics of the dialog box depend on the operating system that is running MATLAB.

Examples

This dialog box lists all MATLAB code files in the current directory. uigetfile returns the name and path to the file you select.

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

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.

[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');

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.

Was this topic helpful?