uigetfile

Open file selection dialog box

Syntax

file = uigetfile

[file,location] = uigetfile

[file,location,indx] = uigetfile

___ = uigetfile(filter)

___ = uigetfile(filter,title)

___ = uigetfile(filter,title,defname)

___ = uigetfile(___,'MultiSelect',mode)

Description

file = uigetfile opens a modal dialog box that lists files in the current folder. It enables a user to select or enter the name of a file. If the file exists and is valid, uigetfile returns the file name when the user clicks Open. If the user clicks Cancel or the window close button (X), uigetfile returns 0.

[file,location] = uigetfile returns the file name and path to the file when the user clicks Open. If the user clicks Cancel or the window close button (X), then uigetfile returns 0 for both of the output arguments.

[file,location,indx] = uigetfile returns the index of the filter selected in the dialog box when the user clicks Open.

___ = uigetfile(filter) specifies a file extension by which files displayed in the dialog box are filtered. Use this syntax with any of the output argument combinations in the previous syntaxes.

Typically, only files with a matching file extension are displayed. On some platforms, uigetfile displays files that do not match the filter, but dims those file names. If the filter is missing or empty, uigetfile uses the default list of file types (for example, all MATLAB^® files).

___ = uigetfile(filter,title) specifies a dialog box title. To filter using the default file filter, but specify a custom title, use empty quotes for the filter value. For example:

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

___ = uigetfile(filter,title,defname) specifies a default file name for the File name field or a default folder that the dialog opens to.

___ = uigetfile(___,'MultiSelect',mode) specifies whether a user can select multiple files. Set the mode to 'on' to enable multifile selection. By default it is set to 'off'.

Windows^® libraries can span multiple folders.

Note

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 uigetfile function, those operating systems do not display the title.

Examples

Display Full File Specification

Display the full file specification of the file selected in the dialog box. Use the disp and fullfile functions to add explanatory text and concatenate the location and file output values.

[file,location] = uigetfile('*.m');
if isequal(file,0)
   disp('User selected Cancel');
else
   disp(['User selected ', fullfile(location,file)]);
end

User selected H:\Documents\MyCode\surf.m

Display Filter Index Selection

Display the filter index selection with explanatory text in the Command Window. Use the num2str function to convert the numeric filter index value (indx) to a character array. Doing so makes the value valid input to the disp function.

[file,location,indx] = uigetfile;
if isequal(file,0)
   disp('User selected Cancel')
else
   disp(['User selected ', fullfile(location,file),... 
         ' and filter index: ', num2str(indx)])
end

User selected H:\Documents\MyCode\peaks.fig and filter index: 3

Filter Files by Extension

Display only files with a .m extension in the dialog box by specifying '*. m' as the filter input argument.

[file,location] = uigetfile('*.m');

Specify Filter List and Dialog Box Title

Create a list of file extensions in the file filter drop-down list. Pass the filter input argument as a cell array of character vectors and separate the file extensions with semicolons.

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

Specify Filters and Filter Descriptions

Create a list of file extensions and give them descriptions by passing the filter input argument as a cell array of character vectors. The first column of the cell array contains the file extensions, and the second contains custom descriptions of the file types. This example also associates multiple file types with the 'MATLAB Files' and 'Models' descriptions.

[file,location,indx] = uigetfile( ...
{'*.m;*.mlx;*.fig;*.mat;*.slx;*.mdl',...
    'MATLAB Files (*.m,*.mlx,*.fig,*.mat,*.slx,*.mdl)';
   '*.m;*.mlx','Code files (*.m,*.mlx)'; ...
   '*.fig','Figures (*.fig)'; ...
   '*.mat','MAT-files (*.mat)'; ...
   '*.mdl;*.slx','Models (*.slx, *.mdl)'; ...
   '*.*',  'All Files (*.*)'}, ...
   'Select a File');

Specify Default File Name

To display a default file name in the File name field when the dialog box opens, pass the file name as the defname input argument

 [file,location] = uigetfile('*.png',...
               'Select an icon file','icon.png')

Specify Default Path and File

To display a default path and file name in the File name field when the dialog box opens, pass the full file name as the filter input argument.

[file,location] = uigetfile('C:\Documents\Work\icon.png',...
                        'Select an Image File')

Specify Filters and Default Folder

Create a list of file extensions by passing the filter input argument as a cell array of character vectors. Specify the folder that the dialog box opens to.

[file,location] = uigetfile({'*.png';'*.m'},...
               'Select a file','C:\Documents\AppBuildingFiles\')

Enable Multifile Selection

Enable multifile selection by setting the 'Multiselect' option to 'on'. Users can select multiple files by holding down the Shift or Ctrl key and clicking file names.

[file,location] = uigetfile('*.m',...
   'Select One or More Files', ...
   'MultiSelect', 'on');

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 uigetfile 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 uigetfile 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 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. To create a filter with more than one file extension, specify the extensions within a single character vector or string, separated by a semicolon (;).	'*.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.	{'*.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:

uigetfile('','Select File')

Note

If you or a user includes either an asterisk (*) or a question mark (?) in a file name, then uigetfile does not respond to clicking Open. The dialog box remains open until the user clicks Cancel or removes the wildcard characters from the name. This restriction applies to all platforms, even to file systems that permit these characters in file names.

title — Dialog box title

Select File to Open (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:

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

Example: "Select a File"

defname — Default file name

'' (default) | 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 defname value can specify a path, or a path and a file name.

• If you specify a path, it can contain the following characters:

  • .

  • ..

  • \

  • /

  • ~

• To specify a folder name only, make the last character of the defname value either a backslash (\) or a slash (/).

Example: 'myfile.mat'

Example: 'C:\Documents\my_MATLAB_files'

Example: '..\myfile.mat'

Example: '..\Documents\'

mode — Multiselect mode

'off' (default) | 'on'

Multiselect mode, specified as 'on' or 'off'. If multiselect mode is off, then a user can select one file only. If multiselect mode is on, then a user can select multiple files. If a user selects multiple files, then they must be in the same folder; otherwise MATLAB displays a warning dialog box. Microsoft^® Windows libraries can span multiple folders.

Output Arguments

file — File name

character vector | cell array of character vectors

File name that the user specified in the dialog box, returned as a character vector or a cell array of character vectors.

A cell array of character vectors is returned when 'MultiSelect' is set to 'on' and a user selects multiple files. Each array element contains the name of a selected file. File names in the cell array are sorted in the order that the user's platform uses. If a user selects multiple files, they must be in the same folder, otherwise MATLAB displays a warning dialog box.

If the user clicks the Cancel button or the window close button (X), then MATLAB returns the file value as 0.

location — Path to specified file

character vector

Path to the specified file or files, returned as a character vector.

If the user clicks the Cancel button or the window close button (X), then MATLAB returns the file value as 0.

indx — Selected filter index

integer

Selected filter index, returned as an integer.

The filter is the unlabeled dialog box control to the right of the File name field in the dialog box. The filter index value corresponds to the item selected in the filter drop-down list. The index of the first row is 1.

If the user clicks the Cancel button or the window close button (X), then MATLAB returns an index value of 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 uigetfile 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 select a file from their local system.

[file,loc] = uigetfile;

When a user drops or selects a file from their local system, the web app uploads a copy of the file to a temporary folder, and uigetfile returns the file location. You can access a copy of the file from this location. For example, if the file is an image, you can construct the path to the file using the file and loc outputs and then read the image from the file.

f = fullfile(loc,file);
A = imread(f);

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

Tips

• Use the path and file name that uigetfile returns to open, read, or analyze the file using various input and output functions in MATLAB and MATLAB toolboxes. For example:

  • imread for reading images.

  • xlsread for reading Microsoft Excel files.

  • open, edit, or run with MATLAB code files. For example, this code creates a dialog box to get a MATLAB code file name from the user, builds a full file name from the returned values, and then runs the user-specified code file.

    [file,location] = uigetfile('*.m');
    selectedfile = fullfile(location,file);
    run(selectedfile);
    

Alternative Functionality

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

Version History

Introduced before R2006a