Documentation

waitfor

Block execution and wait for event or condition

Syntax

waitfor(h)
waitfor(h,PropertyName)
waitfor(h,PropertyName,PropertyValue)

Description

waitfor(h) blocks the caller from executing statements until the graphics object identified by h closes (is deleted). When object h no longer exists, waitfor returns, enabling execution to resume. If the object does not exist, waitfor returns immediately without processing any events.

waitfor(h,PropertyName) blocks the caller from executing until the value of PropertyName (any property of the graphics object h) changes or h closes (is deleted). If PropertyName is not a valid property for the object, MATLAB® returns an error.

waitfor(h,PropertyName,PropertyValue) blocks the caller from executing until the value of PropertyName for the graphics object h changes to the specific value PropertyValue or h closes (is deleted). If the value of PropertyName is already PropertyValue, waitfor returns immediately without processing any events.

Here are some important characteristics of the waitfor function:

  • The waitfor function prevents its caller from continuing, but callbacks that respond to various user actions (for example, pressing a mouse button) can still run.

  • The waitfor function also blocks Simulink® models from executing, but callbacks do still execute.

  • The waitfor function can block nested function calls. For example, a callback that executes while the waitfor function is running can call waitfor.

  • If a callback function of a UI component is currently executing the waitfor function, then that callback can be interrupted regardless of that component's Interruptible property value.

  • If you type Ctrl+C in the Command Window while the waitfor function is executing, the executing program terminates. To avoid terminating, the program can call the waitfor function within a try/catch block that handles the exception that typing Ctrl+C generates.

Examples

Create a plot and pause execution of the rest of the statements until you close the figure window:

f = warndlg('This is a warning.', 'A Warning Dialog');
disp('This prints immediately');
drawnow     % Necessary to print the message
waitfor(f);
disp('This prints after you close the warning dialog');

Suspend execution until name of figure changes:

f = figure('Name', datestr(now));
h = uicontrol('String','Change Name',...
              'Position',[20 20 100 30],...
'Callback', 'set(gcbf, ''Name'', datestr(now))');
disp('This prints immediately');
drawnow     % Necessary to print the message
waitfor(f, 'Name');
disp('This prints after clicking the push button');     

Display text object and wait for user to edit it:

figure;
textH = text(.5, .5, 'Edit me and click away');
set(textH,'Editing','on', 'BackgroundColor',[1 1 1]);
disp('This prints immediately.');
drawnow
waitfor(textH,'Editing','off');
set(textH,'BackgroundColor',[1 1 0]);
disp('This prints after text editing is complete.');

If you close the figure while waitfor is executing, an error occurs because the code attempts to access handles of objects that no longer exist. You can handle the error by enclosing code starting with the call to waitfor in a try/catch block, as follows:

figure;
textH = text(.5, .5, 'Edit me and click away');
set(textH,'Editing','on', 'BackgroundColor',[1 1 1]);
disp('This prints immediately.');
drawnow
% Use try/catch block to handle errors, 
% such as deleting figure
try
    waitfor(textH,'Editing','off');
    set(textH,'BackgroundColor',[1 1 0]);
    disp('This prints after text editing is complete.');
catch ME
    disp('This prints if figure is deleted:')
    disp(ME.message)
		% You can place other code to respond to the error here
end

The ME variable is a MATLAB Exception object that you can use to determine the type of error that occurred. For more information, see Respond to an Exception.

Was this topic helpful?