ProgressDialog
Progress dialog box
Description
A progress dialog box indicates that an operation is in progress by displaying an
animated progress bar. Use the ProgressDialog
object to modify the appearance
and behavior of a progress dialog box after you create it.
Creation
Create a progress dialog box in an app using the uiprogressdlg
function.
Properties
Text and Styling
Message
— message
''
(default) | character vector | cell array of character vectors | string array
Message, specified as a character vector, cell array of character vectors, or string array. The message displays within the dialog box, above the progress bar.
To display multiple lines of text, specify a cell array of character vectors or a
string array. Each element in the array corresponds to a line of text. Hard breaks
within each element, such as '\n'
, create additional lines of
text.
Example: d = uiprogressdlg(uifigure,'Message','Calculating result.');
Title
— Title
''
(default) | character vector | string scalar
Title, specified as a character vector or a string scalar. The title displays in the title bar of the dialog box.
Example: d = uiprogressdlg(uifigure,'Title','Calculating');
Icon
— Predefined or custom icon
''
(default) | character vector | string scalar | truecolor image array
Predefined or custom icon, specified as a character vector, string scalar, or truecolor image array.
Predefined Icon
This table lists the values to specify the predefined icons.
Value | Icon |
---|---|
'' (default) | No icon added. |
'question' |
|
'info' |
|
'success' |
|
'warning' |
|
'error' |
|
Custom Icon
Specify a custom icon as one of these values:
A character vector or string scalar 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 Working with Image Types in MATLAB for more information.
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{ | Font name — Replace
with the name of
a font family. You can use this in combination with other modifiers. | '\fontname{Courier} text' |
\fontsize{ | Font size —Replace
with a numeric
scalar value in point units. | '\fontsize{15} text' |
\color{ | Font color — Replace
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
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 |
---|---|---|---|---|---|
| α |
| υ |
| ~ |
| ∠ |
| ϕ |
| ≤ |
|
|
| χ |
| ∞ |
| β |
| ψ |
| ♣ |
| γ |
| ω |
| ♦ |
| δ |
| Γ |
| ♥ |
| ϵ |
| Δ |
| ♠ |
| ζ |
| Θ |
| ↔ |
| η |
| Λ |
| ← |
| θ |
| Ξ |
| ⇐ |
| ϑ |
| Π |
| ↑ |
| ι |
| Σ |
| → |
| κ |
| ϒ |
| ⇒ |
| λ |
| Φ |
| ↓ |
| µ |
| Ψ |
| º |
| ν |
| Ω |
| ± |
| ξ |
| ∀ |
| ≥ |
| π |
| ∃ |
| ∝ |
| ρ |
| ∍ |
| ∂ |
| σ |
| ≅ |
| • |
| ς |
| ≈ |
| ÷ |
| τ |
| ℜ |
| ≠ |
| ≡ |
| ⊕ |
| ℵ |
| ℑ |
| ∪ |
| ℘ |
| ⊗ |
| ⊆ |
| ∅ |
| ∩ |
| ∈ |
| ⊇ |
| ⊃ |
| ⌈ |
| ⊂ |
| ∫ |
| · |
| ο |
| ⌋ |
| ¬ |
| ∇ |
| ⌊ |
| x |
| ... |
| ⊥ |
| √ |
| ´ |
| ∧ |
| ϖ |
| ∅ |
| ⌉ |
| 〉 |
| | |
| ∨ |
| 〈 |
| © |
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.
To use HTML markup to create a hyperlink that runs MATLAB code, see Create Hyperlinks that Run Functions.
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.
Progress
Value
— Fraction complete
0
(default) | number between 0
and 1
Fraction complete, specified as a number between 0
and
1
. The progress bar reaches its full length when the value is
1
. Change Value
at different points in your
code to provide a visual indication of progress in the running app.
Data Types: double
ShowPercentage
— Show percentage
'off'
(default) | on/off logical value
Show percentage, specified as 'off'
or 'on'
,
or as numeric or logical 1
(true
) or
0
(false
). A value of 'on'
is equivalent to true
, and 'off'
is equivalent
to false
. Thus, you can use the value of this property as a logical
value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState
.
Set this property to 'on'
to display the fraction complete as a
percentage in the dialog box.
Indeterminate
— Indeterminate progress
'off'
(default) | on/off logical value
Indeterminate progress, specified as 'off'
or 'on'
, or
as numeric or logical 1
(true
) or 0
(false
). A value of
'on'
is equivalent to
true
, and
'off'
is equivalent to
false
. Thus, you can use the
value of this property as a logical value. The value is stored
as an on/off logical value of type matlab.lang.OnOffSwitchState
.
Set this property to 'on'
to provide an animated
bar without any specific progress information. This animation is
useful when you do not know how long a calculation will
take.
To prevent indeterminate progress bars from displaying indefinitely, call the close
function after completing your calculations.
Interactivity
Cancelable
— Allow cancellation
'off'
(default) | on/off logical value
Allow cancellation, specified as 'off'
or 'on'
, or as
numeric or logical 1
(true
) or
0
(false
). A value of 'on'
is equivalent to true
, and 'off'
is equivalent to
false
. Thus, you can use the value of this property as a logical
value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState
.
A value of 'on'
displays a cancel button in the dialog box. You
can customize the button label by specifying the CancelText
property.
When you allow cancellation, you must check the value of the CancelRequested
property, and call the close
function when the value is true
. Otherwise, the dialog box displays indefinitely.
CancelText
— Cancel button text
'Cancel'
(default) | character vector | string scalar
Cancel button text, specified as a character vector or string scalar. This
property has an effect only when the Cancelable
property is set
to 'on'
.
Example: d =
uiprogressdlg(uifigure,'Cancelable','on','CancelText','Stop')
CancelRequested
— Cancel requested
true
| false
Cancel requested, specified as true
or
false
. Use this property when Cancelable
is
'on'
, and you want to know whether the user clicked the cancel
button. This property is false
until the user
clicks the cancel button, then the value changes to true
.
Examples
Determinate Progress Bar
Create a program file called myprogress1.m
that creates a figure
and a progress dialog box. Update the Value
and
Message
properties at three different points in the code.
function myprogress1 fig = uifigure; d = uiprogressdlg(fig,'Title','Please Wait',... 'Message','Opening the application'); pause(.5) % Perform calculations % ... d.Value = .33; d.Message = 'Loading your data'; pause(1) % Perform calculations % ... d.Value = .67; d.Message = 'Processing the data'; pause(1) % Finish calculations % ... d.Value = 1; d.Message = 'Finishing'; pause(1) % Close dialog box close(d) end
Run the program to display the progress dialog box.
myprogress1
Indeterminate Progress Bar
Create a program file called myprogress2.m
that creates a figure
and displays an indeterminate progress bar during a singular value decomposition.
function myprogress2 fig = uifigure; d = uiprogressdlg(fig,'Title','Computing SVD',... 'Indeterminate','on'); drawnow % Do the SVD computation svd(rand(5000)); % close the dialog box close(d) end
Setting the Indeterminate
property to 'on'
animates the progress bar to indicate that there is no projected completion time. After
completing the calculation, the close
function closes the dialog
box.
Run the program to perform the singular value decomposition and display the progress dialog box.
myprogress2
Determinate Progress Bar with Cancel Button
Create a program file called myprogress3.m
that creates a figure
and displays a progress bar while approximating the value of pi.
function myprogress3 fig = uifigure; d = uiprogressdlg(fig,'Title','Approximating Pi',... 'Message','1','Cancelable','on'); drawnow % Approximate pi^2/8 as: 1 + 1/9 + 1/25 + 1/49 + ... pisqover8 = 1; denom = 3; valueofpi = sqrt(8 * pisqover8); steps = 20000; for step = 1:steps % Check for Cancel button press if d.CancelRequested break end % Update progress, report current estimate d.Value = step/steps; d.Message = sprintf('%12.9f',valueofpi); % Calculate next estimate pisqover8 = pisqover8 + 1 / (denom * denom); denom = denom + 2; valueofpi = sqrt(8 * pisqover8); end % Close the dialog box close(d) end
Setting the Cancelable
property to 'on'
creates a cancel button with the default label, Cancel. The first
command in the for
loop checks the value of
d.CancelRequested
to see if the user clicked the cancel button. If
the value is true
, the program exits the loop. Finally, the
close(d)
command closes the dialog box after the
for
loop finishes or the user cancels.
Run the program to approximate pi and display the progress dialog box.
myprogress3
Customize Progress Dialog Box Appearance
Specify a custom icon and format message text using HTML to modify the appearance of the progress dialog box.
Create a program file called myprogress4.m
that creates a figure
and displays a progress bar. Specify an image file as the dialog box icon, and then
specify that the dialog box interpret its message text as HTML. Create a matrix of RGB
color values using the winter
colormap. Use a for
loop to update the progress bar value and to format and display the message color by
using HTML markup. Close the dialog box when the loop completes.
function myprogress4 fig = uifigure; d = uiprogressdlg(fig,'Icon','peppers.png', ... 'Interpreter','html'); steps = 100; cmap = winter(steps)*100; for step = 1:steps r = num2str(cmap(step,1)); g = num2str(cmap(step,2)); b = num2str(cmap(step,3)); msg = ['<p style=color:rgb(' r '%,' g '%,' b '%)> Calculating... </p>']; d.Message = msg; d.Value = step/steps; pause(0.05); end close(d) end
Run the program to display the progress dialog box.
myprogress4
Version History
Introduced in R2018aR2021b: Style text and display equations
Use the Interpreter
property to enable markup in the dialog box
text. Specify the interpreter as 'html'
, 'latex'
,
'tex'
, or 'none'
.
See Also
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)