15.3.2.2 句柄函数 ¶

要判断一个变量是否是图形对象句柄，或者是否是坐标轴或图形窗口的句柄，可以使用函数 ishghandle, isgraphics, isaxes 和 isfigure。

tf = ishghandle (h) ¶

如果 h 是图形句柄，则返回 true，否则返回 false。

h 也可以是句柄矩阵，此时将返回一个逻辑数组，其中 h 的元素是图形句柄的位置为 true，否则为 false。

另请参阅: isgraphics, isaxes, isfigure, ishandle.

tf = isgraphics (h) ¶

tf = isgraphics (h, type) ¶

如果 h 是（指定类型 type 的）图形句柄，则返回 true，否则返回 false。

当未指定 type 时，该函数等效于 ishghandle。

另请参阅: ishghandle, ishandle, isaxes, isfigure.

tf = ishandle (h) ¶

如果 h 是图形对象或 Java 对象的句柄，则返回 true，否则返回 false。

h 也可以是句柄矩阵，此时将返回一个逻辑数组，其中 h 的元素是图形或 Java 对象句柄的位置为 true，否则为 false。

编程说明：通常更实用的做法是测试特定的对象类型。要判断一个句柄是否属于图形对象，请使用 ishghandle 或 isgraphics。要判断一个句柄是否属于 Java 对象，请使用 isjava。

另请参阅: ishghandle, isgraphics, isjava.

tf = isaxes (h) ¶

如果 h 是坐标轴图形句柄，则返回 true，否则返回 false。

如果 h 是矩阵，则返回一个逻辑数组，其中 h 的元素是坐标轴图形句柄的位置为 true，否则为 false。

另请参阅: isfigure, ishghandle, isgraphics.

tf = isfigure (h) ¶

如果 h 是图形窗口句柄，则返回 true，否则返回 false。

如果 h 是矩阵，则返回一个逻辑数组，其中 h 的元素是图形窗口句柄的位置为 true，否则为 false。

另请参阅: isaxes, ishghandle, isgraphics.

函数 gcf 返回当前图形窗口对象的句柄，如果不存在则创建一个。类似地，gca 返回当前坐标轴对象的句柄，如果不存在则创建一个（同时创建其父级图形窗口对象）。

h = groot () ¶

返回根图形对象的句柄。

根图形对象是所有图形对象的最终父级。

此外，根对象包含有关整个图形系统的信息，例如 ScreenSize。使用 get (groot) 可以查看有哪些信息可用。

整个图形系统的默认值是通过设置根图形对象中以 "Default" 开头的属性来指定的。例如，要将所有文本对象的默认字体设置为 FreeSans，请使用：

set (groot, "DefaultTextFontName", "FreeSans")

默认属性可以通过为 set 指定特殊属性值 "remove" 来删除。要撤销上面的默认字体分配，请使用：

set (groot, "DefaultTextFontName", "remove")

编程说明：根图形对象由特殊的句柄值 0 标识。这个唯一值未来可能会改变，但通过使用 groot 函数（保证始终返回根图形对象）可以使代码免受未来变化的影响。

另请参阅: gcf, gca, get, set.

h = gcf () ¶

返回当前图形窗口的句柄。

当前图形窗口是图形输出的默认目标。如果存在多个图形窗口，gcf 返回最后创建的或最后用鼠标点击的图形窗口。

如果当前图形窗口不存在，则创建一个并返回其句柄。然后可以使用该句柄来查看或设置图形窗口的属性。例如：

fplot (@sin, [-10, 10]);
fig = gcf ();
set (fig, "numbertitle", "off", "name", "sin plot")

这段代码绘制正弦波，查找当前图形窗口的句柄，然后重命名图形窗口以描述其内容。

注意：要在不创建新图形窗口的情况下查找当前图形（如果不存在），请查询根图形对象的 "CurrentFigure" 属性。

get (groot, "currentfigure");

另请参阅: gca, gco, gcbf, gcbo, get, set.

h = gca () ¶

返回当前坐标轴对象的句柄。

当前坐标轴是图形输出的默认目标。在一个图形窗口中包含多个坐标轴的情况下，gca 返回最后创建的或最后用鼠标点击的坐标轴。

如果当前坐标轴对象不存在，则创建一个并返回其句柄。然后可以使用该句柄来查看或设置坐标轴的属性。例如：

ax = gca ();
set (ax, "position", [0.5, 0.5, 0.5, 0.5]);

这段代码创建一个空的坐标轴对象，然后更改其在图形窗口中的位置和大小。

注意：要在不创建新坐标轴的情况下查找当前坐标轴（如果不存在），请查询图形窗口的 "CurrentAxes" 属性。

get (gcf, "currentaxes");

另请参阅: gcf, gco, gcbf, gcbo, get, set.

h = gco () ¶

h = gco (hfig) ¶

返回当前图形窗口中当前对象的句柄，或者返回句柄为 hfig 的图形窗口中当前对象的句柄。

图形窗口的当前对象是最后被鼠标点击的对象。它存储在目标图形窗口的 "CurrentObject" 属性中。

如果最后一次鼠标点击没有发生在图形窗口的任何子对象上，那么当前对象就是图形窗口本身。

如果目标图形窗口中没有发生过鼠标点击，则此函数返回空矩阵。

编程说明：此函数返回的值不一定与回调执行期间 gcbo 返回的值相同。正在执行的回调可能被另一个回调中断，从而导致当前对象发生变化。

另请参阅: gcbo, gca, gcf, gcbf, get, set.

get 和 set 函数可用于查看和设置图形对象的属性。例如：

get (groot)
    ⇒  ans =
       {
         type = root
         currentfigure = [](0x0)
         children = [](0x0)
         visible = on
         ...
       }

返回一个包含根图形对象所有属性的结构体。与 Octave 中的所有函数一样，该结构体是按值返回的，因此修改它不会修改内部的根对象。要修改根对象，必须使用 set 函数。另外请注意，在此例中，currentfigure 属性为空，表示当前没有图形窗口。

get 函数也可以用于查找单个属性的值。例如：

get (gca (), "xlim")
    ⇒  [ 0 1 ]

返回当前图形窗口中当前坐标轴对象的 x 轴范围。

要设置图形对象的属性，请使用 set 函数。例如：

set (gca (), "xlim", [-10, 10]);

将当前图形窗口中当前坐标轴对象的 x 轴范围设置为 ‘[-10, 10]’。

如果在调用 set 函数时不带值参数，还可以查询默认属性值。当只给一个参数（图形句柄）时，将返回一个结构体，其中包含给定对象类型的所有属性的默认值。例如：

set (gca ())

返回一个包含坐标轴对象默认属性值的结构体。如果 set 被传入两个参数（图形句柄和属性名），则只返回所请求属性的默认值。

val = get (h) ¶

val = get (h, p) ¶

从图形句柄 h 返回命名属性 p 的值。

如果省略 p，则返回 h 的完整属性列表。

如果 h 是向量，则返回一个元胞数组，其中分别包含属性值或列表。

另请参阅: set.

set (h, property, value, …) ¶

set (h, {properties}, {values}) ¶

set (h, pv) ¶

value_list = set (h, property) ¶

all_value_list = set (h) ¶

为图形句柄（或图形句柄向量）h 设置命名的属性值。

有三种方式提供属性名称和值：

• 作为 property, value 对的逗号分隔列表

  每个 property 是一个包含属性名称的字符串，每个 value 是该属性相应类型的值。当 h 中有多个句柄时，每个句柄都被赋予相同的 value。例如：

  h = plot ([0, 1]);
  set (h, 'color', 'green');
  

• 作为包含属性名称的字符串元胞数组 properties 和包含属性值的元胞数组 values。

  在这种情况下，values 的列数必须与 properties 中的元素数匹配。values 的第一列包含 properties 中第一个条目的值，以此类推。values 的行数必须为 1 或与 h 中的元素数匹配。在第一种情况下，h 中的每个句柄将被分配相同的值。在第二种情况下，h 中的第一个句柄将被分配 values 第一行的值，依此类推。例如：

  h = plot ([0, 1; 1, 0]);
  set (h, {'color'}, {'green'; 'red'});
  

• 作为结构体 pv

  这与第一种情况相同，其中 pv 的字段名表示属性名称，字段值给出属性值。与第一种情况一样，只能为属性设置一个值，该值将应用于 h 中的所有句柄。例如：

  h = plot ([0, 1]);
  props.color = 'green';
  set (h, props);
  

设置属性的三种语法可以任意组合使用。

set 还可用于查询命名属性可取值的列表。clist = set (h, "property") 将返回元胞数组 clist 中 "property" 的可能值列表。如果未使用输出变量，则列表将被格式化并打印到屏幕上。

如果未指定属性（slist = set (h)），则返回结构体 slist，其中字段名是对象 h 的属性，字段值是每个属性的可能值列表。如果未使用输出变量，则列表将被格式化并打印到屏幕上。

查询属性时，只允许为单个图形对象使用单个图形句柄 h。

查询示例：

hf = figure ();
set (hf, "paperorientation")
⇒   [ landscape | {portrait} ]

显示 paperorientation 属性可以取两个值，默认值为 "portrait"。

另请参阅: get.

parent = ancestor (h, type) ¶

parent = ancestor (h, type, "toplevel") ¶

返回句柄对象 h 的第一个祖先，其类型与 type 匹配，其中 type 是一个字符串。

如果 type 是一个字符串元胞数组，则返回第一个类型与任意给定类型字符串匹配的父对象。

如果句柄对象 h 本身属于 type 类型，则返回 h。

如果第三个参数给定为 "toplevel"，则返回对象层次结构中匹配条件的最高父级，而不是第一个（最近的）父级。

另请参阅: findobj, findall, allchild.

h = allchild (handles) ¶

查找图形对象的所有子对象，包括隐藏的子对象。

此函数类似于 get (h, "children")，但也会返回隐藏对象（HandleVisibility = "off"）。

如果 handles 是标量，则 h 为向量。否则，h 为与 handles 大小相同的元胞矩阵，每个元胞包含一个句柄向量。

另请参阅: findall, findobj, get, set.

findfigs () ¶

查找所有当前不可见的图形窗口并将它们移到屏幕上。

另请参阅: allchild, figure, get, set.

图形可以通过 print 和 saveas 以多种图形格式打印或保存。但有时直接保存原始的 Octave 句柄图形可能很有用，以便将来进行进一步修改，例如修改标题或图例。

这可以通过以下函数来实现：

fig_struct = hdl2struct (gcf);
save myplot.fig -struct fig_struct;
...
fig_struct = load ("myplot.fig");
struct2hdl (fig_struct);

s = hdl2struct (h) ¶

返回结构体 s，其中包含与句柄对象 h 及其子对象相关的属性。

结构体 s 的字段有 "type", "handle", "properties", "children" 和 "special"。

另请参阅: struct2hdl, hgsave, findobj.

h = struct2hdl (s) ¶

h = struct2hdl (s, p) ¶

h = struct2hdl (s, p, hilev) ¶

从结构体 s 构造图形句柄对象 h。

结构体必须包含字段 "handle", "type", "children", "properties" 和 "special"。

如果指定了现有图形窗口或坐标轴的句柄 p，新对象将创建为该对象的子对象。如果未提供父句柄，则将使用根对象的默认值构造一个新的图形窗口及其必要的子对象。

第三个布尔参数 hilev 可用于指定函数是否应保留监听器/回调，例如用于图例或 hggroup。默认值为 false。

另请参阅: hdl2struct, hgload, findobj.

hnew = copyobj (horig) ¶

hnew = copyobj (horig, hparent) ¶

构造与句柄 horig 关联的图形对象的副本，并返回新对象的句柄 hnew。

如果指定了父句柄 hparent（根、图形窗口、坐标轴或 hggroup），则复制的对象将创建为 hparent 的子对象。

如果 horig 是句柄向量而 hparent 是标量，则向量 hnew 中的每个句柄的 "Parent" 属性都设置为 hparent。反之，如果 horig 是标量而 hparent 是向量，则每个父对象都将收到 horig 的一个副本。如果 horig 和 hparent 都是具有相同元素数量的向量，则 hnew(i) 的父级为 hparent(i)。

另请参阅: struct2hdl, hdl2struct, findobj.