Create Callbacks for Graphics Objects - MATLAB & Simulink (original) (raw)
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 asLine, 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 theLineobject 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 theWindowKeyPressFcn 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 nameddisplayCoordinates.m and define a callback function nameddisplayCoordinates. 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 thescatter function. Specify theButtonDownFcn callback property of theScatter object using an anonymous function. The anonymous function accepts the source and event arguments that MATLAB passes to the callback and then calls thedisplayCoordinates 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 thedisplayCoordinates 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 orbar, 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 namedcustomizeGrid.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 axesCreateFcn callback on the groot object. Assign the property as an anonymous function that takes in the two required callback inputs and then calls thecustomizeGrid 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 yourstartup.m file. For more information, see startup.