DataCursorManager - Enable data cursor mode - MATLAB (original) (raw)
datacursormode
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 thedatacursormode 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
Description
datacursormode [option](#mw%5F2124b08c-519a-4fc9-b8a0-8df8dea7031c) 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 betweenon and off.
datacursormode([fig](#mw%5F586d2d5d-ad49-4f0c-bea7-0e239734ebcb),[option](#mw%5F2124b08c-519a-4fc9-b8a0-8df8dea7031c)) 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, usedatacursormode(fig,'on').
datacursormode([ax](#mw%5F752964fd-656f-4f0c-9518-1807ca0c1030),[option](#mw%5F2124b08c-519a-4fc9-b8a0-8df8dea7031c)) sets the data cursor mode for the specified axes. For example, to enable data cursor mode for the axes ax, usedatacursormode(ax,'on'). (since R2023a)
Before R2025a: Use this syntax with apps created in App Designer or using the uifigure function.
dcm = datacursormode creates aDataCursorManager 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](#mw%5F586d2d5d-ad49-4f0c-bea7-0e239734ebcb)) creates aDataCursorManager object for the specified figure.
Input Arguments
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 callingdatacursormodewithout any arguments.
Target figure, specified as a Figure object. Specifying a target figure sets the mode for all current or future Axes children.
Target axes, specified as an Axes object.
Properties
Note
With the exception of UpdateFcn, if you modify any of these properties of a DataCursorManager object, then MATLAB® enables legacy exploration modes on the figure. For more information, seeenableLegacyExplorationModes.
Data cursor mode state, specified as 'on' or'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type OnOffSwitchState.
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.
Note
You can achieve the same functionality without entering legacy exploration modes by setting the DatatipsPlacementMethod property of theInteractionOptions object of the axes.
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 theShift 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.
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, orlightBlue. | '\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.
MATLAB supports most standard LaTeX math mode commands. For more information, see Supported LaTeX Commands. For examples that use TeX and LaTeX, see Greek Letters and Special Characters in Chart Text.
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. Theinfoargument has two fields,TargetandPosition. TheTargetfield contains an object with aDataTipTemplateproperty. ThePositionfield 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 from the data tip context menu.
For more information about callbacks, see Create Callbacks for Graphics Objects.
This property is read-only.
Figure object in which data tips appear.
Object Functions
Note
If you call this object function for a DataCursorManager object, then MATLAB enables legacy exploration modes on the figure. For more information, seeenableLegacyExplorationModes.
| 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 objectdcm returns a vector info with these fields: Target — An object with aDataTipTemplate property, such as Line,Histogram, Surface, orFunctionLine.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 — 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. NoteFor some target objects, the info structure does not include a DataIndex field. |
|---|
Examples
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';
Define a callback function that accepts data tip information and returns customized text. Return the customized text as a string, in this case containing an ordered pair of coordinates. Save the function as a program file nameddisplayCoordinates.m.
function txt = displayCoordinates(~,info) x = info.Position(1); y = info.Position(2); myDatatipText = "(%s, %s)"; txt = sprintf(myDatatipText, 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.
Version History
Introduced before R2006a
Set the data cursor mode for axes by specifying the axes as the first input ofdatacursormode. When setting the data cursor mode for axes, the function does not return a DataCursorManager object. Previously, you could set the data cursor mode for axes only in apps created in App Designer or using theuifigure function.
For apps created in App Designer or using the uifigure function, set the data cursor mode for axes by specifying the axes as the first input ofdatacursormode. When setting the data cursor mode for axes, the function does not return a DataCursorManager object.
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.