Interrupt Callback Execution

MATLAB^® lets you control whether a callback function can be interrupted while it is executing. At times you might want to permit interruptions. For instance, you might allow users to stop an animation loop by creating a callback that interrupts the animation. At other times, when the order of the running callback is important, you might want to prevent potential interruptions. For instance, in order to make an app more responsive, you might prevent interruption of callbacks that respond to pointer movement.

Interrupted Callback Behavior

Callback functions execute according to their order in a queue. If a callback is executing and a user action triggers a second callback, the second callback attempts to interrupt the first callback. The first callback is the running callback. The second callback is the interrupting callback.

Certain commands that occur in the running callback cause MATLAB to process the rest of the callback queue. MATLAB determines callback interruption behavior whenever it executes one of these commands. These commands include drawnow, figure, uifigure, getframe, waitfor, and pause.

If the running callback does not contain one of these commands, then no interruption occurs. MATLAB first finishes executing the running callback, and later executes the interrupting callback.

If the running callback does contain one of these commands, then the Interruptible property of the object that owns the running callback determines whether the interruption occurs:

• If the value of Interruptible is 'on', then the interruption occurs. When MATLAB processes the callback queue, it pauses the execution of the running callback and executes the interrupting callback. After the interrupting callback is complete, MATLAB then resumes executing the running callback.

• If the value of Interruptible is 'off', then no interruption occurs. Instead, the BusyAction property of the interrupting callback determines what MATLAB does with the interrupting callback:

  • If the value of BusyAction is 'queue', MATLAB executes the interrupting callback after the running callback finishes.

  • If the value of BusyAction is 'cancel', MATLAB discards the interrupting callback.

The default value of Interruptible is 'on', and the default value of BusyAction is 'queue'.

Finally, if the interrupting callback is a DeleteFcn, CloseRequestFcn, or SizeChangedFcn callback, then the interruption occurs regardless of the value of the Interruptible property.

Control Callback Interruption Behavior

This example shows how the Interruptible and BusyAction component properties interact to produce different types of callback interruption behavior.

Create a file called callbackBehavior.m in your current folder, and define in it a function with the same name. This function creates an app with two figure windows, each with two buttons. Each of the buttons has a ButtonPushedFcn callback and a different callback execution property value. If you click one button, and then click a second button before the first one is done, then the callback of the second button attempts to interrupt the first. The buttons in the first window display and update a progress dialog when clicked. The buttons in the second window plot data when clicked. You can control what happens by defining the interruption behavior for the two buttons.

function callbackBehavior
% Create the figures and grid layouts
fig1 = uifigure('Position',[400 600 500 150]);
g1 = uigridlayout(fig1,[2,2]);
fig2 = uifigure('Position',[400 100 500 400]);
g2 = uigridlayout(fig2,[3,2], ...
    'RowHeight', {'1x','1x','8x'});

% Create the label for the first figure window
lbl1 = uilabel(g1,'Text','1. Click a button to clear the axes and generate a progress dialog.');
lbl1.Layout.Column = [1 2];
lbl1.HorizontalAlignment = 'center';

% Create the buttons that create a progress dialog
interrupt = uibutton(g1, ...
    'Text','Wait (interruptible)', ...
    'Interruptible','on', ...
    'ButtonPushedFcn',@createProgressDlg);
nointerrupt = uibutton(g1, ...
    'Text','Wait (not interruptible)', ...
    'Interruptible','off', ...
    'ButtonPushedFcn',@createProgressDlg);

% Create the label for the second figure window
lbl2 = uilabel(g2,'Text','2. Click a button to plot some data.');
lbl2.Layout.Column = [1 2];
lbl2.HorizontalAlignment = 'center';

% Create the axes
ax = uiaxes(g2);
ax.Layout.Row = 3;
ax.Layout.Column = [1 2];

% Create the buttons to plot data
queue = uibutton(g2, ...
    'Text','Plot (queue)', ...
    'BusyAction','queue', ...
    'ButtonPushedFcn',@(src,event)surf(ax,peaks(35)));
queue.Layout.Row = 2;
queue.Layout.Column = 1;

cancel = uibutton(g2, ...
    'Text','Plot (cancel)', ...
    'BusyAction','cancel', ...
    'ButtonPushedFcn',@(src,event)surf(ax,peaks(35)));
cancel.Layout.Row = 2;
cancel.Layout.Column = 2;

    % Callback function to create and update a progress dialog
    function createProgressDlg(src,event)
        % Clear axes
        cla(ax,'reset')
        % Create the dialog
        dlg = uiprogressdlg(fig1,'Title','Please Wait',...
        'Message','Loading...');
        steps = 250;
        for step = 1:steps 
            % Update progress
            dlg.Value = step/steps;
            pause(0.01)
        end
        close(dlg)
    end
end

Call the callbackBehavior function to display the figure windows.

callbackBehavior

Click pairs of buttons to see the effects of different combinations of Interruptible and BusyAction property values.

• Callback interruption — Click Wait (interruptible) immediately followed by either button in the second window: Plot (queue) or Plot (cancel). Because the first button has its Interruptible value set to 'on', interruption occurs. The plot appears while the progress dialog is still running.

• Callback queueing — Click Wait (not interruptible) immediately followed by Plot (queue). Because the first button has its Interruptible value set to 'off' and the second button has its BusyAction value set to 'queue', queueing occurs. The progress dialog runs to completion. Then, the plot displays.

• Callback cancellation — Click Wait (not interruptible) immediately followed by Plot (cancel). Because the first button has its Interruptible value set to 'off' and the second button has its BusyAction value set to 'cancel', cancellation occurs. The progress dialog runs to completion. But then, no plot appears, because MATLAB has discarded the plot callback.