datatip

Create data tip

Description

Data tips are small text boxes that display information about individual data points. By default, data tips show the coordinates of a data point.

Creation

Interactively create data tips by clicking on data points in a chart, for example line and scatter plots. You can also create data tips using the datatip function.

Description

datatip(target) creates a data tip on the first plotted data point of the specified chart, such as a line or scatter plot.

example

datatip(target,x,y) creates a data tip on the 2-D plotted data point specified by x and y. If you specify approximate coordinates, then datatip creates a data tip at the nearest data point.

datatip(target,x,y,z) creates a data tip on the 3-D plotted data point specified by x, y, and z. If you specify approximate coordinates, then datatip creates a data tip at the nearest data point.

example

datatip(target,'DataIndex',n) creates a data tip on the nth plotted data point by setting the DataIndex property.

datatip(___,Name,Value) specifies properties using one or more name-value pair arguments. Specify name-value pairs after all other arguments.

dt = datatip(___) returns a DataTip object. You can specify any of the input argument combinations in the previous syntaxes. This syntax is useful for controlling the properties of the data tip.

Input Arguments

expand all

Target, specified as an object with a DataTipTemplate property. Examples of objects with a DataTipTemplate property include Line, Histogram, Surface, and FunctionLine objects.

First coordinate of the data tip, specified as a scalar. The interpretation of the first coordinate depends on the type of axes:

  • For Cartesian axes, the first coordinate is the x-axis position using the same units as your data.

  • For polar axes, the first coordinate is the polar angle θ in radians.

  • For geographic axes, the first coordinate is the latitude in degrees.

By default, if you specify the approximate coordinates of a data point, then the datatip function creates a data tip at the nearest data point. The nearest data point depends on the type of chart. For example, on a line chart the nearest point has the smallest Euclidean distance from the approximate coordinates.

To create data tips between data points, set the SnapToDataVertex property to 'off'.

Second coordinate of the data tip, specified as a scalar. The interpretation of the second coordinate depends on the type of axes:

  • For Cartesian axes, the second coordinate is the y-axis position using the same units as your data.

  • For polar axes, the second coordinate is the radius r in the same units as your data.

  • For geographic axes, the second coordinate is the longitude in degrees.

By default, if you specify the approximate coordinates of a data point, then the datatip function creates a data tip at the nearest data point. The nearest data point depends on the type of chart. For example, on a line chart the nearest point has the smallest Euclidean distance from the approximate coordinates.

To create data tips between data points, set the SnapToDataVertex property to 'off'.

Third coordinate of the data tip, specified as a scalar. For Cartesian axes, the third coordinate is the z-axis position using the same units as your data.

By default, if you specify the approximate coordinates of a data point, then the datatip function creates a data tip at the nearest data point. The nearest data point depends on the type of chart. For example, on a line chart the nearest point has the smallest Euclidean distance from the approximate coordinates.

To create data tips between data points, set the SnapToDataVertex property to 'off'.

Properties

expand all

Data Tip

Index of the plotted data, specified as a positive integer.

For example, the plotted data of a 2-D object on a set of Cartesian axes is contained in its XData and YData properties. When you specify the DataIndex of a data tip, MATLAB® positions the data tip on the chart by indexing into XData and YData.

When you create a data tip using this property, do not specify the x, y, or z arguments.

Example: datatip(chart,'DataIndex',3) creates a data tip at the third plotted data point.

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

  • 'on' – Display the data tip at the closest data point.

  • 'off' – Display the data tip at the nearest specified location on the chart, even if it is between data points.

Offset from DataIndex, specified as a scalar. Use this property to create data tips between adjacent data points on a Line object by setting SnapToDataVertex to 'off' and InterpolationFactor to a scalar between 0 and 1.

For example, create a data tip halfway between adjacent data points on a line by specifying the InterpolationFactor as 0.5.

x = 1:4;
y = 2.*x;
p = plot(x,y,'-*');
dt = datatip(p,'DataIndex',2, ...
               'Location','southeast', ...
               'SnapToDataVertex','off', ...
               'InterpolationFactor',0.5);

InterpolationFactor is not supported for data tips on all types of objects.

Location with respect to the data point, specified as one of these values:

ValueDescriptionAppearance
'northeast'Top-right corner of data point
'northwest'Top-left corner of data point
'southeast'Bottom-right corner of data point
'southwest'Bottom-left corner of data point

Example: dt.Location = 'southwest';

Selection mode for the Location property value, specified as one of these values:

  • 'auto' – The datatip function automatically selects the location.

  • 'manual' – If you set the Location property, the LocationMode property automatically changes to 'manual'.

This property is read-only.

Data tip content, specified as a cell array. By default, data tip content is a 2-by-1 cell array for 2-D data tips or a 3-by-1 cell array for 3-D data tips.

To add additional rows to the data tip content, use dataTipTextRow.

Font

Font name, specified as a supported font name or 'FixedWidth'. To display and print text properly, you must choose a font that your system supports. The default font depends on your operating system and locale.

To use a fixed-width font that looks good in any locale, use 'FixedWidth'. The fixed-width font relies on the root FixedWidthFontName property. Setting the root FixedWidthFontName property causes an immediate update of the display to use the new font.

Selection mode for the FontName property, specified as one of these values:

  • 'auto' – Use the same value as the FontName property for the DataTipTemplate object associated with the chart that contains the data tip.

  • 'manual' – If you set the FontName property, the FontNameMode property automatically changes to 'manual'.

Font size, specified as a scalar value greater than zero in point units. One point equals 1/72 inch.

Selection mode for the font size, specified as one of these values:

  • 'auto' – Use the same value as the FontSize property for the DataTipTemplate object associated with the chart that contains the data tip.

  • 'manual' – If you set the FontSize property, the FontSizeMode property automatically changes to 'manual'.

Character slant, specified as 'normal' or 'italic'.

Not all fonts have both font styles. Therefore, the italic font might look the same as the normal font.

Selection mode for the FontAngle property, specified as one of these values:

  • 'auto' – Use the same value as the FontAngle property for the DataTipTemplate object associated with the chart that contains the data tip.

  • 'manual' – If you set the FontAngle property, the FontAngleMode property automatically changes to 'manual'.

Interpretation of text characters, 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 property to 'tex', the supported modifiers are as follows.

ModifierDescriptionExample
^{ }Superscript'text^{superscript}'
_{ }Subscript'text_{subscript}'
\bfBold font'\bf text'
\itItalic font'\it text'
\slOblique font (usually the same as italic font)'\sl text'
\rmNormal 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 with the Interpreter property set to 'tex'.

Character SequenceSymbolCharacter SequenceSymbolCharacter SequenceSymbol

\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 property 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. The FontName, FontWeight, and FontAngle properties do not have an effect. 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/.

Selection mode for the Interpreter property, specified as one of these values:

  • 'auto' — Use the same value as the Interpreter property for the DataTipTemplate object associated with the chart that contains the data tip.

  • 'manual' — If you set the Interpreter property, the InterpreterMode property automatically changes to 'manual'.

Cartesian Coordinate Data

Position along the x-axis, specified as a scalar using the same units as your data.

Position along the y-axis, specified as a scalar using the same units as your data.

Position along the z-axis, specified as a scalar using the same units as your data.

Polar Coordinate Data

Radius, specified as a scalar using the same units as your data.

This property applies only to data tips on polar plots.

Angle, specified as a scalar in degrees.

This property applies only to data tips on polar plots.

Geographic Coordinate Data

Latitude, specified as a scalar in degrees.

This property applies only to data tips on geographic plots.

Longitude, specified as a scalar in degrees.

This property applies only to data tips on geographic plots.

Interactivity

State of visibility, specified as one of these values:

  • 'on' — Display the object.

  • 'off' — Hide the object without deleting it. You still can access the properties of an invisible object.

Context menu, specified as a ContextMenu object that provides data tip options. You cannot set this property.

Selection state, specified as one of these values:

  • 'on' — Selected. If you click the object when in plot edit mode, then MATLAB sets its Selected property to 'on'. If the SelectionHighlight property also is set to 'on', then MATLAB displays selection handles around the object.

  • 'off' — Not selected.

Display of selection handles when selected, specified as one of these values:

  • 'on' — Display selection handles when the Selected property is set to 'on'.

  • 'off' — Never display selection handles, even when the Selected property is set to 'on'.

Callbacks

Mouse-click callback, specified as one of these values:

  • Function handle

  • Cell array containing a function handle and additional arguments

  • Character vector that is a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)

Use this property to execute code when you click the object. If you specify this property using a function handle, then MATLAB passes two arguments to the callback function when executing the callback:

  • Clicked object — Access properties of the clicked object from within the callback function.

  • Event data — Empty argument. Replace it with the tilde character (~) in the function definition to indicate that this argument is not used.

For more information on how to use function handles to define callback functions, see Callback Definition.

Note

If the PickableParts property is set to 'none' or if the HitTest property is set to 'off', then this callback does not execute.

Object creation function, specified as one of these values:

  • Function handle.

  • Cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • Character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback as a function handle, cell array, or character vector, see Callback Definition.

This property specifies a callback function to execute when MATLAB creates the object. MATLAB initializes all property values before executing the CreateFcn callback. If you do not specify the CreateFcn property, then MATLAB executes a default creation function.

Setting the CreateFcn property on an existing component has no effect.

If you specify this property as a function handle or cell array, you can access the object that is being created using the first argument of the callback function. Otherwise, use the gcbo function to access the object.

Object deletion function, specified as one of these values:

  • Function handle.

  • Cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • Character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback as a function handle, cell array, or character vector, see Callback Definition.

This property specifies a callback function to execute when MATLAB deletes the object. MATLAB executes the DeleteFcn callback before destroying the properties of the object. If you do not specify the DeleteFcn property, then MATLAB executes a default deletion function.

If you specify this property as a function handle or cell array, you can access the object that is being deleted using the first argument of the callback function. Otherwise, use the gcbo function to access the object.

Callback Execution Control

Callback interruption, specified as 'on' or 'off'. The Interruptible property determines if a running callback can be interrupted.

There are two callback states to consider:

  • The running callback is the currently executing callback.

  • The interrupting callback is a callback that tries to interrupt the running callback.

Whenever MATLAB invokes a callback, that callback attempts to interrupt the running callback (if one exists). The Interruptible property of the object owning the running callback determines if interruption is allowed. The Interruptible property has two possible values:

  • 'on' — Allows other callbacks to interrupt the object's callbacks. The interruption occurs at the next point where MATLAB processes the queue, such as when there is a drawnow, figure, uifigure, getframe, waitfor, or pause command.

    • If the running callback contains one of those commands, then MATLAB stops the execution of the callback at that point and executes the interrupting callback. MATLAB resumes executing the running callback when the interrupting callback completes.

    • If the running callback does not contain one of those commands, then MATLAB finishes executing the callback without interruption.

  • 'off' — Blocks all interruption attempts. The BusyAction property of the object owning the interrupting callback determines if the interrupting callback is discarded or put into a queue.

Note

Callback interruption and execution behave differently in these situations:

  • If the interrupting callback is a DeleteFcn, CloseRequestFcn or SizeChangedFcn callback, then the interruption occurs regardless of the Interruptible property value.

  • If the running callback is currently executing the waitfor function, then the interruption occurs regardless of the Interruptible property value.

  • Timer objects execute according to schedule regardless of the Interruptible property value.

When an interruption occurs, MATLAB does not save the state of properties or the display. For example, the object returned by the gca or gcf command might change when another callback executes.

Callback queuing, specified as 'queue' or 'cancel'. The BusyAction property determines how MATLAB handles the execution of interrupting callbacks. There are two callback states to consider:

  • The running callback is the currently executing callback.

  • The interrupting callback is a callback that tries to interrupt the running callback.

Whenever MATLAB invokes a callback, that callback attempts to interrupt a running callback. The Interruptible property of the object owning the running callback determines if interruption is permitted. If interruption is not permitted, then the BusyAction property of the object owning the interrupting callback determines if it is discarded or put in the queue. These are possible values of the BusyAction property:

  • 'queue' — Puts the interrupting callback in a queue to be processed after the running callback finishes execution.

  • 'cancel' — Does not execute the interrupting callback.

Ability to capture mouse clicks, specified as one of these values:

  • 'visible' — Capture mouse clicks when visible. The Visible property must be set to 'on' and you must click a part of the DataTip object that has a defined color. You cannot click a part that has an associated color property set to 'none'. The HitTest property determines if the DataTip object responds to the click or if an ancestor does.

  • 'all' — Capture mouse clicks regardless of visibility. The Visible property can be set to 'on' or 'off' and you can click a part of the DataTip object that has no color. The HitTest property determines if the DataTip object responds to the click or if an ancestor does.

  • 'none' — Cannot capture mouse clicks. Clicking the DataTip object passes the click through it to the object below it in the current view of the figure window. The HitTest property has no effect.

Response to captured mouse clicks, specified as one of these values:

  • 'on' — Trigger the ButtonDownFcn callback of the DataTip object. If you have defined the UIContextMenu property, then invoke the context menu.

  • 'off' — Trigger the callbacks for the nearest ancestor of the DataTip object that has one of these:

    • HitTest property set to 'on'

    • PickableParts property set to a value that enables the ancestor to capture mouse clicks

Note

The PickableParts property determines if the DataTip object can capture mouse clicks. If it cannot, then the HitTest property has no effect.

This property is read-only.

Deletion status, returned as 'off' or 'on'. MATLAB sets the BeingDeleted property to 'on' when the DeleteFcn callback begins execution. The BeingDeleted property remains set to 'on' until the component object no longer exists.

Check the value of the BeingDeleted property to verify that the object is not about to be deleted before querying or modifying it.

Parent/Child

Parent, specified as a object with a DataTipTemplate property. Examples of objects with a data tip template include Line, Histogram, Surface, and FunctionLine objects. Move a data tip to another object by setting this property.

The object has no children. You cannot set this property.

Visibility of the object handle in the Children property of the parent, specified as one of these values:

  • 'on' — Object handle is always visible.

  • 'off' — Object handle is invisible at all times. This option is useful for preventing unintended changes by another function. Set the HandleVisibility to 'off' to temporarily hide the handle during the execution of that function.

  • 'callback' — Object handle is visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. This option blocks access to the object at the command line, but permits callback functions to access it.

If the object is not listed in the Children property of the parent, then functions that obtain object handles by searching the object hierarchy or querying handle properties cannot return it. Examples of such functions include the get, findobj, gca, gcf, gco, newplot, cla, clf, and close functions.

Hidden object handles are still valid. Set the root ShowHiddenHandles property to 'on' to list all object handles regardless of their HandleVisibility property setting.

Identifiers

This property is read-only.

Type of graphics object, returned as 'datatip'. Use this property to find all objects of a given type within a plotting hierarchy, for example, when searching for the type using findobj.

Object identifier, specified as a character vector or string scalar. You can specify a unique Tag value to serve as an identifier for an object. When you need access to the object elsewhere in your code, you can use the findobj function to search for the object based on the Tag value.

User data, specified as any MATLAB array. For example, you can specify a scalar, vector, matrix, cell array, character array, table, or structure. Use this property to store arbitrary data on an object.

If you are working in App Designer, create public or private properties in the app to share data instead of using the UserData property. For more information, see Share Data Within App Designer Apps.

Examples

collapse all

Plot data on a scatter chart and return the Scatter object. Then, create a data tip at a particular data point by specifying the x- and y-coordinates.

x = linspace(0,10,11);
y = x.^2;
sc = scatter(x,y);

dt = datatip(sc,7,49);

Plot data on a bar chart and return the Bar object. Then, create a data tip on the seventh bar by specifying the DataIndex name-value pair argument.

x = 1900:10:2000;
y = [75 91 105 123.5 131 120 107 96 82 73 70];
b = bar(x,y);

dt = datatip(b,'DataIndex',7);

Plot data on a scatter chart and return the Scatter object. Create a data tip at the data point near (3,0) by specifying x = 3 and y = 0 as approximate coordinates. When you create a data tip using approximate coordinates, the data tip appears at the closest data point.

x = linspace(0,2*pi,20);
y = sin(x);
sc = scatter(x,y);
grid on;

dt = datatip(sc,3,0);

Plot data and return the Line object. Show a marker at each plotted data point. Then, create a data tip between two data points by specifying the x- and y-coordinates for the data tip and specifying the SnapToDataVertex name-value pair argument as 'off'.

x = linspace(1,10,10);
y = 2.*x;
p = plot(x,y,'-*');

dt = datatip(p,3.5,7,'SnapToDataVertex','off');

Tips

  • Interactively create data tips by clicking on data points in a chart. To assign interactively created data tips to a variable, use the findobj function.

    dt = findobj(chart,'Type','datatip');

  • To delete data tips, use the delete function.

    delete(dt);

Introduced in R2019b