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. You cannot access the figure behind the dialog box while the dialog box is open, but you can access the MATLAB^® command prompt.

uiconfirm(fig,message,title,Name,Value) displays the confirmation dialog box with one or more Name,Value 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 selection as a character vector. Specify the selection output argument with any of the previous syntaxes. When you use this syntax, you cannot access the MATLAB command prompt while the dialog box is open.

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.

Display Formatted Equation

Create a figure with a PolarAxes object and a confirmation dialog box that displays an equation formatted using LaTeX. Include code to process the dialog box selection and plot the equation if the user clicks OK.

fig = uifigure;
ax = polaraxes(fig);
msg = 'Do you want to plot $$r = \exp \left(\frac{\theta}{10}\right)?$$';
selection = uiconfirm(fig,msg,'Plot equation','Interpreter','latex');
switch selection
    case 'OK'
        theta = -100:0.1:0;
        r = exp(theta/10);
        polarplot(ax,theta,r);
    case 'Cancel'
        return
end

Click OK to plot the equation.

Define CloseFcn Callback

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

In the MATLAB Editor, create a script that contains the following code. The code creates a figure and defines two callback functions named figcallback and dlgcallback.

• The figcallback function executes when a user attempts to close the figure window. The function creates a confirmation dialog box in the figure window and specifies the dlgcallback function as the dialog box CloseFcn callback.

• The dlgcallback function executes when the dialog box closes. The function accesses the SelectedOption field in a struct called event, which MATLAB passes as the second argument to the callback function. If the user selects OK, the function closes the figure window.

fig = uifigure('CloseRequestFcn',@figcallback);

function figcallback(src,event)
    uiconfirm(src,'Close app?','Confirm Close', ...
        'CloseFcn',@dlgcallback);
end

function dlgcallback(src,event)
    if event.SelectedOption == "OK"
        delete(event.Source)
    end
end

Run the script, and then attempt to close the figure window. This creates the confirmation dialog box.

For more information about specifying callback functions, see Write Callbacks for Apps Created Programmatically.

Create a Dialog Box in App Designer

Create a confirmation dialog box in App Designer that asks a user to confirm the decision to close the app.

Write a CloseFcn callback for the confirmation dialog box that closes the app figure window if the user selects OK. First, in App Designer Code View, create a private function by selecting Function > Private Function. Then, write the private function so that it matches this code:

function mycallback(app,src,event)
    if event.SelectedOption == "OK"
        delete(app.UIFigure);
    end
end

Finally, to display the dialog box when a user tries to close the app, create a CloseRequestFcn callback for the figure window. Click Callback and select app.UIFigure as the component and CloseRequestFcn as the callback, and then click Add Callback. Replace the body of the callback function that App Designer creates with this code:

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

Save and run your app, and then attempt to close the app window to create the confirmation dialog box.

For more information about programmatically creating components and specifying callback functions, see Add UI Components to App Designer Programmatically.

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

For more information about specifying callback functions, see Write Callbacks for Apps Created Programmatically.

Interpreter — Dialog text interpreter

'none' (default) | 'tex' | 'latex' | 'html'

Dialog text interpreter, specified as:

• 'none' — Display literal characters.

• 'tex'— Interpret text using a subset of TeX markup.

• 'latex'— Interpret text using a subset of LaTeX markup.

• 'html'— Interpret text using a subset of HTML markup.

TeX Markup

Use TeX markup to add superscripts and subscripts and to include special characters in the text.

Modifiers remain in effect until the end of the text. Superscripts and subscripts are an exception because they modify only the next character or the characters within the curly braces. When you set the interpreter to 'tex', the supported modifiers are as follows.

Modifier	Description	Example
^{ }	Superscript	'text^{superscript}'
_{ }	Subscript	'text_{subscript}'
\bf	Bold font	'\bf text'
\it	Italic font	'\it text'
\sl	Oblique font (usually the same as italic font)	'\sl text'
\rm	Normal font	'\rm text'
\fontname{specifier}	Font name — Replace specifier with the name of a font family. You can use this in combination with other modifiers.	'\fontname{Courier} text'
\fontsize{specifier}	Font size —Replace specifier with a numeric scalar value in point units.	'\fontsize{15} text'
\color{specifier}	Font color — Replace specifier with one of these colors: red, green, yellow, magenta, blue, black, white, gray, darkGreen, orange, or lightBlue.	'\color{magenta} text'
\color[rgb]{specifier}	Custom font color — Replace specifier with a three-element RGB triplet.	'\color[rgb]{0,0.5,0.5} text'

This table lists the supported special characters for the 'tex' interpreter.

Character Sequence	Symbol	Character Sequence	Symbol	Character Sequence	Symbol
\alpha	α	\upsilon	υ	\sim	~
\angle	∠	\phi		\leq	≤
\ast	*	\chi	χ	\infty	∞
\beta	β	\psi	ψ	\clubsuit	♣
\gamma	γ	\omega	ω	\diamondsuit	♦
\delta	δ	\Gamma	Γ	\heartsuit	♥
\epsilon	ϵ	\Delta	Δ	\spadesuit	♠
\zeta	ζ	\Theta	Θ	\leftrightarrow	↔
\eta	η	\Lambda	Λ	\leftarrow	←
\theta	θ	\Xi	Ξ	\Leftarrow	⇐
\vartheta	ϑ	\Pi	Π	\uparrow	↑
\iota	ι	\Sigma	Σ	\rightarrow	→
\kappa	κ	\Upsilon	ϒ	\Rightarrow	⇒
\lambda	λ	\Phi	Φ	\downarrow	↓
\mu	µ	\Psi	Ψ	\circ	º
\nu	ν	\Omega	Ω	\pm	±
\xi	ξ	\forall	∀	\geq	≥
\pi	π	\exists	∃	\propto	∝
\rho	ρ	\ni	∍	\partial	∂
\sigma	σ	\cong	≅	\bullet	•
\varsigma	ς	\approx	≈	\div	÷
\tau	τ	\Re	ℜ	\neq	≠
\equiv	≡	\oplus	⊕	\aleph	ℵ
\Im	ℑ	\cup	∪	\wp	℘
\otimes	⊗	\subseteq	⊆	\oslash	∅
\cap	∩	\in	∈	\supseteq	⊇
\supset	⊃	\lceil	⌈	\subset	⊂
\int	∫	\cdot	·	\o	ο
\rfloor	⌋	\neg	¬	\nabla	∇
\lfloor	⌊	\times	x	\ldots	...
\perp	⊥	\surd	√	\prime	´
\wedge	∧	\varpi	ϖ	\0	∅
\rceil	⌉	\rangle	〉	\mid	|
\vee	∨	\langle	〈	\copyright	©

LaTeX Markup

Use LaTeX markup to format and display mathematical expressions, equations, and special characters. Use dollar symbols around the marked up text. For example, use '$\int_1^{20} x^2 dx$' for inline mode or '$$\int_1^{20} x^2 dx$$' for display mode.

The displayed text uses the default LaTeX font style. You can use LaTeX markup to change the font style.

MATLAB supports most standard LaTeX math mode commands. For more information, see Supported LaTeX Commands.

HTML Markup

Use HTML markup to display links and customize font styles.

The interpreter supports a subset of HTML markup. As a general guideline, the interpreter supports text-related tags and styles. Unsupported tags and styles are ignored.

This table lists the supported elements and element attributes.

HTML Element	Attributes	Description
a	style, target, href, title	Hyperlink
abbr	style, title	Abbreviation or acronym
address	style	Contact information
article	style	Self-contained, independent content
aside	style	Content indirectly related to the main content
b	style	Bold text
bdi	style, dir	Content formatted in a different direction from surrounding text
bdo	style, dir	Content formatted in a different direction from surrounding text
big	style	Text one font size level larger than surrounding text (obsolete in HTML5)
blockquote	style, cite	Extended quotation
br	n/a	Line break
caption	style	Caption or title of a table
center	style	Content centered horizontally
cite	style	Title of a creative work
code	style	Fragment of code
col	style, align, valign, span, width	Column within a table
colgroup	style, align, valign, span, width	Group of columns within a table
dd	style	Term or value in a description list
del	style, datetime	Text that was deleted from a document
details	style, open	Interactive widget with text visible only when toggled to 'open' state
dl	style	Description list
dt	style	Term or value in a description list
em	style	Emphasized text (typically displayed in italic)
font	style, color, size, face	Text with specified font properties (obsolete in HTML5)
footer	style	Footer
h1. h2, h3, h4, h5, h6	style	Section heading — <h1> is the highest level of heading and <h6> is the lowest
header	style	Introductory content
hr	style	Thematic break
i	style	Text offset from the surrounding content — by default rendered as italic
ins	style, datetime	Text inserted into a document
li	style	Item in a list
mark	style	Marked or highlighted text
ol	style	Ordered list
p	style	Paragraph
pre	style	Preformatted text
s	style	Text with a strikethrough
strike	style	Text with a strikethrough (obsolete in HTML5)
section	style	Standalone section
small	style	Text one font size level smaller than surrounding text (obsolete in HTML5)
sub	style	Subscript
sup	style	Superscript
strong	style	Text with strong importance
table	style, width, border, align, valign	Table
tbody	style, align, valign	Table body
td	style, width, rowspan, colspan, align, valign	Table data cell
tfoot	style, align, valign	Set of table rows that summarize the table columns
th	style, width, rowspan, colspan, align, valign	Table data cell specified as a header of a group of cells
thead	style, align, valign	Set of table rows that specify the column heads
tr	style, rowspan, align, valign	Row of table cells
tt	style	Monospace text (obsolete in HTML5)
u	style	Text with an unarticulated annotation — by default rendered as an underline
ul	style	Unordered list

For more information about these elements, see https://developer.mozilla.org/en-US/docs/Web/HTML/Element.

You can use HTML style attributes to format HTML content. A style attribute is a string of CSS attributes and their values.

These CSS attributes are supported:

• background-color

• border-bottom

• border-bottom-color

• border-bottom-left-radius

• border-bottom-right-radius

• border-bottom-style

• border-bottom-width

• border-left

• border-left-color

• border-left-style

• border-left-width

• border-radius

• border-right

• border-right-color

• border-right-style

• border-right-width

• border-spacing

• border-style

• border-top

• border-top-color

• border-top-left-radius

• border-top-right-radius

• border-top-style

• border-top-width

• border-width

• color

• direction

• font-family

• font-size

• font-style

• font-weight

• height

• hidden

• line-height

• margin

• margin-bottom

• margin-left

• margin-right

• margin-top

• max-height

• max-width

• min-height

• min-width

• overflow

• overflow-wrap

• overflow-x

• overflow-y

• padding

• padding-bottom

• padding-left

• padding-right

• padding-top

• text-align

• text-anchor

• text-decoration

• text-indent

• text-overflow

• text-shadow

• text-transform

• title

• translate

• white-space

• width

For more information about these attributes, see https://developer.mozilla.org/en-US/docs/Web/CSS/Reference.