uiprogressdlg

Create progress dialog box

Syntax

d = uiprogressdlg(fig)

d = uiprogressdlg(fig,Name,Value)

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.

d = uiprogressdlg(fig,Name,Value) specifies ProgressDialog property values using Name,Value pair 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

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

Input Arguments

fig — Target figure

Figure object

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

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: d = uiprogressdlg(uifigure,'Value',0.25)

Note

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

'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

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

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

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