datacursormode

Enable data cursor mode

Description

Data tips are small text boxes that display information about individual data points. In releases prior to R2018b, use the datacursormode function to create and edit data tips. Control data tip appearance and behavior by using datacursormode to create a data cursor manager object.

Starting in R2018b, you can create and edit data tips using built-in interactions instead. Built-in interactions do not require you to enable a mode and respond faster than interaction modes. For more information about built-in interactions, see Control Chart Interactivity.

Most charts support data tips, including line, bar, histogram, and surface charts. Charts that support data tips typically display the data tips icon in the axes toolbar.

Creation

Syntax

datacursormode on

datacursormode off

datacursormode

datacursormode(fig,___)

dcm = datacursormode

dcm = datacursormode(fig)

Description

datacursormode on turns on data cursor mode for charts in the current figure. With data cursor mode on, create a data tip by clicking a data point. To create multiple data tips, hold the Shift key while clicking the data points.

datacursormode off turns off data cursor mode. This command does not remove existing data tips. Some built-in interactions are enabled by default, regardless of the mode. To disable built-in data tip interactions, use the disableDefaultInteractivity function.

datacursormode toggles data cursor mode between 'on' and 'off'. This syntax is the same as datacursormode toggle.

datacursormode(fig,___) sets the data cursor mode for charts in the specified figure. Specify the additional argument as 'on', 'off', or 'toggle'. For example, use datacursormode(fig,'on').

dcm = datacursormode creates a data cursor manager object for the current figure. This syntax is useful for controlling the data cursor mode, data tip display style, and data tip text format.

dcm = datacursormode(fig) creates a data cursor manager object for the specified figure.

Input Arguments

fig — Target figure

Figure object

Target figure, specified as a Figure object.

Properties

SnapToDataVertex — Display at closest data point

'on' (default) | 'off'

Display at closest data point, specified as one of these values:

• 'on' – Display data tip at the closest data point. The closest data point depends on the type of chart. For example, on a line chart the closest point has the smallest Euclidean distance from the specified location.

• 'off' – Display data tip at the location you click, even if it is between data points.

DisplayStyle — Data tip display style

'datatip' (default) | 'window'

Data tip display style, specified as one of these values:

• 'datatip' – Display data tips as small text boxes attached to data values. Create multiple data tips by holding Shift as you select data points. If you turn off data cursor mode, existing data tips remain on the chart.

• 'window' – Display data tips in a moveable window within the figure. When the display style is 'window', you can only display one data tip at a time. If you turn off data cursor mode, the window closes.

Interpreter — Text interpreter

'tex' (default) | 'latex' | 'none'

Text interpreter, specified as one of these values:

• 'tex' — Interpret characters using a subset of TeX markup.

• 'latex' — Interpret characters using LaTeX markup.

• 'none' — Display literal characters.

TeX Markup

By default, MATLAB^® supports a subset of TeX markup. Use TeX markup to add superscripts and subscripts, modify the font type and color, and include special characters in the text.

Modifiers remain in effect until the end of the text. Superscripts and subscripts are an exception because they modify only the next character or the characters within the curly braces. When you set the interpreter to 'tex', the supported modifiers are as follows.

Modifier	Description	Example
^{ }	Superscript	'text^{superscript}'
_{ }	Subscript	'text_{subscript}'
\bf	Bold font	'\bf text'
\it	Italic font	'\it text'
\sl	Oblique font (usually the same as italic font)	'\sl text'
\rm	Normal font	'\rm text'
\fontname{specifier}	Font name — Replace specifier with the name of a font family. You can use this in combination with other modifiers.	'\fontname{Courier} text'
\fontsize{specifier}	Font size —Replace specifier with a numeric scalar value in point units.	'\fontsize{15} text'
\color{specifier}	Font color — Replace specifier with one of these colors: red, green, yellow, magenta, blue, black, white, gray, darkGreen, orange, or lightBlue.	'\color{magenta} text'
\color[rgb]{specifier}	Custom font color — Replace specifier with a three-element RGB triplet.	'\color[rgb]{0,0.5,0.5} text'

This table lists the supported special characters for the 'tex' interpreter.

Character Sequence	Symbol	Character Sequence	Symbol	Character Sequence	Symbol
\alpha	α	\upsilon	υ	\sim	~
\angle	∠	\phi		\leq	≤
\ast	*	\chi	χ	\infty	∞
\beta	β	\psi	ψ	\clubsuit	♣
\gamma	γ	\omega	ω	\diamondsuit	♦
\delta	δ	\Gamma	Γ	\heartsuit	♥
\epsilon	ϵ	\Delta	Δ	\spadesuit	♠
\zeta	ζ	\Theta	Θ	\leftrightarrow	↔
\eta	η	\Lambda	Λ	\leftarrow	←
\theta	θ	\Xi	Ξ	\Leftarrow	⇐
\vartheta	ϑ	\Pi	Π	\uparrow	↑
\iota	ι	\Sigma	Σ	\rightarrow	→
\kappa	κ	\Upsilon	ϒ	\Rightarrow	⇒
\lambda	λ	\Phi	Φ	\downarrow	↓
\mu	µ	\Psi	Ψ	\circ	º
\nu	ν	\Omega	Ω	\pm	±
\xi	ξ	\forall	∀	\geq	≥
\pi	π	\exists	∃	\propto	∝
\rho	ρ	\ni	∍	\partial	∂
\sigma	σ	\cong	≅	\bullet	•
\varsigma	ς	\approx	≈	\div	÷
\tau	τ	\Re	ℜ	\neq	≠
\equiv	≡	\oplus	⊕	\aleph	ℵ
\Im	ℑ	\cup	∪	\wp	℘
\otimes	⊗	\subseteq	⊆	\oslash	∅
\cap	∩	\in	∈	\supseteq	⊇
\supset	⊃	\lceil	⌈	\subset	⊂
\int	∫	\cdot	·	\o	ο
\rfloor	⌋	\neg	¬	\nabla	∇
\lfloor	⌊	\times	x	\ldots	...
\perp	⊥	\surd	√	\prime	´
\wedge	∧	\varpi	ϖ	\0	∅
\rceil	⌉	\rangle	〉	\mid	|
\vee	∨	\langle	〈	\copyright	©

LaTeX Markup

To use LaTeX markup, set the interpreter to 'latex'. Use dollar symbols around the text, for example, use '$\int_1^{20} x^2 dx$' for inline mode or '$$\int_1^{20} x^2 dx$$' for display mode.

The displayed text uses the default LaTeX font style. To change the font style, use LaTeX markup.

The maximum size of the text that you can use with the LaTeX interpreter is 1200 characters. For multiline text, this reduces by about 10 characters per line.

For more information about the LaTeX system, see The LaTeX Project website at https://www.latex-project.org/.

Enable — Data cursor mode

'off' (default) | 'on'

Data cursor mode, specified as 'off' or 'on'.

UpdateFcn — Callback function that formats data tip text

[] (default) | function handle

Callback function that formats data tip text, specified as a function handle.

Use this property to format the content of data tips. MATLAB passes two arguments to the callback function:

• empty – Empty argument. Replace it with the tilde character (~) in the function to indicate that it is not used.

• info – Structure containing information about the data tip. The info argument has two fields, Target and Position. The Target field contains an object with a DataTipTemplate property. The Position field contains the coordinates of the data tip.

The function must be on the MATLAB path or in the current folder. Alternatively, you can select a function that is not on the MATLAB path by selecting Update Function > Choose from File from the data tip context menu.

For more information about callbacks, see Callback Definition.

Figure — Figure object

Figure object

This property is read-only.

Figure object in which data tips appear.

Object Functions

getCursorInfo

info = getCursorInfo(dcm) returns the target and coordinates of each data tip in the figure. info is a vector of structures with these fields: Target – An object with a DataTipTemplate property, such as Line, Histogram, Surface, or FunctionLine. Position – Coordinates of the data tip. The interpretation of the coordinates depends on the type of axes. For example, the coordinates of Cartesian axes are x, y, and z in the same units as your data. DataIndex (for Line objects only) – Index of the plotted data. For example, the plotted data of a 2-D object on a set of Cartesian axes is contained in its XData and YData properties.

Examples

Display Data Tip in Moveable Window

Plot some data, create a DataCursorManager object, and enable data cursor mode. Display data tip content in a moveable window by setting the DisplayStyle property to 'window'. Then, create a data tip by clicking on a data point. You can move the data tip window by clicking on the window heading and dragging.

x = linspace(0,5,30);
y = exp(x);
scatter(x,y)
dcm = datacursormode;
dcm.Enable = 'on';
dcm.DisplayStyle = 'window';

Customize Data Tip Text

Customize data tip text by setting the UpdateFcn property of the DataCursorMode object.

First, define a callback function that accepts data tip information and returns customized text. The UpdateFcn property does not use the first argument of the callback function, so replace it with ~. Return the customized text as a character array, in this case containing an ordered pair of coordinates. Save the function as a program file called displayCoordinates.m.

function txt = displayCoordinates(~,info)
    x = info.Position(1);
    y = info.Position(2);
    txt = ['(' num2str(x) ', ' num2str(y) ')'];
end

Plot some data, enable data cursor mode, and set the UpdateFcn property to the callback function. Then, create a data tip by clicking on a data point.

x = 1:10;
y = x.^2;
scatter(x,y)

dcm = datacursormode;
dcm.Enable = 'on';
dcm.UpdateFcn = @displayCoordinates;

Tips

• In general, data tips show the coordinates of the selected data point. However, for some types of charts, data tips display specialized information. For example, histograms created using the histogram function display data tips that itemize the observation counts and bin edges.

• To programmatically create and customize data tips, use the datatip and dataTipTextRow functions. For more information, see Create Custom Data Tips.