Main Content

datacursormode

启用数据游标模式

说明

您可以使用数据游标模式,通过以交互方式创建和编辑数据提示来浏览数据。数据提示是显示关于单个数据点的信息的小文本框。使用 datacursormode 函数启用或禁用数据游标模式,并设置其他基本选项。要控制数据提示的外观和行为,请返回并使用 DataCursorManager 对象。

大多数图支持数据提示,包括线图、条形图、直方图和曲面图。支持数据提示的图通常会在坐标区工具栏中显示数据提示 图标。

您还可以使用默认情况下启用的内置坐标区交互来以交互方式浏览数据。例如,您可以通过在数据点上暂停来临时显示数据提示,也可以通过点击数据点来固定数据提示。内置交互不要求您启用交互模式,并且比交互模式响应更快。但是,您可以启用数据游标模式来自定义数据提示行为。有关内置交互的详细信息,请参阅对图的交互进行控制

创建对象

描述

datacursormode option 设置当前图窗中所有坐标区的数据游标模式。例如,datacursormode on 会启用数据游标模式,而 datacursormode off 则会禁用数据游标模式。

启用数据游标模式时,可以使用光标或键盘创建数据提示。

  • 游标 - 点击绘制的数据点。要创建多个数据提示,请在选择数据点时按住 Shift 键。要将数据提示移至另一个数据点,请拖动数据提示所在的点。

  • 键盘 - 对于某些图,要将当前所选数据提示移至另一个数据点,请按向上箭头 (↑) 键、向下箭头 (↓) 键、向左箭头 (←) 键或 向右箭头 (→) 键。

不管当前交换模式如何,某些内置交互都默认处于启用状态。要禁用独立于数据游标模式的内置数据提示交互,请使用 disableDefaultInteractivity 函数。

datacursormodeonoff 之间切换数据游标模式。

datacursormode(fig,option) 设置指定的图窗中所有坐标区的数据游标模式。例如,要为图窗 fig 中的所有坐标区启用数据游标模式,请使用 datacursormode(fig,'on')

datacursormode(ax,option) 为指定的坐标区设置数据游标模式。例如,要为坐标区 ax 启用数据游标模式,请使用 datacursormode(ax,'on')。将此语法用于在 App 设计工具中创建的 App 和使用 uifigure 函数创建的 App。 (自 R2023a 起)

示例

dcm = datacursormode 为当前图窗创建一个 DataCursorManager 对象。此语法可用于自定义数据游标模式、数据提示显示样式和数据提示文本格式。

dcm = datacursormode(fig) 为指定的图窗创建 DataCursorManager 对象。

输入参数

全部展开

数据游标模式选项,指定为下列值之一:

  • 'on' - 启用数据游标模式。

  • 'off' - 禁用数据游标模式。不管当前交换模式如何,某些内置交互都默认处于启用状态。要禁用独立于数据游标模式的内置数据提示交互,请使用 disableDefaultInteractivity 函数。

  • 'toggle' - 切换数据游标模式。例如,如果数据游标模式处于禁用状态,则 'toggle' 会启用数据游标模式。使用此选项等效于不带任何参数调用 datacursormode

目标图窗,指定为 Figure 对象。指定目标图窗将为所有当前或将来的 Axes 子级设置模式。

目标坐标区,指定为 Axes 对象。

属性

全部展开

数据游标模式,指定为 'off''on'

在最近的数据点上显示,指定为下列值之一:

  • 'on' - 在最近的数据点显示数据提示。最近的数据点取决于图的类型。例如,在线图上,最近的点与指定位置的欧几里德距离最小。

  • 'off' - 在您点击的位置显示数据提示,即使该位置位于数据点之间。

数据提示显示样式,指定为下列值之一:

  • 'datatip' - 将数据提示显示为附加到数据值的小文本框。要创建多个数据提示,请在选择数据点时按住 Shift 键。如果禁用数据游标模式,现有数据提示将保留在图上。

  • 'window' - 在图窗中的可移动窗口中显示数据提示。当显示样式为 'window' 时,一次只能显示一个数据提示。如果禁用数据游标模式,窗口将关闭。

文本解释器,指定为下列值之一:

  • 'tex' - 使用 TeX 标记子集解释字符。

  • 'latex' - 使用 LaTeX 标记解释字符。

  • 'none' - 显示字面字符。

TeX 标记

默认情况下,MATLAB® 支持一部分 TeX 标记。使用 TeX 标记可添加下标和上标,修改字体类型和颜色,并在文本中包括特殊字符。

修饰符会一直作用到文本结尾,但上标和下标除外,因为它们仅修饰下一个字符或花括号中的字符。当您将解释器设置为 'tex' 时,支持的修饰符如下所示。

修饰符描述示例
^{ }上标'text^{superscript}'
_{ }下标'text_{subscript}'
\bf粗体'\bf text'
\it斜体'\it text'
\sl伪斜体(通常与斜体相同)'\sl text'
\rm常规字体'\rm text'
\fontname{specifier}字体名称 - 将 specifier 替换为字体系列的名称。您可以将此说明符与其他修饰符结合使用。'\fontname{Courier} text'
\fontsize{specifier}字体大小 - 将 specifier 替换为以磅为单位的数值标量值。'\fontsize{15} text'
\color{specifier}字体颜色 - 将 specifier 替换为以下颜色之一:redgreenyellowmagentablueblackwhitegraydarkGreenorangelightBlue'\color{magenta} text'
\color[rgb]{specifier}自定义字体颜色 - 将 specifier 替换为三元素 RGB 三元组。'\color[rgb]{0,0.5,0.5} text'

下表列出了 'tex' 解释器所支持的特殊字符。

字符序列符号字符序列符号字符序列符号

\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 标记

要使用 LaTeX 标记,请将解释器设置为 'latex'。使用美元符号将文本括起来,例如,对于内联模式,使用 '$\int_1^{20} x^2 dx$';对于显示模式,使用 '$$\int_1^{20} x^2 dx$$'

显示的文本将使用默认的 LaTeX 字体样式。要更改字体样式,请使用 LaTeX 标记。

用于 LaTeX 解释器的文本最多可以包含 1200 个字符。对于多行文本,请在此数量的基础上每行减少约 10 个字符。

有关 LaTeX 系统的详细信息,请访问 LaTeX Project 网站:https://www.latex-project.org/

用于格式化数据提示文本的回调函数,指定为函数句柄。

使用此属性格式化数据提示的内容。MATLAB 向回调函数传递两个参数:

  • empty - 空参数。在函数中将其替换为波浪号字符 (~) 以指示不使用此参数。

  • info - 包含有关数据提示的信息的结构体。info 参数有两个字段,即 TargetPositionTarget 字段包含一个具有 DataTipTemplate 属性的对象。Position 字段包含数据提示的坐标。

该函数必须在 MATLAB 路径上或位于当前文件夹中。您也可以通过从数据提示上下文菜单中选择更新函数 > 从文件中选择,来选择不在 MATLAB 路径中的函数。

有关回调的详细信息,请参阅Create Callbacks for Graphics Objects

此 属性 为只读。

在其中显示数据提示的 Figure 对象。

对象函数

getCursorInfo

getCursorInfo 函数返回图窗中每个数据提示的目标和坐标。

对数据游标管理器对象 dcm 调用 info = getCursorInfo(dcm) 会返回包含以下字段的向量 info

  • Target - 具有 DataTipTemplate 属性的对象,如 LineHistogramSurfaceFunctionLine

  • Position - 数据提示的坐标。坐标的解释取决于坐标区的类型。例如,笛卡尔坐标区的坐标是 xyz,单位与数据相同。

  • DataIndex(仅适用于 Line 对象)- 绘图数据的索引。例如,二维对象在笛卡尔坐标区上的绘图数据包含在其 XDataYData 属性中。

示例

全部折叠

绘制一些数据并创建一个 DataCursorManager 对象。

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

启用数据游标模式,并通过将 DisplayStyle 属性设置为 'window' 在可移动窗口中显示数据提示内容。然后,通过点击数据点来创建数据提示。您可以通过拖动窗口标题来移动数据提示窗口。

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

Scatter plot with one selected point. A window in the lower-right corner displays the coordinates of the selected point.

定义接受数据提示信息并返回自定义文本的回调函数。以字符数组形式返回自定义文本,在本例中包含坐标的有序对组。将该函数另存为名为 displayCoordinates.m 的程序文件。

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

绘制一些数据,启用数据游标模式,并将 UpdateFcn 属性设置为回调函数。

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

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

然后,通过点击数据点来创建数据提示。

Scatter plot with one data tip. The text in the data tip is an ordered pair.

提示

  • 通常,数据提示显示所选数据点的坐标。但是,对于某些类型的图,数据提示会显示专用信息。例如,使用 histogram 函数创建的直方图显示的数据提示会逐条列出观察计数和 bin 边界。

替代功能

坐标区工具栏

对于某些图,通过点击坐标区工具栏中的数据提示 图标来启用数据游标模式。

编程工作流

要以编程方式创建和自定义数据提示,请使用 datatipdataTipTextRow 函数。有关详细信息,请参阅创建自定义数据提示

版本历史记录

在 R2006a 之前推出

全部展开