| Products & Services | Industries | Academia | Support | User Community | Company |
| Download Product Updates | | | Get Pricing | | | Trial Software |
| Documentation → MATLAB |
| Contents | Index |
| Learn more about MATLAB |
Use the Data Cursor tool
to label x, y, and z values on
graphs and surfaces. For details, see Data
Cursor — Displaying Data Values Interactively in the MATLAB Graphics
documentation.
datacursormode on
datacursormode off
datacursormode
datacursormode(figure_handle,...)
dcm_obj = datacursormode(figure_handle)
datacursormode on enables data cursor mode on the current figure.
datacursormode off disables data cursor mode on the current figure.
datacursormode toggles data cursor mode on the current figure.
datacursormode(figure_handle,...) enables or disables data cursor mode on the specified figure.
dcm_obj = datacursormode(figure_handle) returns the figure's data cursor mode object, which enables you to customize the data cursor. See Data Cursor Mode Object.
A data cursor is a small black square with a white border that you interactively position on a graph in data cursor mode. When you do this, a datatip) appears. Datatips are small text boxes or windows that float within an axes that display data values at data cursor locations. The default style is a text box. Datatips list x-, y- and (where appropriate) z-values for one data point at a time. See Examples for an illustration of these two styles.
Most types of graphs support data cursor mode, but several do not (pareto, for example). Polar plots support datatips, but display Cartesian rather than polar coordinates on them. Histograms created with hist display specialized datatips that itemize the observation counts, lower and upper limits and center point for histogram bins.
The data cursor mode object has properties that enable you to controls certain aspects of the data cursor. You can use the set and get commands and the returned object (dcm_obj in the above syntax) to set and query property values.
on | off
Specifies whether this mode is currently enabled on the figure.
on | off
Specifies whether the data cursor snaps to the nearest data value or is located at the actual pointer position.
datatip | window
Determines how the data is displayed.
datatip displays cursor information in a yellow text box next to a marker indicating the actual data point being displayed.
window displays cursor information in a floating window within the figure.
handle
Handle of the figure associated with the data cursor mode object.
function handle
This property references a function that customizes the text appearing in the data cursor. The function handle must reference a function that has two implicit arguments (these arguments are automatically passed to the function when it executes). For example, the following function definition line uses the required arguments:
function output_txt = myfunction(obj,event_obj) % obj Currently not used (empty) % event_obj Object containing event data structure % output_txt Data cursor text (string or cell array of strings)
event_obj is an object that contains a struct having the following fields.
Target | Handle of the object the data cursor is referencing (the object on which the user clicked) |
Position | An array specifying the x, y, (and z for 3-D graphs) coordinates of the cursor |
You can query these properties within your function. For example,
pos = get(event_obj,'Position');
returns the coordinates of the cursor. Another way of accessing that data is to obtain the struct and query its Position field.
eventdata = get(event_obj); pos = eventdata.Position;
See Function Handles for more information on creating a function handle.
See Change Data Cursor Text for an example.
The getCursorInfo function queries the data cursor mode object (dcm_obj in the above syntax) to obtain information about the data cursor. For example,
info_struct = getCursorInfo(dcm_obj);
returns a vector of structures, one for each data cursor on the graph. Each structure has the following fields.
Target | The handle of the graphics object containing the data point |
Position | An array specifying the x, y, (and z) coordinates of the cursor |
Line and lineseries objects have an additional field.
DataIndex | A scalar index into the data arrays that correspond to the nearest data point. The value is the same for each array. |
Note Do not change figure callbacks within an interactive mode. While a mode is active (when panning, zooming, etc.), you will receive a warning if you attempt to change any of the figure's callbacks and the operation will not succeed. The one exception to this rule is the figure WindowButtonMotionFcn callback, which can be changed from within a mode. Therefore, if you are creating a GUI that updates a figure's callbacks, the GUI should some keep track of which interactive mode is active, if any, before attempting to do this. |
This example creates a plot and enables data cursor mode from the command line.
surf(peaks)
datacursormode on
% Click mouse on surface to display data cursorSelecting a point on the surface opens a datatip displaying its x-, y-, and z-coordinates.

You change the datatip display style to be a window instead of a text box using the Tools > Options > Display cursor in window , or use the context menu Display Style > Window inside figure to view the datatip in a floating window that you can move around inside the axes.

You can position multiple text box datatips on the same graph, the window style of datatip displays only one value at a time. For more information on interacting with data cursors, including point selection options and exporting datatips to the workspace, see Data Cursor — Displaying Data Values Interactively in the MATLAB Graphics documentation.
This example enables data cursor mode on the current figure and sets data cursor mode options. The following statements
Create a graph
Toggle data cursor mode to on
Save the data cursor mode object to specify options and get the handle of the line to which the datatip is attached
fig = figure;
z = peaks;
plot(z(:,30:35))
dcm_obj = datacursormode(fig);
set(dcm_obj,'DisplayStyle','datatip',...
'SnapToDataVertex','off','Enable','on')
% Click on line to place datatip
c_info = getCursorInfo(dcm_obj);
set(c_info.Target,'LineWidth',2) % Make selected line wider

This example shows you how to customize the text that is displayed by the data cursor. Suppose you want to replace the text displayed in the datatip and data window with "Time:" and "Amplitude:"
Note Save the following functions in you current directory or any writable directory on the MATLAB path before running them. As they are functions, you cannot highlight them and then evaluate the selection to make them work. |
% After saving both these functions as M-files,
% execute the following one first by typing
% >> doc_datacursormode
function doc_datacursormode
fig = figure;
a = -16; t = 0:60;
plot(t,sin(a*t))
dcm_obj = datacursormode(fig);
set(dcm_obj,'UpdateFcn',@myupdatefcn)
% Now click on line to select data point to use the update function
function txt = myupdatefcn(empt,event_obj)
pos = get(event_obj,'Position');
txt = {['Time: ',num2str(pos(1))],...
['Amplitude: ',num2str(pos(2))]};Example — Visually Exploring Demographic Statistics for a further example of a data cursor update function
![]() | daspect | datatipinfo | ![]() |

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.
| © 1984-2009- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |