1
1
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5
5
<title>Object properties</title>
6
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2">
7
<link rel="start" href="index.html" title="GObject Reference Manual">
6
<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
7
<link rel="home" href="index.html" title="GObject Reference Manual">
8
8
<link rel="up" href="chapter-gobject.html" title="The GObject base class">
9
9
<link rel="prev" href="gobject-memory.html" title="Object memory management">
10
10
<link rel="next" href="chapter-signal.html" title="The GObject messaging system">
11
<meta name="generator" content="GTK-Doc V1.9 (XML mode)">
11
<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
12
12
<link rel="stylesheet" href="style.css" type="text/css">
13
13
<link rel="preface" href="pr01.html" title="Introduction">
14
<link rel="part" href="pt01.html" title="Part I. Concepts">
14
<link rel="part" href="pt01.html" title="Part I. Concepts">
15
15
<link rel="chapter" href="chapter-intro.html" title="Background">
16
16
<link rel="chapter" href="chapter-gtype.html" title="The GLib Dynamic Type System">
17
17
<link rel="chapter" href="chapter-gobject.html" title="The GObject base class">
18
18
<link rel="chapter" href="chapter-signal.html" title="The GObject messaging system">
19
19
<link rel="reference" href="rn01.html" title="API Reference">
20
20
<link rel="reference" href="rn02.html" title="Tools Reference">
21
<link rel="part" href="pt02.html" title="Part IV. Tutorial">
21
<link rel="part" href="pt02.html" title="Part IV. Tutorial">
22
22
<link rel="chapter" href="howto-gobject.html" title="How to define and implement a new GObject">
23
23
<link rel="chapter" href="howto-interface.html" title="How to define and implement interfaces">
24
24
<link rel="chapter" href="howto-signals.html" title="How to create and use signals">
25
<link rel="part" href="pt03.html" title="Part V. Related Tools">
25
<link rel="part" href="pt03.html" title="Part V. Related Tools">
26
<link rel="chapter" href="tools-vala.html" title="Vala">
26
27
<link rel="chapter" href="tools-gob.html" title="GObject builder">
27
28
<link rel="chapter" href="tools-ginspector.html" title="Graphical inspection of GObjects">
28
29
<link rel="chapter" href="tools-refdb.html" title="Debugging reference count problems">
64
66
/* Implementation */
65
67
/************************************************/
68
MAMAN_BAR_CONSTRUCT_NAME = 1,
69
MAMAN_BAR_PAPA_NUMBER,
73
maman_bar_instance_init (GTypeInstance *instance,
76
MamanBar *self = (MamanBar *)instance;
80
78
maman_bar_set_property (GObject *object,
82
80
const GValue *value,
85
MamanBar *self = (MamanBar *) object;
87
switch (property_id) {
88
case MAMAN_BAR_CONSTRUCT_NAME: {
89
g_free (self->priv->name);
90
self->priv->name = g_value_dup_string (value);
91
g_print ("maman: %s\n",self->priv->name);
94
case MAMAN_BAR_PAPA_NUMBER: {
95
self->priv->papa_number = g_value_get_uchar (value);
96
g_print ("papa: %u\n",self->priv->papa_number);
100
/* We don't have any other property... */
101
G_OBJECT_WARN_INVALID_PROPERTY_ID(object,property_id,pspec);
83
MamanBar *self = MAMAN_BAR (object);
88
g_free (self->priv->name);
89
self->priv->name = g_value_dup_string (value);
90
g_print ("maman: %s\n", self->priv->name);
93
case PROP_PAPA_NUMBER:
94
self->priv->papa_number = g_value_get_uchar (value);
95
g_print ("papa: %u\n", self->priv->papa_number);
99
/* We don't have any other property... */
100
G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
107
maman_bar_get_property (GObject *object,
106
maman_bar_get_property (GObject *object,
112
MamanBar *self = (MamanBar *) object;
114
switch (property_id) {
115
case MAMAN_BAR_CONSTRUCT_NAME: {
116
g_value_set_string (value, self->priv->name);
119
case MAMAN_BAR_PAPA_NUMBER: {
120
g_value_set_uchar (value, self->priv->papa_number);
124
/* We don't have any other property... */
125
G_OBJECT_WARN_INVALID_PROPERTY_ID(object,property_id,pspec);
111
MamanBar *self = MAMAN_BAR (object);
115
case PROP_MAMAN_NAME:
116
g_value_set_string (value, self->priv->name);
119
case PROP_PAPA_NUMBER:
120
g_value_set_uchar (value, self->priv->papa_number);
124
/* We don't have any other property... */
125
G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
131
maman_bar_class_init (gpointer g_class,
132
gpointer g_class_data)
131
maman_bar_class_init (MamanBarClass *klass)
134
133
GObjectClass *gobject_class = G_OBJECT_CLASS (g_class);
135
MamanBarClass *klass = MAMAN_BAR_CLASS (g_class);
136
134
GParamSpec *pspec;
138
136
gobject_class->set_property = maman_bar_set_property;
164
162
/************************************************/
168
167
bar = g_object_new (MAMAN_TYPE_SUBBAR, NULL);
169
169
g_value_init (&val, G_TYPE_CHAR);
170
170
g_value_set_char (&val, 11);
171
172
g_object_set_property (G_OBJECT (bar), "papa-number", &val);
174
g_value_unset (&val);
174
177
The client code just above looks simple but a lot of things happen under the hood:
177
<code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-set-property">g_object_set_property</a></code> first ensures a property
180
<code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-set-property" title="g_object_set_property ()">g_object_set_property</a></code> first ensures a property
178
181
with this name was registered in bar's class_init handler. If so, it calls
179
182
<code class="function">object_set_property</code> which first walks the class hierarchy,
180
183
from bottom, most derived type, to top, fundamental type to find the class
185
188
If the user provides a signed char GValue, as is shown
186
189
here, and if the object's property was registered as an unsigned int,
187
<code class="function"><a class="link" href="gobject-Generic-values.html#g-value-transform">g_value_transform</a></code> will try to transform the input signed char into
190
<code class="function"><a class="link" href="gobject-Generic-values.html#g-value-transform" title="g_value_transform ()">g_value_transform</a></code> will try to transform the input signed char into
188
191
an unsigned int. Of course, the success of the transformation depends on the availability
189
192
of the required transform function. In practice, there will almost always be a transformation
190
<sup>[<a name="id2814560" href="#ftn.id2814560" class="footnote">6</a>]</sup>
193
<sup>[<a name="id3013964" href="#ftn.id3013964" class="footnote">6</a>]</sup>
191
194
which matches and conversion will be carried out if needed.
194
After transformation, the <span class="type"><a class="link" href="gobject-Generic-values.html#GValue">GValue</a></span> is validated by
195
<code class="function"><a class="link" href="gobject-GParamSpec.html#g-param-value-validate">g_param_value_validate</a></code> which makes sure the user's
196
data stored in the <span class="type"><a class="link" href="gobject-Generic-values.html#GValue">GValue</a></span> matches the characteristics specified by
197
the property's <span class="type"><a class="link" href="gobject-GParamSpec.html#GParamSpec">GParamSpec</a></span>. Here, the <span class="type"><a class="link" href="gobject-GParamSpec.html#GParamSpec">GParamSpec</a></span> we
197
After transformation, the <span class="type"><a class="link" href="gobject-Generic-values.html#GValue" title="GValue">GValue</a></span> is validated by
198
<code class="function"><a class="link" href="gobject-GParamSpec.html#g-param-value-validate" title="g_param_value_validate ()">g_param_value_validate</a></code> which makes sure the user's
199
data stored in the <span class="type"><a class="link" href="gobject-Generic-values.html#GValue" title="GValue">GValue</a></span> matches the characteristics specified by
200
the property's <span class="type"><a class="link" href="gobject-GParamSpec.html#GParamSpec" title="GParamSpec">GParamSpec</a></span>. Here, the <span class="type"><a class="link" href="gobject-GParamSpec.html#GParamSpec" title="GParamSpec">GParamSpec</a></span> we
198
201
provided in class_init has a validation function which makes sure that the GValue
199
202
contains a value which respects the minimum and maximum bounds of the
200
<span class="type"><a class="link" href="gobject-GParamSpec.html#GParamSpec">GParamSpec</a></span>. In the example above, the client's GValue does not
203
<span class="type"><a class="link" href="gobject-GParamSpec.html#GParamSpec" title="GParamSpec">GParamSpec</a></span>. In the example above, the client's GValue does not
201
204
respect these constraints (it is set to 11, while the maximum is 10). As such, the
202
<code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-set-property">g_object_set_property</a></code> function will return with an error.
205
<code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-set-property" title="g_object_set_property ()">g_object_set_property</a></code> function will return with an error.
205
If the user's GValue had been set to a valid value, <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-set-property">g_object_set_property</a></code>
208
If the user's GValue had been set to a valid value, <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-set-property" title="g_object_set_property ()">g_object_set_property</a></code>
206
209
would have proceeded with calling the object's set_property class method. Here, since our
207
210
implementation of Foo did override this method, the code path would jump to
208
211
<code class="function">foo_set_property</code> after having retrieved from the
209
<span class="type"><a class="link" href="gobject-GParamSpec.html#GParamSpec">GParamSpec</a></span> the <span class="emphasis"><em>param_id</em></span>
210
<sup>[<a name="id2814662" href="#ftn.id2814662" class="footnote">7</a>]</sup>
212
<span class="type"><a class="link" href="gobject-GParamSpec.html#GParamSpec" title="GParamSpec">GParamSpec</a></span> the <span class="emphasis"><em>param_id</em></span>
213
<sup>[<a name="id3014079" href="#ftn.id3014079" class="footnote">7</a>]</sup>
211
214
which had been stored by
212
<code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-class-install-property">g_object_class_install_property</a></code>.
215
<code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-class-install-property" title="g_object_class_install_property ()">g_object_class_install_property</a></code>.
215
218
Once the property has been set by the object's set_property class method, the code path
216
returns to <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-set-property">g_object_set_property</a></code> which calls
219
returns to <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-set-property" title="g_object_set_property ()">g_object_set_property</a></code> which calls
217
220
<code class="function">g_object_notify_queue_thaw</code>. This function makes sure that
218
221
the "notify" signal is emitted on the object's instance with the changed property as
219
parameter unless notifications were frozen by <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-freeze-notify">g_object_freeze_notify</a></code>.
222
parameter unless notifications were frozen by <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-freeze-notify" title="g_object_freeze_notify ()">g_object_freeze_notify</a></code>.
222
<code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-thaw-notify">g_object_thaw_notify</a></code> can be used to re-enable notification of
225
<code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-thaw-notify" title="g_object_thaw_notify ()">g_object_thaw_notify</a></code> can be used to re-enable notification of
223
226
property modifications through the "notify" signal. It is important to remember that
224
227
even if properties are changed while property change notification is frozen, the "notify"
225
228
signal will be emitted once for each of these changed properties as soon as the property
253
256
This saves us from managing the GValues that we were needing to handle when using
254
<code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-set-property">g_object_set_property</a></code>.
257
<code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-set-property" title="g_object_set_property ()">g_object_set_property</a></code>.
255
258
The code above will trigger one notify signal emission for each property modified.
258
Of course, the _get versions are also available: <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-get">g_object_get</a></code>
259
and <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-get-valist">g_object_get_valist</a></code> (vararg version) can be used to get numerous
261
Of course, the _get versions are also available: <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-get" title="g_object_get ()">g_object_get</a></code>
262
and <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-get-valist" title="g_object_get_valist ()">g_object_get_valist</a></code> (vararg version) can be used to get numerous
260
263
properties at once.
267
270
NULL will lead to unexpected behaviour.
270
Really attentive readers now understand how <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new">g_object_new</a></code>,
271
<code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-newv">g_object_newv</a></code> and <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new-valist">g_object_new_valist</a></code>
273
Really attentive readers now understand how <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code>,
274
<code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-newv" title="g_object_newv ()">g_object_newv</a></code> and <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new-valist" title="g_object_new_valist ()">g_object_new_valist</a></code>
272
275
work: they parse the user-provided variable number of parameters and invoke
273
<code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-set">g_object_set</a></code> on the parameters only after the object has been successfully constructed.
276
<code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-set" title="g_object_set ()">g_object_set</a></code> on the parameters only after the object has been successfully constructed.
274
277
Of course, the "notify" signal will be emitted for each property set.
277
280
<div class="footnotes">
278
281
<br><hr width="100" align="left">
279
<div class="footnote"><p><sup>[<a name="ftn.id2814560" href="#id2814560" class="para">6</a>] </sup>Its behaviour might not be what you expect but it is up to you to actually avoid
282
<div class="footnote"><p><sup>[<a name="ftn.id3013964" href="#id3013964" class="para">6</a>] </sup>Its behaviour might not be what you expect but it is up to you to actually avoid
280
283
relying on these transformations.
282
<div class="footnote"><p><sup>[<a name="ftn.id2814662" href="#id2814662" class="para">7</a>] </sup>
285
<div class="footnote"><p><sup>[<a name="ftn.id3014079" href="#id3014079" class="para">7</a>] </sup>
283
286
It should be noted that the param_id used here need only to uniquely identify each
284
<span class="type"><a class="link" href="gobject-GParamSpec.html#GParamSpec">GParamSpec</a></span> within the <span class="type">FooClass</span> such that the switch
287
<span class="type"><a class="link" href="gobject-GParamSpec.html#GParamSpec" title="GParamSpec">GParamSpec</a></span> within the <span class="type">FooClass</span> such that the switch
285
288
used in the set and get methods actually works. Of course, this locally-unique
286
289
integer is purely an optimization: it would have been possible to use a set of
287
290
<span class="emphasis"><em>if (strcmp (a, b) == 0) {} else if (strcmp (a, b) == 0) {}</em></span> statements.
296
Generated by GTK-Doc V1.11</div>
added
removed
docs/reference/gobject/html/gobject-properties.html
