1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Octave: Object Groups</title>
<meta name="description" content="GNU Octave: Object Groups">
<meta name="keywords" content="GNU Octave: Object Groups">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Advanced-Plotting.html#Advanced-Plotting" rel="up" title="Advanced Plotting">
<link href="Data-Sources-in-Object-Groups.html#Data-Sources-in-Object-Groups" rel="next" title="Data Sources in Object Groups">
<link href="Application_002ddefined-Data.html#Application_002ddefined-Data" rel="prev" title="Application-defined Data">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Object-Groups"></a>
<div class="header">
<p>
Next: <a href="Graphics-Toolkits.html#Graphics-Toolkits" accesskey="n" rel="next">Graphics Toolkits</a>, Previous: <a href="Application_002ddefined-Data.html#Application_002ddefined-Data" accesskey="p" rel="prev">Application-defined Data</a>, Up: <a href="Advanced-Plotting.html#Advanced-Plotting" accesskey="u" rel="up">Advanced Plotting</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Object-Groups-1"></a>
<h4 class="subsection">15.4.6 Object Groups</h4>
<a name="index-object-groups"></a>
<p>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 <code>hggroup</code>
</p>
<a name="XREFhggroup"></a><dl>
<dt><a name="index-hggroup"></a>Function File: <em></em> <strong>hggroup</strong> <em>()</em></dt>
<dt><a name="index-hggroup-1"></a>Function File: <em></em> <strong>hggroup</strong> <em>(<var>hax</var>)</em></dt>
<dt><a name="index-hggroup-2"></a>Function File: <em></em> <strong>hggroup</strong> <em>(…, <var>property</var>, <var>value</var>, …)</em></dt>
<dt><a name="index-hggroup-3"></a>Function File: <em><var>h</var> =</em> <strong>hggroup</strong> <em>(…)</em></dt>
<dd><p>Create handle graphics group object with axes parent <var>hax</var>.
</p>
<p>If no parent is specified, the group is created in the current axes.
</p>
<p>Multiple property/value pairs may be specified for the hggroup, but they
must appear in pairs.
</p>
<p>The optional return value <var>h</var> is a graphics handle to the created
hggroup object.
</p>
<p>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, <code>set (hg_handle, "visible", "off")</code>.
</p>
<p><strong>See also:</strong> <a href="#XREFaddproperty">addproperty</a>, <a href="#XREFaddlistener">addlistener</a>.
</p></dd></dl>
<p>For example a simple use of a <code>hggroup</code> might be
</p>
<div class="example">
<pre class="example">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");
</pre></div>
<p>which groups the two plots into a single object and controls their
visibility directly. The default properties of an <code>hggroup</code> are
the same as the set of common properties for the other graphics
objects. Additional properties can be added with the <code>addproperty</code>
function.
</p>
<a name="XREFaddproperty"></a><dl>
<dt><a name="index-addproperty"></a>Built-in Function: <em></em> <strong>addproperty</strong> <em>(<var>name</var>, <var>h</var>, <var>type</var>)</em></dt>
<dt><a name="index-addproperty-1"></a>Built-in Function: <em></em> <strong>addproperty</strong> <em>(<var>name</var>, <var>h</var>, <var>type</var>, <var>arg</var>, …)</em></dt>
<dd><p>Create a new property named <var>name</var> in graphics object <var>h</var>.
<var>type</var> determines the type of the property to create. <var>args</var>
usually contains the default value of the property, but additional
arguments might be given, depending on the type of the property.
</p>
<p>The supported property types are:
</p>
<dl compact="compact">
<dt><code>string</code></dt>
<dd><p>A string property. <var>arg</var> contains the default string value.
</p>
</dd>
<dt><code>any</code></dt>
<dd><p>An un-typed property. This kind of property can hold any octave
value. <var>args</var> contains the default value.
</p>
</dd>
<dt><code>radio</code></dt>
<dd><p>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.
</p>
</dd>
<dt><code>boolean</code></dt>
<dd><p>A boolean property. This property type is equivalent to a radio
property with "on|off" as accepted values. <var>arg</var> contains
the default property value.
</p>
</dd>
<dt><code>double</code></dt>
<dd><p>A scalar double property. <var>arg</var> contains the default value.
</p>
</dd>
<dt><code>handle</code></dt>
<dd><p>A handle property. This kind of property holds the handle of a
graphics object. <var>arg</var> contains the default handle value.
When no default value is given, the property is initialized to
the empty matrix.
</p>
</dd>
<dt><code>data</code></dt>
<dd><p>A data (matrix) property. <var>arg</var> contains the default data
value. When no default value is given, the data is initialized to
the empty matrix.
</p>
</dd>
<dt><code>color</code></dt>
<dd><p>A color property. <var>arg</var> 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).
</p></dd>
</dl>
<p><var>type</var> 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 to clone an existing
property into the graphics object <var>h</var>.
</p>
<p>Examples:
</p>
<div class="example">
<pre class="example">addproperty ("my_property", gcf, "string", "a string value");
addproperty ("my_radio", gcf, "radio", "val_1|val_2|{val_3}");
addproperty ("my_style", gcf, "linelinestyle", "--");
</pre></div>
<p><strong>See also:</strong> <a href="#XREFaddlistener">addlistener</a>, <a href="#XREFhggroup">hggroup</a>.
</p></dd></dl>
<p>Once a property in added to an <code>hggroup</code>, 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 <code>addlistener</code> function is used to define a
callback function that is executed when the property is altered.
</p>
<a name="XREFaddlistener"></a><dl>
<dt><a name="index-addlistener"></a>Built-in Function: <em></em> <strong>addlistener</strong> <em>(<var>h</var>, <var>prop</var>, <var>fcn</var>)</em></dt>
<dd><p>Register <var>fcn</var> as listener for the property <var>prop</var> of the graphics
object <var>h</var>. Property listeners are executed (in order of registration)
when the property is set. The new value is already available when the
listeners are executed.
</p>
<p><var>prop</var> must be a string naming a valid property in <var>h</var>.
</p>
<p><var>fcn</var> can be a function handle, a string or a cell array whose first
element is a function handle. If <var>fcn</var> 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 <var>fcn</var>
is a string, it must be any valid octave expression. If <var>fcn</var> 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.
</p>
<p>Example:
</p>
<div class="example">
<pre class="example">function my_listener (h, dummy, p1)
fprintf ("my_listener called with p1=%s\n", p1);
endfunction
addlistener (gcf, "position", {@my_listener, "my string"})
</pre></div>
<p><strong>See also:</strong> <a href="#XREFaddproperty">addproperty</a>, <a href="#XREFhggroup">hggroup</a>.
</p></dd></dl>
<a name="XREFdellistener"></a><dl>
<dt><a name="index-dellistener"></a>Built-in Function: <em></em> <strong>dellistener</strong> <em>(<var>h</var>, <var>prop</var>, <var>fcn</var>)</em></dt>
<dd><p>Remove the registration of <var>fcn</var> as a listener for the property
<var>prop</var> of the graphics object <var>h</var>. The function <var>fcn</var> must
be the same variable (not just the same value), as was passed to the
original call to <code>addlistener</code>.
</p>
<p>If <var>fcn</var> is not defined then all listener functions of <var>prop</var>
are removed.
</p>
<p>Example:
</p>
<div class="example">
<pre class="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);
</pre></div>
</dd></dl>
<p>An example of the use of these two functions might be
</p>
<div class="example">
<pre class="example">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
</pre></div>
<p>that adds a <code>linestyle</code> property to the <code>hggroup</code> and
propagating any changes its value to the children of the group. The
<code>linkprop</code> function can be used to simplify the above to be
</p>
<div class="example">
<pre class="example">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");
</pre></div>
<a name="XREFlinkprop"></a><dl>
<dt><a name="index-linkprop"></a>Function File: <em><var>hlink</var> =</em> <strong>linkprop</strong> <em>(<var>h</var>, <var>prop</var>)</em></dt>
<dt><a name="index-linkprop-1"></a>Function File: <em><var>hlink</var> =</em> <strong>linkprop</strong> <em>(<var>h</var>, {<var>prop1</var>, <var>prop2</var>, …})</em></dt>
<dd><p>Link graphics object properties, such that a change in one is
propagated to the others.
</p>
<p><var>prop</var> can be a string for a single property, or a cell array of strings
for multiple properties. <var>h</var> is an array of graphics handles which
will have their properties linked.
</p>
<p>An example of the use of <code>linkprop</code> is
</p>
<div class="example">
<pre class="example">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", "--");
</pre></div>
</dd></dl>
<p>These capabilities are used in a number of basic graphics objects.
The <code>hggroup</code> objects created by the functions of Octave contain
one or more graphics object and are used to:
</p>
<ul>
<li> group together multiple graphics objects,
</li><li> create linked properties between different graphics objects, and
</li><li> to hide the nominal user data, from the actual data of the objects.
</li></ul>
<p>For example the <code>stem</code> function creates a stem series where each
<code>hggroup</code> of the stem series contains two line objects representing
the body and head of the stem. The <code>ydata</code> property of the
<code>hggroup</code> 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
</p>
<div class="example">
<pre class="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]'
</pre></div>
<p>shows the difference between the <code>xdata</code> of the <code>hggroup</code>
of a stem series object and the underlying line.
</p>
<p>The basic properties of such group objects is that they consist of one
or more linked <code>hggroup</code>, 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.
</p>
<p>In addition the members of the group can also be linked to other
graphics objects through callback functions. For example the baseline of
the <code>bar</code> or <code>stem</code> functions is a line object, whose length
and position are automatically adjusted, based on changes to the
corresponding hggroup elements.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="Data-Sources-in-Object-Groups.html#Data-Sources-in-Object-Groups" accesskey="1">Data Sources in Object Groups</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="Area-Series.html#Area-Series" accesskey="2">Area Series</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="Bar-Series.html#Bar-Series" accesskey="3">Bar Series</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="Contour-Groups.html#Contour-Groups" accesskey="4">Contour Groups</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="Error-Bar-Series.html#Error-Bar-Series" accesskey="5">Error Bar Series</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="Line-Series.html#Line-Series" accesskey="6">Line Series</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="Quiver-Group.html#Quiver-Group" accesskey="7">Quiver Group</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="Scatter-Group.html#Scatter-Group" accesskey="8">Scatter Group</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="Stair-Group.html#Stair-Group" accesskey="9">Stair Group</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="Stem-Series.html#Stem-Series">Stem Series</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">• <a href="Surface-Group.html#Surface-Group">Surface Group</a>:</td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<div class="header">
<p>
Next: <a href="Graphics-Toolkits.html#Graphics-Toolkits" accesskey="n" rel="next">Graphics Toolkits</a>, Previous: <a href="Application_002ddefined-Data.html#Application_002ddefined-Data" accesskey="p" rel="prev">Application-defined Data</a>, Up: <a href="Advanced-Plotting.html#Advanced-Plotting" accesskey="u" rel="up">Advanced Plotting</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
