Main Content

uigetfile

Open file selection dialog box

collapse all in page

Syntax

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

example

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

example

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

example

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

example

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

example

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

collapse all

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 path and file output values.

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

File selection dialog box. The visible files are .m files and the file filter drop-down reads (*.m).

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

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,path,indx] = uigetfile;
if isequal(file,0)
   disp('User selected Cancel')
else
   disp(['User selected ', fullfile(path, file),... 
         ' and filter index: ', num2str(indx)])
end

File selection dialog box. The dialog shows files with various extensions, and the file filter drop-down contains the extensions types.

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

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

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

File selection dialog box. The visible files are .m files and the file filter drop-down reads (*.m).

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,path] = uigetfile({'*.m';'*.slx';'*.mat';'*.*'},...
                          'File Selector');

File selection dialog box. The file filter drop-down has an option for each specified file extension, and (*.m) is selected. The visible files are .m files.

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,path,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');

File selection dialog box. The file filter drop-down lists the specified file filter descriptions. The visible files are .m and .fig files.

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,path] = uigetfile('*.png',...
               'Select an icon file','icon.png')

File selection dialog box. The title of the dialog box is Select an icon file and the default file name is icon.png. The visible files are .png files.

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,path] = uigetfile('C:\Documents\Work\icon.png',...
                        'Select an Image File')

File selection dialog box. The title of the dialog box is Select an Image File. The dialog is open to the C:\Documents\Work folder and the default file name is icon.png. The visible files are .png files.

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,path] = uigetfile({'*.png';'*.m'},...
               'Select a file','C:\Documents\AppBuildingFiles\')

File selection dialog box. The title of the dialog box is Select a file. The dialog is open to the C:\Documents\AppBuildingFiles folder and the file filter drop-down contains a .png and a .m filter.

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,path] = uigetfile('*.m',...
   'Select One or More Files', ...
   'MultiSelect', 'on');

File selection dialog box. The title of the dialog box is Select One or More Files. Multiple files in the dialog box are selected.

Input Arguments

collapse all

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.

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

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"

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\'

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

collapse all

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.

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.

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.

File name field and drop-down list. The drop-down list contains multiple options for file extension filters.

If the user clicks the Cancel button or the window close button (X), then MATLAB returns an index value of 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

  • 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: listed here.

    • 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,path] = uigetfile('*.m');
selectedfile = fullfile(path,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

See Also

| |