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, …) ¶

Создаёт новое свойство с именем name в графическом объекте h.

type определяет тип создаваемого свойства. args обычно содержит значение по умолчанию свойства, но могут быть указаны дополнительные аргументы в зависимости от типа свойства.

Поддерживаемые типы свойств:

string

Строковое свойство. arg содержит значение строкового свойства по умолчанию.

any

Нетипизированное свойство. Такое свойство может содержать любое значение Octave. args содержит значение по умолчанию.

radio

Строковое свойство с ограниченным набором допустимых значений. Первый аргумент должен быть строкой со всеми допустимыми значениями, разделёнными вертикальной чертой (’|’). Значение по умолчанию может быть помечено парой ’{’ ’}’. Значение по умолчанию также может быть задано как необязательный второй строковый аргумент.

boolean

Булево свойство. Этот тип свойства эквивалентен радио-свойству с допустимыми значениями "on|off". arg содержит значение свойства по умолчанию.

double

Числовое свойство типа double. arg содержит значение по умолчанию.

handle

Свойство-дескриптор. Этот тип свойства содержит дескриптор графического объекта. arg содержит значение дескриптора по умолчанию. При отсутствии значения по умолчанию свойство инициализируется пустой матрицей.

data

Свойство данных (матрица). arg содержит значение данных по умолчанию. При отсутствии значения по умолчанию данные инициализируются пустой матрицей.

color

Свойство цвета. arg содержит значение цвета по умолчанию. При отсутствии значения по умолчанию свойство устанавливается в чёрный цвет. В качестве необязательного второго строкового аргумента можно указать дополнительный набор допустимых строковых значений (как для радио-свойств).

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 — функция-обработчик, соответствующая функция должна принимать как минимум 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 в качестве слушателя для свойства 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) ¶

Связывает пределы осей 2D графиков таким образом, что изменение одного распространяется на другие.

Дескрипторы осей, которые нужно связать, передаются в качестве первого аргумента hax.

Необязательный второй аргумент — это строка, определяющая, какие пределы осей будут связаны. Возможные значения для optstr:

"x"

Связать оси X

"y"

Связать оси Y

"xy" (по умолчанию)

Связать обе оси

"off"

Отключить связывание

Если не указано, по умолчанию связываются оси X и Y.

При связывании пределы от первой оси в hax применяются к другим осям в списке. Последующие изменения любой из осей будут переданы другим осям.

См. также: linkprop, addproperty.

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

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

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

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 объекта серии штрихов и базовой линией.

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

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

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