datacursormode

Enable data cursor mode

Description

You can use data cursor mode to explore data by interactively creating and editing data tips. Data tips are small text boxes that display information about individual data points. Enable or disable data cursor mode, and set other basic options, by using the datacursormode function. To control data tip appearance and behavior, return and use a DataCursorManager object.

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.

You can also interactively explore data using built-in axes interactions that are enabled by default. For example, you can temporarily display a data tip by pausing on a data point, or you can pin a data tip by clicking on a data point. Built-in interactions do not require you to enable an interaction mode and respond faster than interaction modes. However, you can enable data cursor mode to customize data tip behavior. For more information about built-in interactions, see Control Chart Interactivity.

Creation

Syntax

datacursormode option

datacursormode

datacursormode(fig,option)

datacursormode(ax,option)

dcm = datacursormode

dcm = datacursormode(fig)

Description

datacursormode option sets the data cursor mode for all axes in the current figure. For example, datacursormode on enables data cursor mode and datacursormode off disables data cursor mode.

When data cursor mode is enabled, create a data tip using either the cursor or the keyboard.

• Cursor — Click a plotted data point. To create multiple data tips, hold the Shift key as you select data points. To move a data tip to another data point, drag the point where the data tip is located.

• Keyboard — For some charts, to move the currently selected data tip to another data point, press the up arrow (↑), down arrow (↓), left arrow (←), or right arrow (→) key.

Some built-in interactions remain enabled by default, regardless of the current interaction mode. To disable built-in data tip interactions that are independent of the data cursor mode, use the disableDefaultInteractivity function.

datacursormode toggles data cursor mode between on and off.

datacursormode(fig,option) sets the data cursor mode for all axes in the specified figure. For example, to enable data cursor mode for all axes in the figure fig, use datacursormode(fig,'on').

datacursormode(ax,option) sets the data cursor mode for the specified axes. For example, to enable data cursor mode for the axes ax, use datacursormode(ax,'on'). Use this syntax with apps created in App Designer and using the uifigure function. (since R2023a)

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

dcm = datacursormode(fig) creates a DataCursorManager object for the specified figure.

Input Arguments

option — Data cursor mode option

'on' | 'off' | 'toggle'

Data cursor mode option, specified as one of these values:

• 'on' — Enable data cursor mode.

• 'off' — Disable data cursor mode. Some built-in interactions remain enabled by default, regardless of the current interaction mode. To disable built-in data tip interactions that are independent of the data cursor mode, use the disableDefaultInteractivity function.

• 'toggle' — Toggle the data cursor mode. For example, if data cursor mode is disabled, then 'toggle' enables data cursor mode. Using this option is the same as calling datacursormode without any arguments.

fig — Target figure

Figure object

Target figure, specified as a Figure object. Specifying a target figure sets the mode for all current or future Axes children.

ax — Target axes

Axes object

Target axes, specified as an Axes object.

Properties

Enable — Data cursor mode

'off' (default) | 'on'

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

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. To create multiple data tips, hold the Shift key as you select data points. If you disable data cursor mode, existing data tips remain on the chart.

• 'window' — Display data tips in a movable window within the figure. When the display style is 'window', you can display only one data tip at a time. If you disable 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/.

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 Create Callbacks for Graphics Objects.

Figure — Figure object

Figure object

This property is read-only.

Figure object in which data tips appear.

Object Functions

getCursorInfo

The getCursorInfo function returns the target and coordinates of each data tip in the figure. Calling info = getCursorInfo(dcm) on the data cursor manager object dcm returns a vector info 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 Movable Window

Plot some data and create a DataCursorManager object.

x = linspace(0,5,30);
y = exp(x);
scatter(x,y)
dcm = datacursormode;

Enable data cursor mode, and display data tip content in a movable 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 dragging the window heading.

dcm.Enable = 'on';
dcm.DisplayStyle = 'window';

Customize Data Tip Text

Define a callback function that accepts data tip information and returns customized text. Return the customized text as a character array, in this case containing an ordered pair of coordinates. Save the function as a program file named 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.

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

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

Then, create a data tip by clicking on a data point.

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.

Alternative Functionality

Axes Toolbar

For some charts, enable data cursor mode by clicking the data tips icon in the axes toolbar.

Programmatic Workflow

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

Version History

Introduced before R2006a

R2023a: Set data cursor mode for specified axes in apps

For apps created in App Designer and using the uifigure function, set the data cursor mode for axes by specifying the axes as the first input of datacursormode. When setting the data cursor mode for axes, the function does not return a DataCursorManager object.

R2018b: Explore data with data tips enabled by default

Interactively explore your data using built-in axes interactions that are enabled by default. For example, you can pause on a data point to see a data tip without enabling data cursor mode. For more information, see Control Chart Interactivity.

Previously, no axes interactions were enabled by default.