Documentation

This is machine translation

Translated by Microsoft
Mouse over text to see original. Click the button below to return to the English verison of the page.

Write Callbacks for Apps Created Programmatically

Callbacks for Different User Actions

UI and graphics components have certain properties that you can associate with specific callback functions. Each of these properties corresponds to a specific user action. For example, a uicontrol has a property called Callback. You can set the value of this property to be a handle to a callback function, an anonymous function, or a character vector containing a MATLAB® expression. Setting this property makes your app respond when the user interacts with the uicontrol. If the Callback property has no specified value, then nothing happens when the user interacts with the uicontrol.

This table lists the callback properties that are available, the user actions that trigger the callback function, and the most common UI and graphics components that use them.

Callback Property

User Action

Components That Use This Property

ButtonDownFcn

End user presses a mouse button while the pointer is on the component or figure.

axes, figure, uibuttongroup, uicontrol, uipanel, uitable,

Callback

End user triggers the component. For example: selecting a menu item, moving a slider, or pressing a push button.

uicontextmenu, uicontrol, uimenu

CellEditCallback

End user edits a value in a table whose cells are editable.

uitable

CellSelectionCallback

End user selects cells in a table.

uitable

ClickedCallback

End user clicks the push tool or toggle tool with the left mouse button.

uitoggletool, uipushtool

CloseRequestFcn

The figure closes.

figure

CreateFcn

Callback executes when MATLAB creates the object, but before it is displayed.

axes, figure, uibuttongroup, uicontextmenu, uicontrol, uimenu, uipushtool, uipanel, uitable, uitoggletool, uitoolbar

DeleteFcn

Callback executes just before MATLAB deletes the figure.

axes, figure, uibuttongroup, uicontextmenu, uicontrol, uimenu, uipushtool, uipanel, uitable, uitoggletool, uitoolbar

KeyPressFcn

End user presses a keyboard key while the pointer is on the object.

figure, uicontrol, uipanel, uipushtool, uitable, uitoolbar

KeyReleaseFcn

End user releases a keyboard key while the pointer is on the object.

figure, uicontrol, uitable

OffCallback

Executes when the State of a toggle tool changes to 'off'.

uitoggletool

OnCallback

Executes when the State of a toggle tool changes to 'on'.

uitoggletool

SizeChangedFcn

End user resizes a button group, figure, or panel whose Resize property is 'on'.

figure, uipanel, uibuttongroup

SelectionChangedFcn

End user selects a different radio button or toggle button within a button group.

uibuttongroup

WindowButtonDownFcn

End user presses a mouse button while the pointer is in the figure window.

figure

WindowButtonMotionFcn

End user moves the pointer within the figure window.

figure

WindowButtonUpFcn

End user releases a mouse button.

figure

WindowKeyPressFcn

End user presses a key while the pointer is on the figure or any of its child objects.

figure

WindowKeyReleaseFcn

End user releases a key while the pointer is on the figure or any of its child objects.

figure

WindowScrollWheelFcn

End user turns the mouse wheel while the pointer is on the figure.

figure

How to Specify Callback Property Values

To associate a callback function with a UI component, set the value of one of the component's callback properties to be a reference to the callback function. Typically, you do this when you define the component, but you can change callback property values anywhere in your code.

Specify the callback property value in one of the following ways:

Specify a Function Handle

Function handles provide a way to represent a function as a variable. The function must be a local or nested function in the same file as the app code, or you can write it in a separate file that is on the MATLAB path.

To create the function handle, specify the @ operator before the name of the function. For example, this uicontrol command specifies the Callback property to be a handle to the function pushbutton_callback:

b = uicontrol('Style','pushbutton','Callback',@pushbutton_callback);

Here is the function definition for pushbutton_callback:

function pushbutton_callback(src,event)
   display('Button pressed');
end
Notice that the function handle does not explicitly refer to any input arguments, but the function declaration includes two input arguments. These two input arguments are required for all callbacks you specify as a function handle. MATLAB passes these arguments automatically when the callback executes. The first argument is the UI component that triggered the callback. The second argument provides event data to the callback function. If there is no event data available to the callback function, then MATLAB passes the second input argument as an empty array. The following table lists the callbacks and components that use event data.

Callback Property NameComponent
WindowKeyPressFcn
WindowKeyReleaseFcn
WindowScrollWheel
figure
KeyPressFcnfigure, uicontrol, uitable
KeyReleaseFcnfigure, uicontrol, uitable
SelectionChangedFcnuibuttongroup
CellEditCallback
CellSelectionCallback
uitable

A benefit of specifying callbacks as function handles is that MATLAB checks the function for syntax errors and missing dependencies when you assign the callback to the component. If there is a problem in the callback function, then MATLAB returns an error immediately instead of waiting for the user to trigger the callback. This behavior helps you to find problems in your code before the user encounters them.

Specify a Cell Array

Use a cell array to specify a callback function that accepts additional input arguments that you want to use in the function. The first element in the cell array is a function handle. The other elements in the cell array are the additional input arguments you want to use, separated by commas. The function you specify must define the same two input arguments as described in Specify a Function Handle. However, you can define additional inputs in your function declaration after the first two arguments.

This uicontrol command creates a push button and specifies the Callback property to be a cell array. In this case, the name of the function is pushbutton_callback, and the value of the additional input argument is 5.

b = uicontrol('Style','pushbutton','Callback',{@pushbutton_callback,5});

Here is the function definition for pushbutton_callback:

function pushbutton_callback(src,event,x)
   display(x);
end

Like callbacks specified as function handles, MATLAB checks callbacks specified as cell arrays for syntax errors and missing dependencies when you assign the callback to the component. If there is a problem in the callback function, then MATLAB returns an error immediately instead of waiting for the user to trigger the callback. This behavior helps you to find problems in your code before the user encounters them.

Specify an Anonymous Function

Specify an anonymous function when you want a UI component to execute a function that does not support the two arguments that are required for function handles and cell arrays. For example, this uicontrol command creates a push button and specifies the Callback property to be an anonymous function. In this case, the name of function is myfun, and its function declaration defines only one input argument, x.

b = uicontrol('Style','pushbutton','Callback',@(src,event)myfun(x));

Specify a Character Vector Containing MATLAB Commands (Not Recommended)

You can specify a character vector when you want to execute a few simple commands, but the callback can become difficult to manage if it contains more than a few commands. The character vector you specify must consist of valid MATLAB expressions, which can include arguments to functions. For example:

hb = uicontrol('Style','pushbutton',...
               'String','Plot line',...
               'Callback','plot(rand(20,3))');
The character vector, 'plot(rand(20,3))', is a valid command, and MATLAB evaluates it when the user clicks the button. If the character vector includes a variable, for example,
'plot(x)'
The variable x must exist in the base workspace when the user triggers the callback, or it returns an error. The variable does not need to exist at the time you assign callback property value, but it must exist when the user triggers the callback.

Unlike callbacks that are specified as function handles or cell arrays, MATLAB does not check character vectors for syntax errors or missing dependencies. If there is a problem with the MATLAB expression, it remains undetected until the user triggers the callback.

Related Examples

Was this topic helpful?