matlab myupdatefcn,启用、禁用和管理交互式数据游标模式

datacursormode

启用、禁用和管理交互式数据游标模式

语法

datacursormode on

datacursormode off

datacursormode

datacursormode toggle

datacursormode(figure_handle)

dcm_obj = datacursormode(figure_handle)

说明

datacursormode on 在当前图窗上启用数据游标模式。

datacursormode off 在当前图窗上禁用数据游标模式。

datacursormode 或 datacursormode toggle 在当前图窗上切换数据游标模式。

datacursormode(figure_handle) 在指定图窗上启用或禁用数据游标模式。

dcm_obj = datacursormode(figure_handle) 返回该图窗的数据游标模式对象。该对象允许您自定义数据游标。有关数据游标模式对象的详细信息，请参阅输出参数。不能在返回模式对象的 datacursormode 调用中更改数据游标模式的状态。

数据游标是一个小黑方块，带有白色边框，在数据游标模式下以交互方式将其放置在图形上。点击某图形对象(例如图上的线条)时，会显示数据提示。数据提示是在坐标区(在数据游标位置显示数据值)内浮动的小文本框或窗口。默认样式是文本框。数据提示一次列出一个数据点的 x、y 和(如果适用)z 值。有关这两种样式的演示，请参阅示例。

输入参数figure_handle图窗窗口的可选句柄

默认:当前图窗

state''、'toggle'、'on' 或 'off'

默认:'toggle'

输出参数dcm_obj使用 datacursormode 返回的对象控制数据游标行为的各方面。您可以使用 set 和 get 命令来设置和查询对象的属性值。可通过为这些对象编码回调函数来自定义数据游标模式显示信息的方式。

名称-值对组参数

以下参数适用于 datacursormode 调用返回的对象，而不适用于该函数本身。DisplayStyledatatip | window

确定数据游标的显示方式。

datatip 在以交互方式选择的数据点处附加到黑色正方形标记的黄色小文本框中显示数据游标信息。

window 显示您在图窗内的浮动窗口中以交互方式选择的数据点的数据游标信息。

默认:datatip

Enableon | off

指定当前是否为该图窗启用数据游标模式。

默认:off

Figure句柄

与数据游标模式对象关联的图窗的句柄。

SnapToDataVertexon | off

指定数据游标移至最近的数据值还是位于实际指针位置。

默认:on

UpdateFcn函数句柄

对格式化显示在数据游标中的文本的函数的引用。您可以提供自己的函数来自定义数据提示显示。您的函数必须至少包括两个参数。第一个参数未使用，可以为变量名称或波浪线 (~)。第二个参数将数据游标事件对象传递到您的更新函数。该事件对象封装数据游标的状态。以下函数定义说明了更新函数：

function output_txt = myfunction(~,event_obj)

% ~ Currently not used (empty)

% event_obj Object containing event data structure

% output_txt Data cursor text

event_obj 是具有以下属性的对象。

Target数据游标引用的对象(您点击的对象，比如序列中的线条或条)的句柄。

Position指定光标的 x、y(和 z，对于三维图形)坐标的数组。

可以在函数中查询这些属性。例如，

pos = get(event_obj,'Position');

返回光标的坐标。访问该数据的另一种方法是获取结构体并查询其 Position 字段：

eventdata = get(event_obj);

pos = eventdata.Position;您也可以直接从以下对象获取位置：

pos = event_obj.Position;

可用在运行时重新定义数据游标 Updatefcn。例如：

set(dcm_obj,'UpdateFcn',@myupdatefcn)将函数 myupdatefcn 应用于当前数据提示。按此方式设置更新函数时，该函数必须在 MATLAB® 路径上。而如果您选择数据游标模式上下文菜单项选择文本更新函数，则可以交互方式选择不在该路径上的函数。

在数据游标模式下不要重新定义图窗窗口回调，例如 ButtonDownFcn、KeyPressFcn 或 CloseRequestFcn。如果您尝试在交互模式下更改任何图窗回调，则您会收到警告并且尝试失败。MATLAB 交互模式为：

brush

datacursormode

pan

rotate3d

zoom

此限制不适用于更改图窗的 WindowButtonMotionFcn 回调或 uicontrol 回调。

查询数据游标模式

使用 getCursorInfo 函数可以查询数据游标模式对象(更新函数语法中的 dcm_obj)以获取有关数据游标的信息。例如，

info_struct = getCursorInfo(dcm_obj);

为图形上的每个数据游标返回一个结构体向量。每个结构体包含以下字段。

Target包含数据点的图形对象的句柄

Position用于指定光标的 x、y(和 z)坐标的数组。

线条和线条序列对象有另一个字段。

DataIndex对应于最近数据点的数据数组的标量索引。每个数组的此值是相同的。

有关数据游标模式对象的更多详细信息，请参阅输出参数。

示例

此示例创建一个绘图并从命令行启用数据游标模式。

surf(peaks)

datacursormode on

% Click mouse on surface to display data cursor

选择曲面上的一个点会打开显示其 x、y 和 z 坐标的数据提示。

使用工具 > 选项 > 在窗口中显示光标将数据提示显示样式更改为窗口而非文本框，或使用上下文菜单显示样式 > 图窗内部窗口查看可在坐标区内部四处移动的浮动窗口中的数据提示。

可将多个文本框数据提示放置在同一图上，数据提示的窗口样式一次仅显示一个值。有关与数据游标交互(包括点选择选项和将数据提示导出到工作区)的详细信息，请参阅以交互方式显示数据值。

此示例在当前图窗上启用数据游标模式并设置数据游标模式选项。以下语句

创建图形

打开数据游标模式

获取数据游标模式对象，指定数据提示对象并获取数据提示占用的线条句柄：

fig = figure;

z = peaks;

plot(z(:,30:35))

dcm_obj = datacursormode(fig);

set(dcm_obj,'DisplayStyle','datatip',...

'SnapToDataVertex','off','Enable','on')

disp('Click line to display a data tip, then press Return.')

% Wait while the user does this.

pause

c_info = getCursorInfo(dcm_obj);

% Make selected line wider

set(c_info.Target,'LineWidth',2)

此示例说明了如何自定义数据游标显示的文本。例如，您可以通过创建简单更新函数将数据提示和数据窗口(x: 和 y:)中显示的文本替换为 Time: 和 Amplitude:。

将下列函数保存在 MATLAB 路径上的当前目录或任何可写目录中，然后运行它们。因为它们是函数，所以不能突出显示它们，然后计算选择以使其生效。

将此代码保存为 doc_datacursormode.m：

function doc_datacursormode

% Plots graph and sets up a custom data tip update function

fig = figure;

a = -16; t = 0:60;

plot(t,sin(a*t))

dcm_obj = datacursormode(fig);

set(dcm_obj,'UpdateFcn',@myupdatefcn)

将以下代码以 MATLAB 名称保存至 myupdatefcn.m 路径：

function txt = myupdatefcn(empt,event_obj)

% Customizes text of data tips

pos = get(event_obj,'Position');

txt = {['Time: ',num2str(pos(1))],...

['Amplitude: ',num2str(pos(2))]};

要设置和使用更新函数，请键入：

doc_datacursormode当使用此更新函数放置数据提示时，它如同下图中所示的一样。

提示

多数类型的图和三维绘图都支持数据游标模式，但有些不支持(比如 pareto)。

极坐标图支持数据提示，但在其上显示笛卡尔坐标而非极坐标。

用 histogram 创建的直方图显示专用数据提示，以逐条列举观察计数和长条边缘。

只能通过点击图上的数据对象放置数据提示。不能以编程方式(通过执行代码以放置数据游标)放置数据提示。

当 DisplayStyle 为 datatip 时，您可以在图上放置多个数据提示。当 DisplayStyle 为 window 时，它仅报告最新的数据提示。

datacursormode off 退出数据游标模式但不删除显示的数据提示。但如果 DisplayStyle 是 window，则数据提示窗口将消失。

备选方法

使用数据游标工具 标记图形和曲面上的 x、y 和 z 值。可通过右键点击并从上下文菜单中选择项目来控制数据提示的显示方式。

在 R2006a 之前推出