uiconfirm

Create confirmation dialog box

Syntax

uiconfirm(fig,message,title)

uiconfirm(fig,message,title,Name,Value)

selection = uiconfirm(___)

Description

uiconfirm(fig,message,title) displays a modal in-app confirmation dialog box in the specified target figure. The target figure must be created with the uifigure function. This syntax displays two options for the user to select, OK and Cancel. The figure behind the dialog box is not accessible while the dialog box is displaying, but the MATLAB^® command prompt is accessible.

uiconfirm(fig,message,title,Name,Value) displays the confirmation dialog box with one or more Name,Value pair arguments that customize the appearance and behavior of the dialog box. For example, you can specify a custom set of options in the dialog box instead of the default, OK and Cancel.

selection = uiconfirm(___) returns the user's selection as a character vector. Specify the selection output argument with any of the previous syntaxes. When you use this syntax, the MATLAB command prompt is not accessible while the dialog box is displaying.

Examples

Specify Different Icon

Create a dialog box that displays the warning icon instead of the default question icon.

fig = uifigure;
selection = uiconfirm(fig,'Close document?','Confirm Close',...
                        'Icon','warning');

When the user selects an option, uiconfirm returns that choice as a character vector.

Specify Custom Options

Create a confirmation dialog containing three options: Overwrite, Save as new, and Cancel. Specify Save as new as the default option, and specify Cancel as the option that maps to the cancel behavior.

fig = uifigure;
msg = 'Saving these changes will overwrite previous changes.';
title = 'Confirm Save';
selection = uiconfirm(fig,msg,title,...
           'Options',{'Overwrite','Save as new','Cancel'},...
           'DefaultOption',2,'CancelOption',3);

When the user selects an option, uiconfirm returns their selection as a character vector.

Define CloseFcn Callback

The CloseFcn name-value pair argument is useful for executing specific tasks when the dialog box closes.

In the MATLAB Editor, create a new function called mycallback.m that contains the following code. This callback function displays the SelectedOption field in a struct called event. MATLAB automatically passes this struct as the second argument to the callback function.

function mycallback(src,event)
   display(event.SelectedOption);
end

In the MATLAB Command Window, execute the following code to create a confirmation dialog box that specifies mycallback as the value for CloseFcn.

fig = uifigure;
uiconfirm(fig,'Close document?','Confirm Close',...
            'CloseFcn',@mycallback);

When the user selects an option, the value of SelectedOption displays in the Command Window.

Define CloseFcn Callback in App Designer

To create a confirmation dialog box in App Designer that has a CloseFcn callback, write the callback as a private function in App Designer.

Start by selecting Code View. Then create a private function by selecting Function > Private Function.

Next, write the private function so that it matches this code:

function mycallback(app,src,event)
   display(event.SelectedOption);
end

Add this command to the callback function that you want to display the dialog box. In this case, the target figure is app.UIFigure, which is the default name for the figure in App Designer.

uiconfirm(app.UIFigure,'Close document?','Confirm Close',...
            'CloseFcn',@(src,event)mycallback(app,src,event));

Save and run your app. When the user triggers the callback that creates the dialog box, the dialog box displays in the app.

Input Arguments

fig — Target figure

Figure object

Target figure, specified as a Figure object. The figure must be created with the uifigure function.

message — Message to display

character vector | cell array of character vectors | string array

Message to display, specified as a character vector, cell array of character vectors, or string array. Specify a cell array or string array when your message has multiple lines of text. Each element in the array corresponds to a different line of text.

title — Dialog box title

character vector | string scalar

Dialog box title, specified as a character vector or string scalar.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: selection = uiconfirm(fig,message,title,'Options',{'Save','Delete','Quit'}) specifies three custom options for the dialog box.

'Options' — Custom options

{'OK','Cancel'} (default) | cell array of character vectors | string array

Custom options, specified as a cell array of character vectors or a string array.

'Icon' — Icon

'question' (default) | predefined icon | custom icon

Icon, specified as a predefined icon or a custom icon.

Predefined Icon

This table lists the values for the predefined icons. For example, to show the check mark icon, specify the name-value pair 'Icon','success'.

Value	Icon
'question' (default)
'info'
'success'
'warning'
'error'
''	No icon displays.

Custom Icon

Specify a custom icon as one of these values:

• A character vector that specifies the file name of an SVG, JPEG, GIF, or PNG image that is on the MATLAB path. Alternatively, you can specify a full path to the image file.

• A truecolor image array. See Image Types for more information.

'DefaultOption' — Default option

1 (default) | character vector | string scalar | whole number

Default option, specified as a character vector, string scalar, or a whole number. The default option corresponds to the button in the dialog box that has focus by default.

When you specify a character vector or string scalar, it must match an element in the Options array. However, if you are calling uiconfirm without the Options argument, then DefaultOption must be 'OK' or 'Cancel'.

When you specify a whole number, it must be in the range [1, n], where n is the length of the Options array. If you are calling uiconfirm without the Options argument, then DefaultOption must be 1 or 2.

'CancelOption' — Cancel option

2 (default) | character vector | string scalar | whole number

Cancel option, specified as a character vector, string scalar, or a whole number. The cancel option specifies which option maps to cancel actions in the dialog box.

When you specify a character vector or string scalar, it must match an element in the Options array. However, if you are calling uiconfirm without the Options argument, then CancelOption must be 'OK' or 'Cancel'.

When you specify a whole number, it must be in the range [1, n], where n is the length of the Options array. If you are calling uiconfirm without the Options argument, then CancelOption must be 1 or 2.

'CloseFcn' — Close callback function

'' (default) | function handle | cell array | character vector

Close callback function, specified as one of these values:

• A function handle.

• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

This callback is useful for executing specific tasks when the dialog box closes.

When you specify CloseFcn as a function handle (or cell array containing a function handle), MATLAB passes a struct containing event data as an input argument to the callback function. This struct contains the fields described in the following table.

Structure Field	Value
Source	Figure object associated with the dialog box.
EventName	'ConfirmDialogClosed'
DialogTitle	Title of the dialog box.
SelectedOptionIndex	Index of the selected option. For n options, the index can be any whole number from 1 to n.
SelectedOption	Button label for the selected option, returned as a character vector.