15.4.6 对象组¶

许多 Octave 高级绘图函数会返回其他图形对象的组，或者返回属性之间具有链接关系的图形对象，使得一个属性的更改会导致其他属性的更改。用于将其他对象分组的图形对象称为 hggroup。

hggroup () ¶

hggroup (hax) ¶

hggroup (…, property, value, …) ¶

h = hggroup (…) ¶

创建句柄图形组对象，其父轴为 hax。

如果未指定父对象，则会在当前轴中创建该组。

可以为 hggroup 指定多个属性/值对，但必须成对出现。完整的属性列表请参见 轴属性。

可选的返回值 h 是所创建的 hggroup 对象的图形句柄。

编程说明：hggroup 是一种将基本图形对象（如线条对象或补丁对象）组合为一个单元的方法，该单元可以恰当地响应操作。例如，等高线图的各条独立线条被收集到单个 hggroup 中，从而可以通过一条命令控制它们的可见性：set (hg_handle, "visible", "off")。

另请参阅： addproperty，addlistener。

例如，hggroup 的一个简单用法如下：

x = 0:0.1:10;
hg = hggroup ();
plot (x, sin (x), "color", [1, 0, 0], "parent", hg);
hold on
plot (x, cos (x), "color", [0, 1, 0], "parent", hg);
set (hg, "visible", "off");

该例将两个图形组合成一个对象并直接控制它们的可见性。hggroup 的默认属性与其他图形对象的公共属性集相同。可以使用 addproperty 函数添加其他属性。

addproperty (name, h, type) ¶

addproperty (name, h, type, arg, …) ¶

在图形对象 h 中创建一个名为 name 的新属性。

type 决定要创建的属性的类型。args 通常包含属性的默认值，但根据属性类型的不同，也可能会提供额外的参数。

支持的属性类型包括：

string

字符串属性。arg 包含默认字符串值。

any

无类型属性。此类属性可以保存任何 Octave 值。args 包含默认值。

radio

具有一组有限可接受值的字符串属性。第一个参数必须是一个字符串，其中所有可接受的值用竖线（"|"）分隔。默认值可以通过用 "{" "}" 括起来进行标记。默认值也可以作为可选的第二个字符串参数给出。

boolean

布尔属性。此属性类型等价于一个将 "on|off" 作为可接受值的 radio 属性。arg 包含默认属性值。

double

标量 double 属性。arg 包含默认值。

handle

句柄属性。此类属性保存图形对象的句柄。arg 包含默认句柄值。当未给出默认值时，该属性被初始化为空矩阵。

data

数据（矩阵）属性。arg 包含默认数据值。当未给出默认值时，数据被初始化为空矩阵。

color

颜色属性。arg 包含默认颜色值。当未给出默认颜色时，该属性设置为黑色。可以给出一个可选的第二个字符串参数，用于指定额外的一组可接受字符串值（类似于 radio 属性）。

type 也可以是核心对象类型与该对象类型的有效属性名称的连接。这样创建的属性将具有与被引用属性相同的特征（类型、可能的值、隐藏状态等）。这允许将现有属性克隆到图形对象 h 中。

示例：

addproperty ("my_property", gcf, "string", "a string value");
addproperty ("my_radio", gcf, "radio", "val_1|val_2|{val_3}");
addproperty ("my_style", gcf, "linelinestyle", "--");

另请参阅： addlistener，hggroup。

一旦向 hggroup 添加了一个属性，它并不与组的子对象或任何其他图形对象的任何属性相链接。因此，为了控制这个新加属性的使用方式，可以使用 addlistener 函数来定义一个回调函数，当该属性被更改时执行。

addlistener (h, prop, fcn) ¶

将 fcn 注册为图形对象 h 的属性 prop 的监听器。当属性 prop 被修改时，将调用函数 fcn。

fcn 可以是函数句柄、字符串或首个元素为函数句柄的元胞数组。如果 fcn 是函数句柄，则相应的函数应至少接受 2 个参数，这两个参数将分别设置为对象句柄和空矩阵。如果 fcn 是字符串，则必须是任何有效的 Octave 表达式。如果 fcn 是元胞数组，则第一个元素必须是函数句柄，其签名如上所述。元胞数组的后续元素将作为额外参数传递给该函数。

示例：

function my_listener (h, dummy, p1)
  fprintf ("my_listener called with p1=%s\n", p1);
endfunction

addlistener (gcf, "position", {@my_listener, "my string"})

另请参阅： dellistener，addproperty，hggroup。

dellistener (h, prop, fcn) ¶

移除 fcn 作为图形对象 h 的属性 prop 的监听器注册。

函数 fcn 必须与最初调用 addlistener 时传入的变量是同一个变量（而不仅仅是相同的值）。

如果未指定 fcn，则移除 prop 的所有监听器函数。

示例：

function my_listener (h, dummy, p1)
  fprintf ("my_listener called with p1=%s\n", p1);
endfunction

c = {@my_listener, "my string"};
addlistener (gcf, "position", c);
dellistener (gcf, "position", c);

另请参阅： addlistener。

以下示例展示了这两个函数的用法：

x = 0:0.1:10;
hg = hggroup ();
h = plot (x, sin (x), "color", [1, 0, 0], "parent", hg);
addproperty ("linestyle", hg, "linelinestyle", get (h, "linestyle"));
addlistener (hg, "linestyle", @update_props);
hold on
plot (x, cos (x), "color", [0, 1, 0], "parent", hg);

function update_props (h, d)
  set (get (h, "children"), "linestyle", get (h, "linestyle"));
endfunction

该例向 hggroup 添加了一个 linestyle 属性，并将其值的任何更改传播到组的子对象。linkprop 函数可以简化上述操作为：

x = 0:0.1:10;
hg = hggroup ();
h1 = plot (x, sin (x), "color", [1, 0, 0], "parent", hg);
addproperty ("linestyle", hg, "linelinestyle", get (h, "linestyle"));
hold on
h2 = plot (x, cos (x), "color", [0, 1, 0], "parent", hg);
hlink = linkprop ([hg, h1, h2], "color");

hlink = linkprop (h, "prop") ¶

hlink = linkprop (h, {"prop1", "prop2", …}) ¶

链接图形对象属性，使得一个属性的更改会传播到其他对象。

输入参数 h 是要链接的图形句柄向量。

prop 可以是字符串（用于链接单个属性），也可以是字符串元胞数组（用于链接多个属性）。在链接过程中，prop 中的所有属性将首先设置为列表 h 中第一个对象上已存在的值。

该函数返回 hlink，它是一个描述链接关系的特殊对象。只要引用 hlink 存在，图形对象之间的链接就会保持激活状态。这意味着 hlink 必须保存在工作区变量、全局变量中，或者使用 setappdata 或 guidata 等函数进行存储。要解除属性链接，请执行 clear hlink。

linkprop 的使用示例如下：

x = 0:0.1:10;
subplot (1,2,1);
h1 = plot (x, sin (x));
subplot (1,2,2);
h2 = plot (x, cos (x));
hlink = linkprop ([h1, h2], {"color","linestyle"});
set (h1, "color", "green");
set (h2, "linestyle", "--");

另请参阅： linkaxes，addlistener。

linkaxes (hax) ¶

linkaxes (hax, optstr) ¶

链接二维图的轴限制，使得一个轴的变化传播到其他轴。

要链接的轴句柄作为第一个参数 hax 传入。

可选的第二个参数是一个字符串，用于定义要链接的轴限制。optstr 的可能值如下：

"x"

链接 x 轴

"y"

链接 y 轴

"xy"（默认值）

链接两个轴

"off"

关闭链接

如果未指定，默认情况下同时链接 X 轴和 Y 轴。

进行链接时，hax 中第一个轴的限制将应用于列表中的其他轴。此后对任何一个轴的更改将传播到其他轴。

另请参阅： linkprop，addproperty。

这些功能被用于许多基本图形对象中。Octave 函数创建的 hggroup 对象包含一个或多个图形对象，用于：

• 将多个图形对象组合在一起，
• 在不同图形对象之间创建链接属性，以及
• 隐藏名义上的用户数据与对象的实际数据之间的差异。

例如，stem 函数创建一个茎叶图序列，其中茎叶图序列的每个 hggroup 包含两个线对象，分别表示茎的主体和头部。茎叶图序列的 hggroup 的 ydata 属性表示茎的头部，而茎的主体位于基线和该值之间。例如：

h = stem (1:4)
get (h, "xdata")
⇒  [  1   2   3   4]'
get (get (h, "children")(1), "xdata")
⇒  [  1   1 NaN   2   2 NaN   3   3 NaN   4   4 NaN]'

这展示了茎叶图序列对象的 hggroup 的 xdata 与其底层线条之间的差异。

此类组对象的基本特性是：它们由一个或多个链接的 hggroup 组成，并且这些组的某些属性的更改会传播到组的其他成员。而组中某些成员属性仅适用于当前成员。

此外，组的成员还可以通过回调函数链接到其他图形对象。例如，bar 或 stem 函数的基线是一个线条对象，其长度和位置会根据相应的 hggroup 元素的变化自动调整。

• 对象组中的数据源
• 区域序列
• 条形序列
• 等高线组
• 误差条序列
• 线条序列
• 箭头组
• 阶梯组
• 茎叶图序列
• 曲面组