Learn more about MATLAB

waitbar - Open or update a wait bar dialog box

Syntax

h = waitbar(x,'message') waitbar(x,'message','CreateCancelBtn','button_callback') waitbar(x,'message',property_name,property_value,...) waitbar(x) waitbar(x,h) waitbar(x,h,'updated message')

Description

A wait bar is a figure that displays what percentage of a calculation is complete as the calculation proceeds by progressively filling a bar with red from left to right.

h = waitbar(x,'message') displays a wait bar of fractional length x. The wait bar figure displays until the code that controls it closes it or the use clicks its Close Window button. Its (figure) handle is returned in h. The argument x must be between 0 and 1.

Note Wait bars are not modal figures (their WindowStyle is 'normal'). They often appear to be modal because the computational loops within which they are called prevent interaction with the Command Window until they terminate. For more information, see WindowStyle in the MATLAB Figure Properties documentation.

waitbar(x,'message','CreateCancelBtn','button_callback') specifying CreateCancelBtn adds a Cancel button to the figure that executes the MATLAB commands specified in button_callback when the user clicks the Cancel button or the Close Figure button. waitbar sets both the Cancel button callback and the figure CloseRequestFcn to the string specified in button_callback.

waitbar(x,'message',property_name,property_value,...) optional arguments property_name and property_value enable you to set figure properties for the waitbar.

waitbar(x) subsequent calls to waitbar(x) extend the length of the bar to the new position x. Successive values of x normally increase. If they decrease, the wait bar runs in reverse.

waitbar(x,h) extends the length of the bar in the wait bar h to the new position x.

waitbar(x,h,'updated message') updates the message text in the waitbar figure, in addition to setting the fractional length to x.

Examples

Example 1 — Basic Wait Bar

Typically, you call waitbar repeatedly inside a for loop that performs a lengthy computation. For example:

h = waitbar(0,'Please wait...');
steps = 1000;
for step = 1:steps
    % computations take place here
    waitbar(step / steps)
end
close(h)

Example 2 — Wait Bar with Dynamic Text and Cancel Button

Adding a Cancel button allows user to abort the computation. Clicking it sets a logical flag in the figure's application data (appdata). The function tests for that value within the main loop and exits the loop as soon as the flag has been set. The example iteratively approximates the value of π. At each step, the current value is encoded as a string and displayed in the wait bar's message field. When the function finishes, it destroys the wait bar and returns the current estimate of π and the number of steps it ran.

Copy the following function to an M-file and save it as approxpi.m. Execute it as follows, allowing it to run for 10,000 iterations.

[estimated_pi steps] = approxpi(10000)

You can click Cancel or close the window to abort the computation and return the current estimate of π.

function [valueofpi step] = approxpi(steps)
% Converge on pi in steps iterations, displaying waitbar.
% User can click Cancel or close button to exit the loop.
% Ten thousand steps yields error of about 0.001 percent.

h = waitbar(0,'1','Name','Approximating pi...',...
            'CreateCancelBtn',...
            'setappdata(gcbf,''canceling'',1)');
setappdata(h,'canceling',0)
% Approximate as pi^2/8 = 1 + 1/9 + 1/25 + 1/49 + ...
pisqover8 = 1;
denom = 3;
valueofpi = sqrt(8 * pisqover8);
for step = 1:steps 
    % Check for Cancel button press
    if getappdata(h,'canceling')
        break
    end
    % Report current estimate in the waitbar's message field
    waitbar(step/steps,h,sprintf('%12.9f',valueofpi))
    % Update the estimate
    pisqover8 = pisqover8 + 1 / (denom * denom);
    denom = denom + 2;
    valueofpi = sqrt(8 * pisqover8);
end
delete(h)       % DELETE the waitbar; don't try to CLOSE it.

The function sets the figure Name property to describe what is being computed. In the for loop, calling waitbar sets the fractional progress indicator and displays intermediate results. the code waitbar(i/steps,h,sprintf('%12.9f',valueofpi)) sets the wait bar's message variable to a string representation of the current estimate of pi. Naturally, the extra computation involved makes iterations last longer than they need to, but such feedback can be helpful to users.

Note You should call delete to remove a wait bar when you give it a CloseRequestFcn, as in the preceding code; calling close does not close it, and makes its Cancel and Close Window buttons unresponsive. This happens because the figure's CloseRequestFcn recursively calls itself. In such a situation you must forcibly remove the wait bar, for example like this:

set(0,'ShowHiddenHandles','on')
delete(get(0,'Children'))

However, as issuing these commands will delete all open figures—not just the wait bar—it is best never to use close in a CloseRequestFcn to close a window.