docs/reference/gobject/html/gobject-properties.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Object properties</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="index.html" title="GObject Reference Manual">
   8 <link rel="up" href="chapter-gobject.html" title="The GObject base class">
   9 <link rel="prev" href="gobject-memory.html" title="Object memory management">
  10 <link rel="next" href="chapter-signal.html" title="The GObject messaging system">
  11 <meta name="generator" content="GTK-Doc V1.13 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 <link rel="preface" href="pr01.html" title="Introduction">
  14 <link rel="part" href="pt01.html" title="Part I. Concepts">
  15 <link rel="chapter" href="chapter-intro.html" title="Background">
  16 <link rel="chapter" href="chapter-gtype.html" title="The GLib Dynamic Type System">
  17 <link rel="chapter" href="chapter-gobject.html" title="The GObject base class">
  18 <link rel="chapter" href="chapter-signal.html" title="The GObject messaging system">
  19 <link rel="reference" href="rn01.html" title="API Reference">
  20 <link rel="reference" href="rn02.html" title="Tools Reference">
  21 <link rel="part" href="pt02.html" title="Part IV. Tutorial">
  22 <link rel="chapter" href="howto-gobject.html" title="How to define and implement a new GObject">
  23 <link rel="chapter" href="howto-interface.html" title="How to define and implement interfaces">
  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">
  26 <link rel="chapter" href="tools-vala.html" title="Vala">
  27 <link rel="chapter" href="tools-gob.html" title="GObject builder">
  28 <link rel="chapter" href="tools-ginspector.html" title="Graphical inspection of GObjects">
  29 <link rel="chapter" href="tools-refdb.html" title="Debugging reference count problems">
  30 <link rel="chapter" href="tools-gtkdoc.html" title="Writing API docs">
  31 <link rel="index" href="api-index-full.html" title="Index">
  32 <link rel="index" href="api-index-deprecated.html" title="Index of deprecated symbols">
  33 <link rel="index" href="api-index-2-2.html" title="Index of new symbols in 2.2">
  34 <link rel="index" href="api-index-2-4.html" title="Index of new symbols in 2.4">
  35 <link rel="index" href="api-index-2-6.html" title="Index of new symbols in 2.6">
  36 <link rel="index" href="api-index-2-8.html" title="Index of new symbols in 2.8">
  37 <link rel="index" href="api-index-2-10.html" title="Index of new symbols in 2.10">
  38 <link rel="index" href="api-index-2-12.html" title="Index of new symbols in 2.12">
  39 <link rel="index" href="api-index-2-14.html" title="Index of new symbols in 2.14">
  40 <link rel="index" href="api-index-2-18.html" title="Index of new symbols in 2.18">
  41 <link rel="index" href="api-index-2-22.html" title="Index of new symbols in 2.22">
  42 <link rel="index" href="api-index-2-24.html" title="Index of new symbols in 2.24">
  43 </head>
  44 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  45 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
  46 <td><a accesskey="p" href="gobject-memory.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  47 <td><a accesskey="u" href="chapter-gobject.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  48 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  49 <th width="100%" align="center">GObject Reference Manual</th>
  50 <td><a accesskey="n" href="chapter-signal.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  51 </tr></table>
  52 <div class="sect1" title="Object properties">
  53 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  54 <a name="gobject-properties"></a>Object properties</h2></div></div></div>
  55 <p>
  56       One of GObject's nice features is its generic get/set mechanism for object
  57       properties. When an object
  58       is instantiated, the object's class_init handler should be used to register
  59       the object's properties with <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>
  60       (implemented in <code class="filename">gobject.c</code>).
  61     </p>
  62 <p>
  63       The best way to understand how object properties work is by looking at a real example
  64       on how it is used:
  65 </p>
  66 <pre class="programlisting">
  67 /************************************************/
  68 /* Implementation                               */
  69 /************************************************/
  70
  71 enum
  72 {
  73   PROP_0,
  74
  75   PROP_MAMAN_NAME,
  76   PROP_PAPA_NUMBER
  77 };
  78
  79 static void
  80 maman_bar_set_property (GObject      *object,
  81                         guint         property_id,
  82                         const GValue *value,
  83                         GParamSpec   *pspec)
  84 {
  85   MamanBar *self = MAMAN_BAR (object);
  86
  87   switch (property_id)
  88     {
  89     case PROP_MAMAN_NAME:
  90       g_free (self-&gt;priv-&gt;name);
  91       self-&gt;priv-&gt;name = g_value_dup_string (value);
  92       g_print ("maman: %s\n", self-&gt;priv-&gt;name);
  93       break;
  94
  95     case PROP_PAPA_NUMBER:
  96       self-&gt;priv-&gt;papa_number = g_value_get_uchar (value);
  97       g_print ("papa: %u\n", self-&gt;priv-&gt;papa_number);
  98       break;
  99
 100     default:
 101       /* We don't have any other property... */
 102       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
 103       break;
 104     }
 105 }
 106
 107 static void
 108 maman_bar_get_property (GObject    *object,
 109                         guint       property_id,
 110                         GValue     *value,
 111                         GParamSpec *pspec)
 112 {
 113   MamanBar *self = MAMAN_BAR (object);
 114
 115   switch (property_id)
 116     {
 117     case PROP_MAMAN_NAME:
 118       g_value_set_string (value, self-&gt;priv-&gt;name);
 119       break;
 120
 121     case PROP_PAPA_NUMBER:
 122       g_value_set_uchar (value, self-&gt;priv-&gt;papa_number);
 123       break;
 124
 125     default:
 126       /* We don't have any other property... */
 127       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
 128       break;
 129     }
 130 }
 131
 132 static void
 133 maman_bar_class_init (MamanBarClass *klass)
 134 {
 135   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 136   GParamSpec *pspec;
 137
 138   gobject_class-&gt;set_property = maman_bar_set_property;
 139   gobject_class-&gt;get_property = maman_bar_get_property;
 140
 141   pspec = g_param_spec_string ("maman-name",
 142                                "Maman construct prop",
 143                                "Set maman's name",
 144                                "no-name-set" /* default value */,
 145                                G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE);
 146   g_object_class_install_property (gobject_class,
 147                                    PROP_MAMAN_NAME,
 148                                    pspec);
 149
 150   pspec = g_param_spec_uchar ("papa-number",
 151                               "Number of current Papa",
 152                               "Set/Get papa's number",
 153                               0  /* minimum value */,
 154                               10 /* maximum value */,
 155                               2  /* default value */,
 156                               G_PARAM_READWRITE);
 157   g_object_class_install_property (gobject_class,
 158                                    PROP_PAPA_NUMBER,
 159                                    pspec);
 160 }
 161
 162 /************************************************/
 163 /* Use                                          */
 164 /************************************************/
 165
 166 GObject *bar;
 167 GValue val = { 0, };
 168
 169 bar = g_object_new (MAMAN_TYPE_SUBBAR, NULL);
 170
 171 g_value_init (&amp;val, G_TYPE_CHAR);
 172 g_value_set_char (&amp;val, 11);
 173
 174 g_object_set_property (G_OBJECT (bar), "papa-number", &amp;val);
 175
 176 g_value_unset (&amp;val);
 177 </pre>
 178 <p>
 179       The client code just above looks simple but a lot of things happen under the hood:
 180     </p>
 181 <p>
 182       <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
 183       with this name was registered in bar's class_init handler. If so, it calls
 184       <code class="function">object_set_property</code> which first walks the class hierarchy,
 185       from bottom, most derived type, to top, fundamental type to find the class
 186       which registered that property. It then tries to convert the user-provided GValue
 187       into a GValue whose type is that of the associated property.
 188     </p>
 189 <p>
 190       If the user provides a signed char GValue, as is shown
 191       here, and if the object's property was registered as an unsigned int,
 192       <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
 193       an unsigned int. Of course, the success of the transformation depends on the availability
 194       of the required transform function. In practice, there will almost always be a transformation
 195       <sup>[<a name="id600805" href="#ftn.id600805" class="footnote">4</a>]</sup>
 196       which matches and conversion will be carried out if needed.
 197     </p>
 198 <p>
 199       After transformation, the <span class="type"><a class="link" href="gobject-Generic-values.html#GValue" title="GValue">GValue</a></span> is validated by
 200       <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
 201       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
 202       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
 203       provided in class_init has a validation function which makes sure that the GValue
 204       contains a value which respects the minimum and maximum bounds of the
 205       <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
 206       respect these constraints (it is set to 11, while the maximum is 10). As such, the
 207       <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.
 208     </p>
 209 <p>
 210       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>
 211       would have proceeded with calling the object's set_property class method. Here, since our
 212       implementation of Foo did override this method, the code path would jump to
 213       <code class="function">foo_set_property</code> after having retrieved from the
 214       <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>
 215       <sup>[<a name="id600895" href="#ftn.id600895" class="footnote">5</a>]</sup>
 216       which had been stored by
 217       <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>.
 218     </p>
 219 <p>
 220       Once the property has been set by the object's set_property class method, the code path
 221       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
 222       <code class="function">g_object_notify_queue_thaw</code>. This function makes sure that
 223       the "notify" signal is emitted on the object's instance with the changed property as
 224       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>.
 225     </p>
 226 <p>
 227       <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
 228       property modifications through the "notify" signal. It is important to remember that
 229       even if properties are changed while property change notification is frozen, the "notify"
 230       signal will be emitted once for each of these changed properties as soon as the property
 231       change notification is thawed: no property change is lost for the "notify" signal. Signal
 232       can only be delayed by the notification freezing mechanism.
 233     </p>
 234 <p>
 235       It sounds like a tedious task to set up GValues every time when one wants to modify a property.
 236       In practice one will rarely do this. The functions <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>
 237       and <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-get-property" title="g_object_get_property ()">g_object_get_property</a></code>
 238       are meant to be used by language bindings. For application there is an easier way and
 239       that is described next.
 240     </p>
 241 <div class="sect2" title="Accessing multiple properties at once">
 242 <div class="titlepage"><div><div><h3 class="title">
 243 <a name="gobject-multi-properties"></a>Accessing multiple properties at once</h3></div></div></div>
 244 <p>
 245         It is interesting to note that the <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> and
 246         <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-set-valist" title="g_object_set_valist ()">g_object_set_valist</a></code> (vararg version) functions can be used to set
 247         multiple properties at once. The client code shown above can then be re-written as:
 248 </p>
 249 <pre class="programlisting">
 250 MamanBar *foo;
 251 foo = /* */;
 252 g_object_set (G_OBJECT (foo),
 253               "papa-number", 2,
 254               "maman-name", "test",
 255               NULL);
 256 </pre>
 257 <p>
 258         This saves us from managing the GValues that we were needing to handle when using
 259         <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>.
 260         The code above will trigger one notify signal emission for each property modified.
 261       </p>
 262 <p>
 263         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>
 264         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
 265         properties at once.
 266       </p>
 267 <p>
 268         These high level functions have one drawback - they don't provide a return result.
 269         One should pay attention to the argument types and ranges when using them.
 270         A known source of errors is to e.g. pass a gfloat instead of a gdouble and thus
 271         shifting all subsequent parameters by four bytes. Also forgetting the terminating
 272         NULL will lead to unexpected behaviour.
 273       </p>
 274 <p>
 275         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>,
 276         <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>
 277         work: they parse the user-provided variable number of parameters and invoke
 278         <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.
 279         Of course, the "notify" signal will be emitted for each property set.
 280       </p>
 281 </div>
 282 <div class="footnotes">
 283 <br><hr width="100" align="left">
 284 <div class="footnote"><p><sup>[<a name="ftn.id600805" href="#id600805" class="para">4</a>] </sup>Its behaviour might not be what you expect but it is up to you to actually avoid
 285           relying on these transformations.
 286         </p></div>
 287 <div class="footnote"><p><sup>[<a name="ftn.id600895" href="#id600895" class="para">5</a>] </sup>
 288           It should be noted that the param_id used here need only to uniquely identify each
 289           <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
 290           used in the set and get methods actually works. Of course, this locally-unique
 291           integer is purely an optimization: it would have been possible to use a set of
 292           <span class="emphasis"><em>if (strcmp (a, b) == 0) {} else if (strcmp (a, b) == 0) {}</em></span> statements.
 293         </p></div>
 294 </div>
 295 </div>
 296 <div class="footer">
 297 <hr>
 298           Generated by GTK-Doc V1.13</div>
 299 </body>
 300 </html>