Main Content

uiprogressdlg

Create progress dialog box

Description

d = uiprogressdlg(fig) displays a determinate progress dialog box in figure fig and returns the ProgressDialog object. The figure must be created using the uifigure function.

example

d = uiprogressdlg(fig,Name,Value) specifies ProgressDialog property values by using Name,Value arguments. Use property values to control the appearance and behavior of the dialog box. For example, you can add a title or message to the dialog box, or specify an indeterminate progress bar.

Examples

collapse all

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

Progress dialog box with title "Please Wait" and text "Loading your data". The progress bar length is about 1/3 of the full length.

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

Progress dialog box with title "Computing SVD" and an indeterminate progress bar

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

Progress dialog box with title "Approximating Pi". The dialog box text is an approximation of pi, and the progress bar length is a fraction of the full length.

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

Progress dialog box with an image of some peppers and a message that says "Calculating..." in blue text.

Input Arguments

collapse all

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

Name-Value Arguments

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: d = uiprogressdlg(uifigure,'Value',0.25)

Note

The properties listed here are only a subset. For a complete list, see ProgressDialog Properties.

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

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, 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');

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.

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.

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.

ModifierDescriptionExample
^{ }Superscript'text^{superscript}'
_{ }Subscript'text_{subscript}'
\bfBold font'\bf text'
\itItalic font'\it text'
\slOblique font (usually the same as italic font)'\sl text'
\rmNormal 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 SequenceSymbolCharacter SequenceSymbolCharacter SequenceSymbol

\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 ElementAttributesDescription
astyle, target, href, titleHyperlink
abbrstyle, titleAbbreviation or acronym
addressstyleContact information
articlestyleSelf-contained, independent content
asidestyleContent indirectly related to the main content
bstyleBold text
bdistyle, dirContent formatted in a different direction from surrounding text
bdostyle, dirContent formatted in a different direction from surrounding text
bigstyleText one font size level larger than surrounding text (obsolete in HTML5)
blockquotestyle, citeExtended quotation
brn/aLine break
captionstyleCaption or title of a table
centerstyleContent centered horizontally
citestyleTitle of a creative work
codestyleFragment of code
colstyle, align, valign, span, widthColumn within a table
colgroupstyle, align, valign, span, widthGroup of columns within a table
ddstyleTerm or value in a description list
delstyle, datetimeText that was deleted from a document
detailsstyle, openInteractive widget with text visible only when toggled to 'open' state
dlstyleDescription list
dtstyleTerm or value in a description list
emstyleEmphasized text (typically displayed in italic)
fontstyle, color, size, faceText with specified font properties (obsolete in HTML5)
footerstyleFooter
h1. h2, h3, h4, h5, h6styleSection heading — <h1> is the highest level of heading and <h6> is the lowest
headerstyleIntroductory content
hrstyleThematic break
istyleText offset from the surrounding content — by default rendered as italic
insstyle, datetimeText inserted into a document
listyleItem in a list
markstyleMarked or highlighted text
olstyleOrdered list
pstyleParagraph
prestylePreformatted text
sstyleText with a strikethrough
strikestyleText with a strikethrough (obsolete in HTML5)
sectionstyleStandalone section
smallstyleText one font size level smaller than surrounding text (obsolete in HTML5)
substyleSubscript
supstyleSuperscript
strongstyleText with strong importance
tablestyle, width, border, align, valignTable
tbodystyle, align, valignTable body
tdstyle, width, rowspan, colspan, align, valignTable data cell
tfootstyle, align, valignSet of table rows that summarize the table columns
thstyle, width, rowspan, colspan, align, valignTable data cell specified as a header of a group of cells
theadstyle, align, valignSet of table rows that specify the column heads
trstyle, rowspan, align, valignRow of table cells
ttstyleMonospace text (obsolete in HTML5)
ustyleText with an unarticulated annotation — by default rendered as an underline
ulstyleUnordered 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.

Tips

  • When you create a progress dialog box, store the ProgressDialog object as a variable by specifying an output argument. You can use this object to update the dialog box after you create it by setting properties and to manage when the dialog box is deleted by using the delete function.

Version History

Introduced in R2018a

expand all

See Also

Functions

Properties