datacursormode

Enable, disable, and manage interactive data cursor mode

Syntax

datacursormode on
datacursormode off
datacursormode
datacursormode toggle
datacursormode(figure_handle)
dcm_obj = datacursormode(figure_handle)


Description

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.

Input Arguments

figure_handle	Optional handle of figure window Default: The current figure
state	'', 'toggle', 'on', or 'off' Default: 'toggle'

Output Arguments

dcm_obj

Use the object returned by datacursormode to control aspects of data cursor behavior. You can use the set and get commands to set and query object property values. You can customize how data cursor mode presents information by coding callback functions for these objects.

Name-Value Pair Arguments

The following parameters apply to objects returned by calls to datacursormode, not to the function itself.

DisplayStyle	datatip | window Determines how the data cursor displays. datatip displays data cursor information in a small yellow text box attached to a black square marker at a data point you interactively select. window displays data cursor information for the data point you interactively select in a floating window within the figure. Default: datatip
Enable	on | off Specifies whether data cursor mode is currently enabled for the figure. Default: off
Figure	handle Handle of the figure associated with the data cursor mode object.
Interpreter	none | tex | latex 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 Interpreter. Default: tex
SnapToDataVertex	on | off Specifies whether the data cursor snaps to the nearest data value or is located at the actual pointer position. Default: on
UpdateFcn	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 (~). The second argument passes the data cursor event object to your update function. The event object encapsulates the state of the data cursor. The following function definition illustrates the update function: function output_txt = myfunction(~,event_obj) % ~ Currently not used (empty) % event_obj Object containing event data structure % output_txt Data cursor text event_obj is an object that has the following properties. Target Handle of the object the data cursor is referencing (the object which you click, for example, a line or a bar from a series) 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; You can also obtain the position directly from the object: pos = event_obj.Position; You can redefine the data cursor Updatefcn at run time. For example: set(dcm_obj,'UpdateFcn',@myupdatefcn) applies the function 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 ButtonDownFcn, KeyPressFcn, or CloseRequestFcn while in data cursor mode. If you attempt to change any figure callbacks when you are in an interactive mode, you receive a warning and the attempt fails. MATLAB interactive modes are: brush datacursormode pan rotate3d zoom This restriction does not apply to changing the figure WindowButtonMotionFcn callback or uicontrol callbacks.

Querying Data Cursor Mode

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.

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.

See Output Arguments for more details on data cursor mode objects.

Examples

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

When you place a data tip using this update function, it looks like the one in the following figure.

Tips

• Most types of graphs and 3-D plots support data cursor mode, but several do not (pareto, for example).

• Polar plots support data tips, but display Cartesian rather than polar coordinates on them.

• Histograms created with histogram display specialized data tips that itemize the observation counts and bin edges.

• You place data tips only by clicking data objects on graphs. You cannot place them programmatically (by executing code to position a data cursor).

• When DisplayStyle is datatip, you can place multiple data tips on a graph. When DisplayStyle is window, it reports only the most recent data tip.

• datacursormode off exits data cursor mode but does not remove displayed data tips. However, if the DisplayStyle is window, the data tip window goes away.

Alternatives

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.