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.

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

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

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

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,path] = 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 defname input argument.

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

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

Input Arguments

collapse all

File filter, specified as a character vector, cell array of character vectors, or a string array.

  • If filter is a file name, then that file name appears in the File name field. The extension of the file is the default filter value. (The filter field is unlabeled and appears to the right of the File name field.)

  • The filter can include a path. That path can contain the following characters:

    • .

    • ..

    • \

    • /

    • ~

    For example, '../*.m' lists all code files with a .m extension in the folder above the current folder.

  • 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

  • If the specified path does not exist, then uigetfile opens the dialog box in the current folder.

  • If filter is a folder name, then MATLAB displays the contents of that 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 filter is a cell array of character vectors or a string array, 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 filter field. A description cannot be empty.

Example: 'myfile.m'

Example: '../myfile.m'

Example: '../..'

Dialog box title, specified as a character vector.

Example: 'Select a File'

Default File name field value, 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 DefaultName 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.

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.

See Also

| |

Introduced before R2006a

MATLAB Documentation

Support