octave: Object Groups
15.4.6 Object Groups
--------------------
A number of Octave high level plot functions return groups of other
graphics objects or they return graphics objects that have their
properties linked in such a way that changes to one of the properties
results in changes in the others. A graphic object that groups other
objects is an ‘hggroup’
-- : hggroup ()
-- : hggroup (HAX)
-- : hggroup (..., PROPERTY, VALUE, ...)
-- : H = hggroup (...)
Create handle graphics group object with axes parent HAX.
If no parent is specified, the group is created in the current
axes.
Multiple property/value pairs may be specified for the hggroup, but
they must appear in pairs.
The optional return value H is a graphics handle to the created
hggroup object.
Programming Note: An hggroup is a way to group base graphics
objects such as line objects or patch objects into a single unit
which can react appropriately. For example, the individual lines
of a contour plot are collected into a single hggroup so that they
can be made visible/invisible with a single command, ‘set
(hg_handle, "visible", "off")’.
DONTPRINTYET See also: 
addproperty XREFaddproperty, *noteaddlistener:
DONTPRINTYET See also: addproperty XREFaddproperty, addlistener
XREFaddlistener.
For example a simple use of a ‘hggroup’ might be
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");
which groups the two plots into a single object and controls their
visibility directly. The default properties of an ‘hggroup’ are the
same as the set of common properties for the other graphics objects.
Additional properties can be added with the ‘addproperty’ function.
-- : addproperty (NAME, H, TYPE)
-- : addproperty (NAME, H, TYPE, ARG, ...)
Create a new property named NAME in graphics object H.
TYPE determines the type of the property to create. ARGS usually
contains the default value of the property, but additional
arguments might be given, depending on the type of the property.
The supported property types are:
‘string’
A string property. ARG contains the default string value.
‘any’
An un-typed property. This kind of property can hold any
octave value. ARGS contains the default value.
‘radio’
A string property with a limited set of accepted values. The
first argument must be a string with all accepted values
separated by a vertical bar (’|’). The default value can be
marked by enclosing it with a ’{’ ’}’ pair. The default value
may also be given as an optional second string argument.
‘boolean’
A boolean property. This property type is equivalent to a
radio property with "on|off" as accepted values. ARG contains
the default property value.
‘double’
A scalar double property. ARG contains the default value.
‘handle’
A handle property. This kind of property holds the handle of
a graphics object. ARG contains the default handle value.
When no default value is given, the property is initialized to
the empty matrix.
‘data’
A data (matrix) property. ARG contains the default data
value. When no default value is given, the data is
initialized to the empty matrix.
‘color’
A color property. ARG contains the default color value. When
no default color is given, the property is set to black. An
optional second string argument may be given to specify an
additional set of accepted string values (like a radio
property).
TYPE may also be the concatenation of a core object type and a
valid property name for that object type. The property created
then has the same characteristics as the referenced property (type,
possible values, hidden state...). This allows one to clone an
existing property into the graphics object H.
Examples:
addproperty ("my_property", gcf, "string", "a string value");
addproperty ("my_radio", gcf, "radio", "val_1|val_2|{val_3}");
addproperty ("my_style", gcf, "linelinestyle", "--");
DONTPRINTYET See also: addlistener XREFaddlistener, *notehggroup:
DONTPRINTYET See also: addlistener XREFaddlistener, hggroup
XREFhggroup.
Once a property in added to an ‘hggroup’, it is not linked to any
other property of either the children of the group, or any other
graphics object. Add so to control the way in which this newly added
property is used, the ‘addlistener’ function is used to define a
callback function that is executed when the property is altered.
-- : addlistener (H, PROP, FCN)
Register FCN as listener for the property PROP of the graphics
object H.
Property listeners are executed (in order of registration) when the
property is set. The new value is already available when the
listeners are executed.
PROP must be a string naming a valid property in H.
FCN can be a function handle, a string or a cell array whose first
element is a function handle. If FCN is a function handle, the
corresponding function should accept at least 2 arguments, that
will be set to the object handle and the empty matrix respectively.
If FCN is a string, it must be any valid octave expression. If FCN
is a cell array, the first element must be a function handle with
the same signature as described above. The next elements of the
cell array are passed as additional arguments to the function.
Example:
function my_listener (h, dummy, p1)
fprintf ("my_listener called with p1=%s\n", p1);
endfunction
addlistener (gcf, "position", {@my_listener, "my string"})
DONTPRINTYET See also: dellistener XREFdellistener, *noteaddproperty:
DONTPRINTYET See also: dellistener XREFdellistener, addproperty
XREFaddproperty, hggroup XREFhggroup.
-- : dellistener (H, PROP, FCN)
Remove the registration of FCN as a listener for the property PROP
of the graphics object H.
The function FCN must be the same variable (not just the same
value), as was passed to the original call to ‘addlistener’.
If FCN is not defined then all listener functions of PROP are
removed.
Example:
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);
See also: addlistener XREFaddlistener.
An example of the use of these two functions might be
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
that adds a ‘linestyle’ property to the ‘hggroup’ and propagating any
changes its value to the children of the group. The ‘linkprop’ function
can be used to simplify the above to be
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", ...})
Link graphic object properties, such that a change in one is
propagated to the others.
The input H is a vector of graphic handles to link.
PROP may be a string when linking a single property, or a cell
array of strings for multiple properties. During the linking
process all properties in PROP will initially be set to the values
that exist on the first object in the list H.
The function returns HLINK which is a special object describing the
link. As long as the reference HLINK exists the link between
graphic objects will be active. This means that HLINK must be
preserved in a workspace variable, a global variable, or otherwise
stored using a function such as ‘setappdata’, ‘guidata’. To unlink
properties, execute ‘clear HLINK’.
An example of the use of ‘linkprop’ is
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", "--");
See also: linkaxes XREFlinkaxes.
-- : linkaxes (HAX)
-- : linkaxes (HAX, OPTSTR)
Link the axis limits of 2-D plots such that a change in one is
propagated to the others.
The axes handles to be linked are passed as the first argument HAX.
The optional second argument is a string which defines which axis
limits will be linked. The possible values for OPTSTR are:
"x"
Link x-axes
"y"
Link y-axes
"xy" (default)
Link both axes
"off"
Turn off linking
If unspecified the default is to link both X and Y axes.
When linking, the limits from the first axes in HAX are applied to
the other axes in the list. Subsequent changes to any one of the
axes will be propagated to the others.
DONTPRINTYET See also: linkprop XREFlinkprop, *noteaddproperty:
DONTPRINTYET See also: linkprop XREFlinkprop, addproperty
XREFaddproperty.
These capabilities are used in a number of basic graphics objects.
The ‘hggroup’ objects created by the functions of Octave contain one or
more graphics object and are used to:
• group together multiple graphics objects,
• create linked properties between different graphics objects, and
• to hide the nominal user data, from the actual data of the objects.
For example the ‘stem’ function creates a stem series where each
‘hggroup’ of the stem series contains two line objects representing the
body and head of the stem. The ‘ydata’ property of the ‘hggroup’ of the
stem series represents the head of the stem, whereas the body of the
stem is between the baseline and this value. For example
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]'
shows the difference between the ‘xdata’ of the ‘hggroup’ of a stem
series object and the underlying line.
The basic properties of such group objects is that they consist of
one or more linked ‘hggroup’, and that changes in certain properties of
these groups are propagated to other members of the group. Whereas,
certain properties of the members of the group only apply to the current
member.
In addition the members of the group can also be linked to other
graphics objects through callback functions. For example the baseline
of the ‘bar’ or ‘stem’ functions is a line object, whose length and
position are automatically adjusted, based on changes to the
corresponding hggroup elements.
Menu
Info Catalog
octave: Application-defined Data
octave: Advanced Plotting
octave: Graphics Toolkits