Enable, disable, and manage interactive data cursor mode
datacursormode on
datacursormode off
datacursormode
datacursormode toggle
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. Starting in R2018b, some data cursor interactions are enabled by
default, regardless of the mode. If you want to disable these default interactions, then
use the disableDefaultInteractivity
function.
datacursormode
or datacursormode toggle
toggles data cursor
mode in the current figure.
datacursormode(figure_handle)
enables
or disables data cursor mode on the specified figure.
dcm_obj = datacursormode(figure_handle)
returns
the data cursor mode object for the figure. The object enables you
to customize the data cursor. For more information on data cursor
mode objects, see Output Arguments. You
cannot change the state of data cursor mode in a call to datacursormode
that
returns a 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 click a graphic object such as a line on a graph, a data tip appears. Data tips 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. Data tips list x-, y- and (where appropriate) z-values for one data point at a time. See Examples for an illustration of these two styles.
|
Optional handle of figure window Default: The current figure |
|
Default: |
|
Use the object returned by |
The following parameters apply to objects returned by calls
to datacursormode
, not to the function itself.
|
Determines how the data cursor displays.
Default: | ||||
|
Specifies whether data cursor mode is currently enabled for the figure. Default: | ||||
|
handle Handle of the figure associated with the data cursor mode object. | ||||
|
Specifies the interpretation of text characters. Use TeX markup to add
superscripts and subscripts, modify the font type and color, and include
special characters in the text. For more information, see Default: | ||||
|
Specifies whether the data cursor snaps to the nearest data value or is located at the actual pointer position. Default: | ||||
|
function handle Reference to a function that formats the text appearing in the
data cursor. You can supply your own function to customize data tip
display. Your function must include at least two arguments. The first
argument is unused, and can be a variable name or tilde ( function output_txt = myfunction(~,event_obj) % ~ Currently not used (empty) % event_obj Object containing event data structure % output_txt Data cursor text
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 eventdata = get(event_obj); pos = eventdata.Position; pos = event_obj.Position; You can redefine the data cursor set(dcm_obj,'UpdateFcn',@myupdatefcn) myupdatefcn to the current data
tip or tips. When you set an update function in this way, the function
must be on the MATLAB® path. If instead you select the data cursor
mode context menu item Select text update function,
you can interactively select a function that is not on the path.
Do not redefine figure window callbacks,
such as
This restriction does not apply to changing the figure |
Use the getCursorInfo
function to query
the data cursor mode object (dcm_obj
in the update
function 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.
| The handle of the graphics object containing the data point |
| An array specifying the x, y, (and z) coordinates of the cursor |
Line and lineseries objects have an additional field.
| A scalar index into the data arrays that correspond to the nearest data point. The value is the same for each array. |
See Output Arguments for more details on data cursor mode objects.
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 cursor
Selecting a point on the surface opens a data tip displaying its x-, y-, and z-coordinates.
You change the data tip 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 data tip in a floating window that you can move around inside the axes.
You can position multiple text box data tips on the same graph, the window style of data tip displays only one value at a time.
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
Obtain the data cursor mode object, specify data tip options, and get the handle of the line the data tip occupies:
fig = figure; z = peaks; plot(z(:,30:35)) dcm_obj = datacursormode(fig); set(dcm_obj,'DisplayStyle','datatip',... 'SnapToDataVertex','off','Enable','on') disp('Click line to display a data tip, then press Return.') % Wait while the user does this. pause c_info = getCursorInfo(dcm_obj); % Make selected line wider set(c_info.Target,'LineWidth',2)
This example shows you how to customize the text that the data
cursor displays. For example, you can replace the text displayed in
the data tip and data window (x:
and y:
)
with Time:
and Amplitude:
by
creating a simple update function.
Save the following functions in your 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.
Save this code as doc_datacursormode.m
:
function doc_datacursormode % Plots graph and sets up a custom data tip update function fig = figure; a = -16; t = 0:60; plot(t,sin(a*t)) dcm_obj = datacursormode(fig); set(dcm_obj,'UpdateFcn',@myupdatefcn)
Save the following code as myupdatefcn.m
on
the MATLAB path:
function txt = myupdatefcn(empt,event_obj) % Customizes text of data tips pos = get(event_obj,'Position'); txt = {['Time: ',num2str(pos(1))],... ['Amplitude: ',num2str(pos(2))]};
To set up and use the update function, type:
doc_datacursormode
You can create data tips on most types of graphs and 3-D plots. However,
some types of plots do not support data cursor mode, such as pie charts
created with pie
.
In general, data tips show the coordinates of the selected point. However,
for some types of charts, data tips display specialized information. For
example, histograms created with histogram
display data
tips that itemize the observation counts and bin edges.
When the DisplayStyle
property of the data cursor
mode object is 'datatip'
, you can create multiple data
tips by holding Shift as you select data points. When the
DisplayStyle
is 'window'
, you
can create only one data tip at a time.
Data tips on a plot persist if you turn off data cursor mode when the
DisplayStyle
property is
'datatip'
. However, the data cursor disappears and
the data tip window closes when the DisplayStyle
is
'window'
.
Use the Data Cursor button in the toolbar to label x, y, and z values on graphs and surfaces. You can control how data tips display by right-clicking and selecting items from the context menu.