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

Скалярное двойное свойство. 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.