Interrupt Callback Execution

MATLAB^® lets you control whether or not a callback function can be interrupted while it is executing. For instance, you can allow users to stop an animation loop by creating a callback that interrupts the animation. At other times, you might want to prevent potential interruptions, when the order of the running callback is important. For instance, you might prevent interruptions for a WindowButtonMotionFcn callback that shows different sections of an image.

How to Control Interruption

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.

Two property values control the response to an interruption attempt:

The Interruptible property of the object owning the running callback determines if interruption is allowed. A value of 'on' allows the interruption. A value of 'off' does not allow the interruption. The default value is 'on'.
If interruption is not allowed, then the BusyAction property (of the object owning the interrupting callback) determines if MATLAB enqueues or discards the interrupting callback. A value of 'queue' allows the interrupting callback to execute after the running callback finishes execution. A value of 'cancel' discards the interrupting callback. The default value is 'queue'.

Callback Behavior When Interruption is Allowed

When an object’s Interruptible property is set to 'on', its callback can be interrupted at the next occurrence of one of these commands: drawnow, figure, getframe, waitfor, pause, or waitbar.

If the running callback contains one of these commands, then MATLAB stops the execution of the running callback and executes the interrupting callback. MATLAB resumes executing the running callback when the interrupting callback completes.
If the running callback does not contain one of these commands, then MATLAB finishes executing the callback without interruption.

For more details about the interruptible property and its effects, see the Interruptible property description on the UIControl Properties page.

Example

This example shows how to control callback interruption using the Interruptible and BusyAction properties and a wait bar.

Copy the Source File

In MATLAB, set your current folder to one in which you have write access.
Execute this MATLAB command:
copyfile(fullfile(docroot, 'techdoc','creating_guis','examples',... 'callback_interrupt.m')),fileattrib('callback_interrupt.m', '+w');

Run the Example Code

Execute the command, callback_interrupt. The program displays two windows.

Clicking specific pairs of buttons demonstrates the effect of different property value combinations :

Callback interruption — Click Wait (interruptible) immediately followed by either button in the second window: Surf Plot (queue) or Mesh Plot (cancel). The wait bar displays, but is momentarily interrupted by the plotting operation.
Callback queueing — Click Wait (uninterruptible) immediately followed by Surf Plot (queue). The wait bar runs to completion. Then the surface plot displays.
Callback cancellation — Click Wait (uninterruptible) immediately followed by Mesh Plot (cancel). The wait bar runs to completion. No plot displays because MATLAB discards the mesh plot callback.

Examine the Source Code

The Interruptible and BusyAction properties are passed as input arguments to the uicontrol function when each button is created.

Here is the command that creates the Wait (interruptible) push button. Notice that the Interruptible property is set to 'on'.

h_interrupt = uicontrol(h_panel1,'Style','pushbutton',...
                        'Position',[30,110,120,30],...
                        'String','Wait (interruptible)',...
                        'Tooltip','Interruptible = on',...
                        'Interruptible','on',...
                        'Callback',@wait_interruptible);

Here is the command that creates the Wait (uninterruptible) push button. Notice that the Interruptible property is set to 'off'.

h_nointerrupt = uicontrol(h_panel1,'Style','pushbutton',...
                        'Position',[30,40,120,30],...
                        'String','Wait (uninterruptible)',...
                        'Tooltip','Interruptible = off',...
                        'Interruptible','off',...
                        'Callback',@wait_uninterruptible);

Here is the command that creates the Surf Plot (queue) push button. Notice that the BusyAction property is set to 'queue'.

hsurf_queue = uicontrol(h_panel2,'Style','pushbutton',...
                        'Position',[30,200,110,30],...
                        'String','Surf Plot (queue)',...
                        'BusyAction','queue',...
                        'Tooltip','BusyAction = queue',...
                        'Callback',@surf_queue);

Here is the command that creates the Mesh Plot (cancel) push button. Notice that the BusyAction property is set to 'cancel'.

hmesh_cancel = uicontrol(h_panel2,'Style','pushbutton',...
                        'Position',[30,130,110,30],...
                        'String','Mesh Plot (cancel)',...
                        'BusyAction','cancel',...
                        'Tooltip','BusyAction = cancel',...
                        'Callback',@mesh_cancel);

Documentation