Create Callbacks for Graphics Objects

What Is a Callback?

A callback is a command that executes in response to some predefined user action, such as clicking on a graphics object or closing a figure window. You can program a response to specific user action by writing a callback function to process the action and then assigning the function to the callback property associated with that user action. For example, you can create a ButtonDownFcn callback for a figure to program a response to a user clicking the figure.

This topic contains examples of writing callbacks for graphics objects such as Line, Axes, or Figure objects. For a list of callbacks associated with a specific graphics object, see the properties of that object. For example, for a list of Figure callbacks, see Figure Properties.

For information about writing callbacks for UI components in an app, see Create Callbacks for Apps Created Programmatically.

Create Basic Callback

Graphics callback functions must accept at least two input arguments:

The graphics object whose callback is executing — Use this argument within your callback function to refer to the object.
The event data structure — Use this argument within your callback function to access information about the user action that is specific to the callback property and the object. This structure is empty for many graphics object callbacks.

Whenever a callback executes in response to a user action, MATLAB^® calls the callback function and passes these two arguments to the function.

To create a callback, first define a callback function with the required input arguments. Then, assign a handle to the function to the relevant callback property.

Define Callback Function

For example, create a new file named figureCallback.m and define a callback function named figureCallback. The callback function processes the action when a user presses a key in a figure window. Define the callback function to accept two input arguments:

src — Use the first argument to refer to the specific figure whose callback is executing to find the Line object plotted in the figure.
event — Use the second argument to access specific information about the key press user action. If the key that was pressed is +, increase the width of the line, and if it is -, decrease the width of the line.

function figureCallback(src,event)
line = findobj(src,"Type","Line");
if event.Character == "+"
    line.LineWidth = line.LineWidth+1;
elseif event.Character == "-"
    line.LineWidth = max(line.LineWidth-1,0.5);
end
end

Assign Callback Function to Callback Property

In the Command Window, create a Figure object. Use the @ operator to assign the function handle to the WindowKeyPressFcn property of the figure. This callback executes when a user presses a key in the figure window. Then, plot some data in the current figure.

f = figure(WindowKeyPressFcn=@figureCallback);
plot(1:10)

Run the code and press +. The line width increases.

Note

Keyboard-based callbacks are not currently supported for figures in the Live Editor. For more information, see Figure Properties.

Create Callback with Additional Input Arguments

You can create a callback with additional input arguments by using an anonymous function. First, define a callback function with any number of input arguments. Then, specify the relevant callback property value as an anonymous function that accepts the required source and event arguments that MATLAB passes to the callback, and then calls your callback function with the appropriate inputs.

Note

Creating a callback as an anonymous function is not currently supported for figures in the Live Editor.

Define Callback Function

For example, define a callback function that changes the marker edge color and then displays x- and y-coordinates in the Command Window when a user clicks a marker. Create a new file named displayCoordinates.m and define a callback function named displayCoordinates. Define the callback function to accept three input arguments:

src — Use the first argument to refer to the specific graphics object whose callback is executing.
~ — Specify the ~ character for the second argument to indicate that the function does not use the callback event data.
ax — Use the third argument to access the location of the mouse pointer on the axes.

function displayCoordinates(src,~,ax)
src.MarkerEdgeColor = rand(1,3);
disp(ax.CurrentPoint(1,1:2))
end

Assign Callback Function to Callback Property

In the Command Window, plot some data on an axes object using the scatter function. Specify the ButtonDownFcn callback property of the Scatter object using an anonymous function. The anonymous function accepts the source and event arguments that MATLAB passes to the callback and then calls the displayCoordinates function with the required inputs.

ax = axes;
x = randn(100,1);
y = randn(100,1);
scatter(x,y,"ButtonDownFcn",@(src,event)displayCoordinates(src,event,ax))

Run the code and click a marker. The marker edge color changes, and the x- and y-coordinates display in the Command Window.

For more information, see Anonymous Functions.

While anonymous functions provide the most flexibility for specifying callback input arguments beyond the source and event inputs, in certain cases an alternative is to specify a callback using a cell array. If your callback function accepts both the source and event inputs followed by any other arguments, you can assign the callback by specifying a cell array. The first element of the cell array is the callback function handle, and any additional elements are the inputs to pass to the function after the source and event.

For example, you can instead specify the ButtonDownFcn callback property of the Scatter object using a cell array. The first element of the array is a handle to the displayCoordinates function, and the second element is the axes object that is passed to the displayCoordinates function after the source and event arguments.

ax = axes;
x = randn(100,1);
y = randn(100,1);
scatter(x,y,"ButtonDownFcn",{@displayCoordinates,ax})

Create Callback as a Default

When you call a plotting function, such as plot or bar, MATLAB creates new graphics objects and resets most figure and axes properties. Therefore, callback functions that you have defined for specific graphics objects might be removed by MATLAB. To instead create a callback that executes for all objects of a specific type, assign a callback function as a default on the root level.

Define Callback Function

Define a function named customizeGrid in a new file named customizeGrid.m. The function takes in an axes object and turns on and customizes its grid lines.

function customizeGrid(ax)
ax.XGrid = 'on';
ax.YGrid = 'on';
ax.GridLineStyle = '--';
ax.GridAlpha = 0.5;
end

Assign Callback Function to Callback Property

Execute the customizeGrid function whenever MATLAB creates a new axes object by setting a default axes CreateFcn callback on the groot object. Assign the property as an anonymous function that takes in the two required callback inputs and then calls the customizeGrid function for the Axes object being created.

set(groot,"defaultAxesCreateFcn",@(src,~)customizeGrid(src))

Create multiple axes in a figure. The customized grid appears for each of them.

ax1 = axes("Position",[0.1 0.1 0.8 0.35]);
ax2 = axes("Position",[0.1 0.55 0.8 0.35]);

For more information, see Default Property Values.

The default callback remains set for the MATLAB session. To set a default callback for every MATLAB session, add the default value assignment to your startup.m file. For more information, see startup.