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.