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

Булево свойство. Этот тип свойства эквивалентен радио-свойству со значениями "вкл|выкл". 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) ¶

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

Дескрипторы осей, которые необходимо связать, передаются в качестве первого аргумента 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.

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