chooseDialog

Class: matlab.uitest.TestCase
Namespace: matlab.uitest

Make a selection in dialog box

Since R2024b

expand all in page

Syntax

chooseDialog(testCase,dialogType,fig,option)

chooseDialog(testCase,dialogType,fig,fcn,option)

dialogData = chooseDialog(testCase,dialogType,fcn)

dialogData = chooseDialog(testCase,dialogType,fcn,Name=Value)

Description

chooseDialog makes a selection in an app or system dialog box in a test. For more information about app and system dialog boxes and their blocking behavior, see Summary of Dialog Boxes.

App Dialog Boxes

chooseDialog(testCase,dialogType,fig,option) selects option in the frontmost nonblocking app dialog box of the specified type in the figure window.

example

chooseDialog(testCase,dialogType,fig,fcn,option) makes a selection in the frontmost blocking app dialog box of the specified type. Because a blocking dialog box prevents additional commands from running while it is open, it must be created as part of the method call by using the fcn function handle.

When you use this syntax, the method first creates a blocking app dialog box by invoking the specified function handle. The method then closes the dialog box by selecting the specified option in the dialog box, which allows code execution to continue.

example

System Dialog Boxes

dialogData = chooseDialog(testCase,dialogType,fcn) makes the default selection in the system dialog box of the specified type and returns information about the interaction with the dialog box. Because a system dialog box is blocking, it must be created as part of the method call by using the fcn function handle. (since R2026a)

example

dialogData = chooseDialog(testCase,dialogType,fcn,Name=Value) specifies options using one or more name-value arguments. For example, dialogData = chooseDialog(testCase,"uigetdir",@uigetdir,Folder="myFolder") selects a folder named myFolder in a folder selection dialog box that opens to the current folder. (since R2026a)

example

Input Arguments

expand all

`testCase` — Test case
`matlab.uitest.TestCase` object

Test case, specified as a matlab.uitest.TestCase object.

`dialogType` — Type of dialog box
`"uiconfirm"` | `"uigetdir"` | `"uigetfile"` | `"uiputfile"`

Type of the app or system dialog box, specified as one of the values in this table. Specify the value that corresponds to the name of the function used to create the dialog box.

Dialog Box Type	Creation Function	Description	Category	Blocking Behavior
`"uiconfirm"`	`uiconfirm`	Confirmation dialog box	App	Nonblocking if created by a call to `uiconfirm` with no output Blocking if created by a call to `uiconfirm` with an output
`"uigetdir"` (since R2026a)	`uigetdir`	Folder selection dialog box	System	Blocking
`"uigetfile"` (since R2026a)	`uigetfile`	File selection dialog box	System	Blocking
`"uiputfile"` (since R2026a)	`uiputfile`	Dialog box for saving files	System	Blocking

For more information about app and system dialog boxes, see Summary of Dialog Boxes.

Data Types: string | char

`fig` — Target figure for app dialog box
`matlab.ui.Figure` object

Target figure for the app dialog box, specified as a matlab.ui.Figure object. The figure must be created with the uifigure function.

`option` — App dialog box option to select
string scalar | character vector | positive integer scalar

App dialog box option to select, specified as a string scalar, character vector, or positive integer scalar. You can use a string scalar or character vector to specify the button label for the option or a positive integer scalar to specify the index of the option.

Example: "Proceed"

Example: 1

`fcn` — Code that creates blocking dialog box
function handle

Code that creates the blocking dialog box, specified as a function handle. The function handle must create a blocking dialog box of type dialogType. For an app dialog box, the function handle must create the dialog box in the target figure fig.

Example: @() createBlockingAppDialog(fig)

Example: @uigetdir

Name-Value Arguments

expand all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: dialogData = chooseDialog(testCase,"uigetdir",@uigetdir,Folder="myFolder")

`Folder` — Name of folder to select
string scalar | character vector

Since R2026a

Name of the folder to select in the dialog box created with the uigetdir function, specified as a string scalar or character vector. The value can be a path relative to the current folder or an absolute path. The specified folder must exist.

By default, the method selects the folder that the folder selection dialog box opens to. For example, dialogData = chooseDialog(testCase,"uigetdir",@() uigetdir(matlabroot,"MATLAB Root Folder")) selects the MATLAB^® root folder. Specify the Folder name-value argument to select a folder within the target folder instead.

Example: dialogData = chooseDialog(testCase,"uigetdir",@uigetdir,Folder="myFolder") selects a folder named myFolder in a folder selection dialog box that opens to the current folder.

Example: dialogData = chooseDialog(testCase,"uigetdir",@() uigetdir(matlabroot,"MATLAB Root Folder"),Folder=fullfile(matlabroot,"bin")) selects the bin folder within the MATLAB root folder.

`File` — Name of file to select
string vector | character vector | cell vector of character vectors

Since R2026a

Name of the file to select in the dialog box created with the uigetfile or uiputfile function, specified as a string vector, character vector, or cell vector of character vectors. The value can be a path relative to the current folder or an absolute path and depends on the type of the dialog box:

If dialogType is "uigetfile", then specify the name of one or more existing files. You can specify multiple filenames only if the dialog box supports multiple file selection.
If dialogType is "uiputfile", then specify the name of a single file. The file does not need to exist, but you must have write permission in the folder to save the file.

By default, the method selects the default file in the dialog box. For example, dialogData = chooseDialog(testCase,"uigetfile",@() uigetfile("*.m","Select a File","default.m")) selects the default file named default.m in the specified file selection dialog box. Specify the File name-value argument to select nondefault files instead.

Example: dialogData = chooseDialog(testCase,"uiputfile",@uiputfile,File="myFile.m") selects a file named myFile.m in a dialog box for saving files that opens to the current folder.

Example: dialogData = chooseDialog(testCase,"uigetfile",@() uigetfile("*.m","Select One or More Files",MultiSelect="on"),File=["file1.m" "file2.m"]) selects the files named file1.m and file2.m in a dialog box that supports multiple file selection.

`Filter` — File filter to select
`"All MATLAB Files"` (default) | string scalar | character vector | positive integer scalar

Since R2026a

File filter to select in the dialog box created with the uigetfile or uiputfile function, specified as a string scalar, character vector, or positive integer scalar. You can use a string scalar or character vector to specify the file extension filter or filter description, or a positive integer scalar to specify the file filter index.

By default, a dialog box of type "uigetfile" or "uiputfile" displays all the MATLAB files. Specify the Filter name-value argument to filter the files displayed in the dialog box when making a file selection. For example, chooseDialog(testCase,"uigetfile",@uigetfile,File="testdata.mat",Filter="*.mat") selects a file named testdata.mat in a dialog box that displays only the MAT files from the current folder.

Example: Filter="*.mat" displays only the MAT files in the dialog box.

Example: Filter="MATLAB Apps" displays only the MATLAB app files (*.mlapp) in the dialog box.

Example: Filter=3 displays only the files that match the third filter in the dialog box.

Output Arguments

expand all

`dialogData` — Information about system dialog box after interaction
`GetDirDialogData` object | `GetFileDialogData` object | `PutFileDialogData` object

Since R2026a

Information about the system dialog box after programmatic interaction, returned as a GetDirDialogData, GetFileDialogData, or PutFileDialogData object. The type of returned object and its contents depend on the type of system dialog box.

Unlike framework interactions with app dialog boxes, which provide visual feedback, interactions with system dialog boxes do not display any graphical output. To get information about the system dialog box under test, inspect the properties of dialogData.

Attributes

Sealed true

To learn about attributes of methods, see Method Attributes.

Examples

expand all

Select Option in Nonblocking App Dialog Box

Open Live Script

Programmatically select an option in a nonblocking confirmation dialog box in front of a figure.

Create a UI figure with a push button that creates a modal confirmation dialog box when clicked. To program the button behavior, specify its ButtonPushedFcn callback property. See the code of the callback function buttonCallback, which creates a confirmation dialog box, at the end of this example.

fig = uifigure;
b = uibutton(fig,Text="Close",ButtonPushedFcn=@buttonCallback);

Create a test case for interactive testing.

testCase = matlab.uitest.TestCase.forInteractiveUse;

Test a press gesture on the button. The gesture executes the buttonCallback function, which creates a confirmation dialog box in the figure. The confirmation dialog box is nonblocking and lets you run additional commands while it is open.

testCase.press(b)

Programmatically select the "Proceed" option in the dialog box by using the chooseDialog method. The dialog box closes. Due to the dialogCallback function that executes when the dialog box closes, the figure behind the dialog box also closes after the "Proceed" option is selected.

testCase.chooseDialog("uiconfirm",fig,"Proceed")

Callback Functions

This code shows the callback functions used in this example:

The buttonCallback function executes when the button in the figure is clicked. The function creates a confirmation dialog box in the figure and specifies the dialogCallback function as the dialog box CloseFcn callback.
The dialogCallback function executes when the dialog box closes. Selecting the "Proceed" option in the dialog box closes the figure. Selecting the "Cancel" option in the dialog box does not affect the figure.

function buttonCallback(src,~)
uiconfirm(src.Parent,"Close this figure?","Confirm Close", ...
    Icon="warning", ...
    Options=["Proceed" "Cancel"], ...
    CloseFcn=@dialogCallback)
end

function dialogCallback(~,event)
switch event.SelectedOption
    case "Proceed"
        close(event.Source)
    case "Cancel"
        return
end
end

Select Option in Blocking App Dialog Box

Open Live Script

Programmatically select an option in a blocking confirmation dialog box in front of a figure.

fig = uifigure;
b = uibutton(fig,Text="Close",ButtonPushedFcn=@buttonCallback);

Create a test case for interactive testing.

testCase = matlab.uitest.TestCase.forInteractiveUse;

Testing a press gesture on the button executes the callback, which creates a blocking confirmation dialog box in the figure. Programmatically select the "Proceed" option in the dialog box by using the chooseDialog method. This code first creates the blocking dialog box by invoking the specified function handle, which presses the button in the figure. The method then closes the dialog box by selecting the "Proceed" option, which allows code execution to continue. Due to the callback function used in this example, the figure behind the dialog box also closes after the "Proceed" option is selected.

testCase.chooseDialog("uiconfirm",fig,@() testCase.press(b),"Proceed")

Callback Function

This code shows the callback function used in this example. The buttonCallback function executes when the button in the figure is clicked. The function creates a blocking confirmation dialog box in the figure. Selecting the "Proceed" option in the dialog box closes the figure. Selecting the "Cancel" option in the dialog box does not affect the figure.

function buttonCallback(src,~)
selection = uiconfirm(src.Parent,"Close this figure?","Confirm Close", ...
    Icon="warning", ...
    Options=["Proceed" "Cancel"]);

switch selection
    case "Proceed"
        close(src.Parent)
    case "Cancel"
        return
end
end

Select File in System Dialog Box

Since R2026a

Open Live Script

Programmatically select the default file in a file selection dialog box.

First, create the files used in this example.

fclose(fopen("default.m","w"));
fclose(fopen("myfile.m","w"));

Create a UI figure with a push button that creates a file selection dialog box when clicked. To program the button behavior, specify its ButtonPushedFcn callback property. The dialog box in this example opens to the current folder, treats default.m as the default file, and displays only the .m files.

fig = uifigure;
b = uibutton(fig, ...
    Text="Select File", ...
    ButtonPushedFcn=@(~,~) uigetfile("*.m","Select a File","default.m"));

Create a test case for interactive testing.

testCase = matlab.uitest.TestCase.forInteractiveUse;

Testing a press gesture on the button executes the callback. Programmatically select the default file in the resulting file selection dialog box by using the chooseDialog method. This code first invokes the specified function handle, which presses the button in the figure. The method then mimics a user closing the dialog box by selecting its default file, which allows code execution to continue. Because framework interactions with system dialog boxes do not display any graphical output, the method returns information about the dialog box as well as the selected file as a GetFileDialogData object.

dialogData = testCase.chooseDialog("uigetfile",@() testCase.press(b))

dialogData = 
  GetFileDialogData with properties:

        MultiSelectionEnabled: 0
    FileTypeFilterDescription: "MATLAB Script"
                SelectedFiles: "C:\work\ExampleManager\user.examples\matlab-ex32722901\default.m"
               FileTypeFilter: "*.m"
          FileTypeFilterIndex: 1
                InitialFolder: "C:\work\ExampleManager\user.examples\matlab-ex32722901"
                        Title: "Select a File"

Close the figure used for testing.

close(fig)

Select Multiple Options in System Dialog Box

Since R2026a

Open Live Script

Programmatically select a file and file filter in a system dialog box for saving files by using name-value arguments of the chooseDialog method.

Create a UI figure with a push button that creates a dialog box for saving files when clicked. To program the button behavior, specify its ButtonPushedFcn callback property. The dialog box in this example opens to the current folder.

fig = uifigure;
b = uibutton(fig, ...
    Text="Save File", ...
    ButtonPushedFcn=@(~,~) uiputfile);

Create a test case for interactive testing.

testCase = matlab.uitest.TestCase.forInteractiveUse;

Testing a press gesture on the button executes the callback. In the resulting dialog box for saving files, programmatically select a file named testdata.mat while the dialog box displays only the MAT files from the current folder. This code first invokes the specified function handle, which presses the button in the figure. The method then mimics a user closing the dialog box by selecting the specified file and file filter, which allows code execution to continue. Because framework interactions with system dialog boxes do not display any graphical output, the method returns information about the dialog box as well as the selected file and file filter as a PutFileDialogData object.

dialogData = testCase.chooseDialog("uiputfile",@() testCase.press(b), ...
File="testdata.mat", ...
Filter="*.mat")

dialogData = 
  PutFileDialogData with properties:

    FileTypeFilterDescription: "MAT-files"
                SelectedFiles: "C:\work\ExampleManager\user.examples\matlab-ex87061827\testdata.mat"
               FileTypeFilter: "*.mat"
          FileTypeFilterIndex: 5
                InitialFolder: "C:\work\ExampleManager\user.examples\matlab-ex87061827"
                        Title: "Select File to Write"

Close the figure used for testing.

close(fig)

Close Sequence of Blocking Dialog Boxes

Open Live Script

Programmatically close a sequence of blocking dialog boxes using the chooseDialog and dismissDialog methods. To close the dialog boxes, first embed all the dialog box creation logic into a function handle, and then perform the final gesture using that function handle.

In a UI figure, create a push button that can result in a sequence of blocking dialog boxes when clicked. To program the button behavior, specify its ButtonPushedFcn callback property.

fig = uifigure;
b = uibutton(fig,Text="Close",ButtonPushedFcn=@buttonCallback);

This code shows the callback function used to create the dialog boxes. The buttonCallback function executes when the button in the figure is clicked. The function creates a blocking confirmation dialog box in the figure with "Proceed" and "Cancel" options:

Selecting the "Proceed" option in the dialog box creates another blocking confirmation dialog box through the reconfirm function.
Selecting the "Cancel" option in the dialog box does not affect the figure.

The reconfirm function executes when the "Proceed" option is selected in the original dialog box. The function creates another blocking confirmation dialog box in the figure with "Yes" and "No" options:

Selecting the "Yes" option in the dialog box closes the figure.
Selecting the "No" option in the dialog box does not affect the figure.

function buttonCallback(src,~)
selection = uiconfirm(src.Parent,"Close this figure?","Confirm Close", ...
    Icon="warning", ...
    Options=["Proceed" "Cancel"]);

switch selection
    case "Proceed"
        reconfirm(src)   % Display another dialog box to reconfirm
    case "Cancel"
        return
end
end

function reconfirm(src)
selection = uiconfirm(src.Parent,"Are you sure?","Confirm Close", ...
    Icon="warning", ...
    Options=["Yes" "No"]);

switch selection
    case "Yes"
        close(src.Parent)   % Close the figure
    case "No"
        return
end
end

To test the app, create a test case for interactive testing. You use this test case first to test a press gesture on the button, which executes the callback and creates a blocking confirmation dialog box in the figure. Then, you programmatically select the "Proceed" option in the dialog box by using the chooseDialog method and dismiss the resulting dialog box by using the dismissDialog method.

testCase = matlab.uitest.TestCase.forInteractiveUse;

Because blocking dialog boxes prevent commands from running while they are open, you cannot call the press, chooseDialog, and dismissDialog methods independently. Instead, you must embed all the dialog box creation logic into a single function handle and then perform the final gesture using that function handle. In this code, fcn1 and fcn2, respectively, specify the code that must run for the first and second dialog boxes to be created. In particular, fcn2 represents all the dialog box creation logic in the test.

fcn1 = @() testCase.press(b);
fcn2 = @() testCase.chooseDialog("uiconfirm",fig,fcn1,"Proceed");

To programmatically close the expected dialog boxes, perform the final gesture using the dismissDialog method with the function handle fcn2 that includes all the dialog box creation logic. This call to the dismissDialog method results in these gestures:

Press the button in the figure, which creates the first blocking dialog box.
Select the "Proceed" option in the first blocking dialog box, which closes the dialog box and creates the second blocking dialog box.
Close the second blocking dialog box by dismissing it.

testCase.dismissDialog("uiconfirm",fig,fcn2)

Closing the blocking dialog boxes allows code execution to continue. For example, close the figure used for testing.

close(fig)

More About

expand all

Summary of Dialog Boxes

The method supports both app and system dialog boxes:

App dialog box — An app dialog box is associated with an app and can be created only in front of a figure. Dialog boxes created with the uiconfirm function are app dialog boxes.
System dialog box — A system dialog box is related to the file system and is created at the operating system level. Dialog boxes created with the uigetdir, uigetfile, and uiputfile functions are system dialog boxes.

Dialog boxes can be either nonblocking or blocking. A nonblocking dialog box lets you access the MATLAB command prompt while the dialog box is open. In contrast, a blocking dialog box prevents you from accessing the command prompt while it is open.

Version History

Introduced in R2024b

expand all

R2026a: Select files or folders in system dialog boxes

You can select files or folders in system dialog boxes created with the uigetdir, uigetfile, and uiputfile functions.

chooseDialog

Syntax

Description

App Dialog Boxes

System Dialog Boxes

Input Arguments

`testCase` — Test case
`matlab.uitest.TestCase` object

`dialogType` — Type of dialog box
`"uiconfirm"` | `"uigetdir"` | `"uigetfile"` | `"uiputfile"`

`fig` — Target figure for app dialog box
`matlab.ui.Figure` object

`option` — App dialog box option to select
string scalar | character vector | positive integer scalar

`fcn` — Code that creates blocking dialog box
function handle

Name-Value Arguments

`Folder` — Name of folder to select
string scalar | character vector

`File` — Name of file to select
string vector | character vector | cell vector of character vectors

`Filter` — File filter to select
`"All MATLAB Files"` (default) | string scalar | character vector | positive integer scalar

Output Arguments

`dialogData` — Information about system dialog box after interaction
`GetDirDialogData` object | `GetFileDialogData` object | `PutFileDialogData` object

Attributes

Examples

Select Option in Nonblocking App Dialog Box

Select Option in Blocking App Dialog Box

Select File in System Dialog Box

Select Multiple Options in System Dialog Box

Close Sequence of Blocking Dialog Boxes

More About

Summary of Dialog Boxes

Version History

R2026a: Select files or folders in system dialog boxes

See Also

Functions

Topics

chooseDialog

Syntax

Description

App Dialog Boxes

System Dialog Boxes

Input Arguments

testCase — Test case matlab.uitest.TestCase object

dialogType — Type of dialog box "uiconfirm" | "uigetdir" | "uigetfile" | "uiputfile"

fig — Target figure for app dialog box matlab.ui.Figure object

option — App dialog box option to select string scalar | character vector | positive integer scalar

fcn — Code that creates blocking dialog box function handle

Name-Value Arguments

Folder — Name of folder to select string scalar | character vector

File — Name of file to select string vector | character vector | cell vector of character vectors

Filter — File filter to select "All MATLAB Files" (default) | string scalar | character vector | positive integer scalar

Output Arguments

dialogData — Information about system dialog box after interaction GetDirDialogData object | GetFileDialogData object | PutFileDialogData object

Attributes

Examples

Select Option in Nonblocking App Dialog Box

Select Option in Blocking App Dialog Box

Select File in System Dialog Box

Select Multiple Options in System Dialog Box

Close Sequence of Blocking Dialog Boxes

More About

Summary of Dialog Boxes

Version History

R2026a: Select files or folders in system dialog boxes

See Also

Functions

Topics

`testCase` — Test case
`matlab.uitest.TestCase` object

`dialogType` — Type of dialog box
`"uiconfirm"` | `"uigetdir"` | `"uigetfile"` | `"uiputfile"`

`fig` — Target figure for app dialog box
`matlab.ui.Figure` object

`option` — App dialog box option to select
string scalar | character vector | positive integer scalar

`fcn` — Code that creates blocking dialog box
function handle

`Folder` — Name of folder to select
string scalar | character vector

`File` — Name of file to select
string vector | character vector | cell vector of character vectors

`Filter` — File filter to select
`"All MATLAB Files"` (default) | string scalar | character vector | positive integer scalar

`dialogData` — Information about system dialog box after interaction
`GetDirDialogData` object | `GetFileDialogData` object | `PutFileDialogData` object