15.4.6 Группы объектов

Некоторые высокоуровневые графические функции Octave возвращают группы других графических объектов или графические объекты, свойства которых связаны таким образом, что изменение одного свойства приводит к изменению остальных. Графический объект, объединяющий другие объекты, — это hggroup

: hggroup ()

: hggroup (hax)

: hggroup (…, property, value, …)

: h = hggroup (…)

Создать объект группы графических дескрипторов с родительской системой координат hax.

Если родительский объект не указан, группа создаётся в текущей системе координат.

Для hggroup можно указать несколько пар свойство/значение, однако они должны быть заданы попарно. Полный список свойств приведён в разделе Свойства систем координат.

Необязательное возвращаемое значение h — графический дескриптор созданного объекта hggroup.

Примечание по программированию: hggroup позволяет объединять базовые графические объекты, такие как линейные объекты или объекты patch, в единое целое, которое может соответствующим образом реагировать на изменения. Например, отдельные линии контурного графика собираются в один 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

Логическое свойство. Этот тип свойства эквивалентен свойству radio с допустимыми значениями "on|off". 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 в качестве слушателя свойства prop графического объекта h.

Слушатели свойств выполняются (в порядке регистрации) при задании свойства. Новое значение уже доступно на момент выполнения слушателей.

prop должна быть строкой с именем допустимого свойства объекта h.

fcn может быть дескриптором функции, строкой или массивом ячеек, первым элементом которого является дескриптор функции. Если fcn — дескриптор функции, соответствующая функция должна принимать не менее двух аргументов, которым будут переданы дескриптор объекта и пустая матрица соответственно. Если 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 в качестве слушателя свойства prop графического объекта h.

Переменная 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

добавляет свойство linestyle объекту hggroup и передаёт все изменения его значения дочерним объектам группы. Функцию 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.

Эти возможности используются в ряде базовых графических объектов. Объекты hggroup, создаваемые функциями Octave, содержат один или несколько графических объектов и используются для того, чтобы:

• объединять несколько графических объектов,
• создавать связанные свойства разных графических объектов и
• отделять пользовательские данные от фактических данных объектов.

Например, функция stem создаёт ряд stem, в котором каждый hggroup ряда stem содержит два линейных объекта, представляющих тело и головку линии stem. Свойство ydata объекта hggroup ряда stem представляет головку линии stem, тогда как тело линии stem расположено между базовой линией и этим значением. Например:

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]'

показывает различие между xdata объекта hggroup ряда stem и соответствующей базовой линией.

Основные свойства таких групповых объектов заключаются в том, что они состоят из одного или нескольких связанных hggroup, а изменения некоторых свойств этих групп передаются другим участникам группы. При этом некоторые свойства участников группы применяются только к текущему участнику.

Кроме того, участников группы можно связать с другими графическими объектами с помощью функций обратного вызова. Например, базовая линия функций bar или stem — это линейный объект, длина и положение которого автоматически корректируются при изменении соответствующих элементов hggroup.

• Источники данных в группах объектов
• Ряды областей
• Столбчатые ряды
• Группы контуров
• Ряды с полосами погрешностей
• Линейные ряды
• Группа векторного поля
• Ступенчатая группа
• Ряды stem
• Группа поверхностей