Learn more about MATLAB

Callback Interruption

On this page…
Callback Execution How the Interruptible Property Works How the Busy Action Property Works Example

Callback Execution

Callback execution is event driven and callbacks from different GUIs share the same event queue. In general, callbacks are triggered by user events such as a mouse click or key press. Because of this, you cannot predict, when a callback is requested, whether or not another callback is executing or, if one is, which callback it is.

If a callback is executing and the user triggers an event for which a callback is defined, that callback attempts to interrupt the callback that is already executing. When this occurs, MATLAB software processes the callbacks according to these factors:

• The Interruptible property of the object whose callback is already executing. The Interruptible property specifies whether the executing callback can be interrupted.

• The BusyAction property of the object whose callback has just been triggered and wants to execute. The BusyAction property specifies whether a callback should be queued to await execution or be canceled.

Note   For information about what callbacks are and do, see Callbacks: An Overview in this User's Guide and also Callback Properties for Graphics Objects in the MATLAB Graphics documentation.

Back to Top

How the Interruptible Property Works

An object's Interruptible property can be either on (the default) or off.

If theInterruptible property of the object whose callback is executing is on, the callback can be interrupted. However, it is interrupted only when it, or a function it triggers, calls drawnow, figure, getframe, pause, or waitfor. Before performing their defined tasks, these functions process any events in the event queue, including any waiting callbacks. If the executing callback, or a function it triggers, calls none of these functions, it cannot be interrupted regardless of the value of its object's Interruptible property.

If the Interruptible property of the object whose callback is executing is off, the callback cannot be interrupted with the following exceptions. If the interrupting callback is a DeleteFcn or CreateFcn callback or a figure's CloseRequest or ResizeFcn callback, it interrupts an executing callback regardless of the value of the executing callback object's Interruptible property. These callbacks too can interrupt only when a drawnow, figure, getframe, pause, or waitfor function executes.

The callback properties to which Interruptible can apply depend on the objects for which the callback properties are defined:

• For figures, only callback routines defined for the ButtonDownFcn, KeyPressFcn, KeyReleaseFcn, WindowButtonDownFcn, WindowButtonMotionFcn, WindowButtonUpFcn, and WindowScrollWheelFcn are affected by the Interruptible property.

  For callbacks that can be issued continuously, such as most of the above, setting the figure's Interruptible property to 'off' might be necessary if callbacks from other objects or GUIs could fire while they are being issued. That is, do not interrupt callbacks that keep on coming if there is not a specific reason to do so.

• For GUI components, Interruptible applies to the ButtonDownFcn, Callback, CellSelectionCallback, KeyPressFcn, SelectionChangeFcn, ClickedCallback, OffCallback, and OnCallback properties, for the components for which these properties are defined.

To prevent continuously repeating callbacks such as the above from being interrupted, set the value of the Interruptible property of the object whose callback is repeating to 'off':

set(hObject,'Interruptible','off');

where hObject is the handle to the object whose callback is called continuously (for example, to load another GUIDE GUI).

Back to Top

How the Busy Action Property Works

An object's BusyAction property can be either queue (the default) or cancel. The BusyAction property of the interrupting callback's object is taken into account only if the Interruptible property of the executing callback's object is off, i.e., the executing callback is not interruptible.

If a noninterruptible callback is executing and an event (such as a mouse click) triggers a new callback, MATLAB software uses the value of the new callback object's BusyAction property to decide whether to queue the requested callback or cancel it.

• If the BusyAction value is queue, the requested callback is added to the event queue and executes in its turn when the executing callback finishes execution.

• If the value is cancel, the event is discarded and the requested callback does not execute.

If an interruptible callback is executing, the requested callback runs when the executing callback terminates or calls drawnow, figure, getframe, pause, or waitfor. The BusyAction property of the requested callback's object has no effect.

Back to Top

Example

This example demonstrates control of callback interruption using the Interruptible and BusyAction properties. It creates two GUIs:

• The first GUI contains two push buttons, Wait (interruptible) whose Interruptible property is set to on, and Wait (noninterruptible)whose Interruptible property is set to off. Clicking either button triggers the button's Callback callback, which creates and updates a waitbar.

  

  This code creates the two Wait buttons and specifies the callbacks that service them.

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

• The second GUI contains two push buttons, Surf Plot (queue) whose BusyAction property is set to queue, and Mesh Plot (cancel)whose BusyAction property is set to cancel. Clicking either button triggers the button's Callback callback to generate a plot in the axes.

  

  This code creates the two plot buttons and specifies the callbacks that service them.

  hsurf_queue = uicontrol(h_panel2,'Style','pushbutton',...
                          'Position',[30,200,110,30],...
                          'String','Surf Plot (queue)',...
                          'TooltipString','BusyAction = queue',...
                          'BusyAction','queue',...
                          'Callback',@surf_queue);
  hmesh_cancel = uicontrol(h_panel2,'Style','pushbutton',...
                          'Position',[30,130,110,30],...
                          'String','Mesh Plot (cancel)',...
                          'BusyAction','cancel',...
                          'TooltipString','BusyAction = cancel',...
                          'Callback',@mesh_cancel);

Using the Example GUIs

Click here to run the example GUIs.

Note   This link executes MATLAB commands and is designed to work within the MATLAB Help browser. If you are reading this online or in PDF, you should go to the corresponding section in the MATLAB Help Browser to use the link.

To see the interplay of the Interruptible and BusyAction properties:

1. Click one of the Wait buttons in the first GUI. Both buttons create and update a waitbar.

2. While the waitbar is active, click either the Surf Plot or the Mesh Plot button in the second GUI. The Surf Plot button creates a surf plot using peaks data. The Mesh Plot button creates a mesh plot using the same data.

The following topics describe what happens when you click specific combinations of buttons:

• Clicking a Wait Button

• Clicking a Plot Button

Clicking a Wait Button.  

The Wait buttons are the same except for their Interruptible properties. Their Callback callbacks, which are essentially the same, call the utility function create_update_waitbar which calls waitbar to create and update a waitbar. The Wait (Interruptible) button Callback callback,wait_interruptible, can be interrupted each time waitbar calls drawnow. The Wait (Noninterruptible) button Callback callback,wait_noninterruptible, cannot be interrupted (except by specific callbacks listed in How the Interruptible Property Works).

This is the Wait (Interruptible) button Callback callback,wait_interruptible:

    function wait_interruptible(hObject,eventdata)
        % Disable the other push button.
        set(h_noninterrupt,'Enable','off')
        % Clear the axes in the other GUI.
        cla(h_axes2,'reset')
        % Create and update the waitbar.
        create_update_waitbar
        % Enable the other push button
        set(h_noninterrupt,'Enable','on')
    end

The callback first disables the other push button and clears the axes in the second GUI. It then calls the utility function create_update_waitbar to create and update a waitbar. When create_update_waitbar returns, it enables the other button.

Clicking a Plot Button.   What happens when you click a Plot button depends on which Wait button you clicked first and the BusyAction property of the Plot button.

• If you click Surf Plot, whose BusyAction property is queue, MATLAB software queues the Surf Plot callback surf_queue.

  If you clicked the Wait (interruptible) button first, surf_queue runs and displays the surf plot when the waitbar issues a call to drawnow, terminates, or is destroyed.

  If you clicked the Wait (noninterruptible) button first, surf_queue runs only when the waitbar terminates or is destroyed.

  This is the surf_queue callback:

  function surf_queue(hObject,eventdata)
          h_plot = surf(h_axes2,peaks_data);
      end

• If you click Mesh Plot , whose BusyAction property is cancel, after having clicked Wait (noninterruptible), MATLAB software discards the button click event and does not queue the mesh_cancel callback.

  If you click Mesh Plot after having clicked Wait (interruptible), the Mesh Plot BusyAction property has no effect. MATLAB software queues the Mesh Plot callback, mesh_cancel. It runs and displays the mesh plot when the waitbar issues a call to drawnow, terminates, or is destroyed.

  This is the mesh_plot callback:

  function mesh_cancel(hObject,eventdata)
          h_plot = surf(h_axes2,peaks_data);
      end

View the Complete GUI M-File

If you are reading this in the MATLAB Help browser, you can click here to display a complete listing of the code used in this example in the MATLAB Editor.

Note   This link executes MATLAB commands and is designed to work within the MATLAB Help browser. If you are reading this online or in PDF, you should go to the corresponding section in the MATLAB Help Browser to use the links.

Back to Top

Managing Callback Execution

Examples of GUIs Created Programmatically

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS