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是图形句柄，则返回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) ¶

从图像对象返回命名属性p的值 h。

如果省略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'});
  

• as a structure 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) ¶

构造一个图形句柄对象h，从结构体s中。

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

如果指定了现存的绘图或轴句柄，p，新对象将作为该对象的子对象创建。 如果不指定父句柄，则一个新的绘图对象和必要的子对象将使用根对象的默认值构造。

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

See also: 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.