docs/reference/gobject/html/howto-gobject-construction.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 Construction</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GObject Reference Manual">
   8 <link rel="up" href="howto-gobject.html" title="How to define and implement a new GObject">
   9 <link rel="prev" href="howto-gobject-code.html" title="Boilerplate code">
  10 <link rel="next" href="howto-gobject-destruction.html" title="Object Destruction">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
  16 <td><a accesskey="p" href="howto-gobject-code.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="howto-gobject.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  18 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  19 <th width="100%" align="center">GObject Reference Manual</th>
  20 <td><a accesskey="n" href="howto-gobject-destruction.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="sect1">
  23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  24 <a name="howto-gobject-construction"></a>Object Construction</h2></div></div></div>
  25 <p>
  26       People often get confused when trying to construct their GObjects because of the
  27       sheer number of different ways to hook into the objects's construction process: it is
  28       difficult to figure which is the <span class="emphasis"><em>correct</em></span>, recommended way.
  29     </p>
  30 <p>
  31       <a class="xref" href="chapter-gobject.html#gobject-construction-table" title="Table 4. g_object_new">Table 4, “g_object_new”</a> shows what user-provided functions
  32       are invoked during object instantiation and in which order they are invoked.
  33       A user looking for the equivalent of the simple C++ constructor function should use
  34       the instance_init method. It will be invoked after all the parent's instance_init
  35       functions have been invoked. It cannot take arbitrary construction parameters
  36       (as in C++) but if your object needs arbitrary parameters to complete initialization,
  37       you can use construction properties.
  38     </p>
  39 <p>
  40       Construction properties will be set only after all instance_init functions have run.
  41       No object reference will be returned to the client of <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>
  42       until all the construction properties have been set.
  43     </p>
  44 <p>
  45       As such, I would recommend writing the following code first:
  46 </p>
  47 <pre class="programlisting">
  48 static void
  49 maman_bar_init (MamanBar *self)
  50 {
  51   self-&gt;priv = MAMAN_BAR_GET_PRIVATE (self);
  52
  53   /* initialize all public and private members to reasonable default values. */
  54
  55   /* If you need specific construction properties to complete initialization,
  56    * delay initialization completion until the property is set.
  57    */
  58 }
  59 </pre>
  60 <p>
  61     </p>
  62 <p>
  63       Now, if you need special construction properties, install the properties in the class_init function,
  64       override the set and get methods and implement the get and set methods as described in
  65       <a class="xref" href="gobject-properties.html" title="Object properties">the section called “Object properties”</a>. Make sure that these properties use a construct only
  66       <a class="link" href="gobject-GParamSpec.html#GParamSpec" title="struct GParamSpec"><span class="type">GParamSpec</span></a> by setting the param spec's flag field to G_PARAM_CONSTRUCT_ONLY: this helps
  67       GType ensure that these properties are not set again later by malicious user code.
  68 </p>
  69 <div class="informalexample">
  70   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
  71     <tbody>
  72       <tr>
  73         <td class="listing_lines" align="right"><pre>1
  74 2
  75 3
  76 4
  77 5
  78 6
  79 7
  80 8
  81 9
  82 10
  83 11
  84 12
  85 13
  86 14
  87 15
  88 16
  89 17
  90 18
  91 19
  92 20
  93 21
  94 22
  95 23
  96 24
  97 25
  98 26
  99 27
 100 28
 101 29</pre></td>
 102         <td class="listing_code"><pre class="programlisting"><span class="keyword">enum</span><span class="normal"> </span><span class="cbracket">{</span>
 103 <span class="normal">  PROP_0</span><span class="symbol">,</span>
 104
 105 <span class="normal">  PROP_MAMAN</span><span class="symbol">,</span>
 106
 107 <span class="normal">  N_PROPERTIES</span>
 108 <span class="cbracket">}</span><span class="symbol">;</span>
 109
 110 <span class="keyword">static</span><span class="normal"> </span><span class="usertype">GParamSpec</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">obj_properties</span><span class="symbol">[</span><span class="normal">N_PROPERTIES</span><span class="symbol">]</span><span class="normal"> </span><span class="symbol">=</span><span class="normal"> </span><span class="cbracket">{</span><span class="normal"> <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">,</span><span class="normal"> </span><span class="cbracket">}</span><span class="symbol">;</span>
 111
 112 <span class="keyword">static</span><span class="normal"> </span><span class="type">void</span>
 113 <span class="function">bar_class_init</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">MamanBarClass</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">klass</span><span class="symbol">)</span>
 114 <span class="cbracket">{</span>
 115 <span class="normal">  </span><span class="usertype">GObjectClass</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">gobject_class </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="gobject-The-Base-Object-Type.html#G-OBJECT-CLASS:CAPS">G_OBJECT_CLASS</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">klass</span><span class="symbol">);</span>
 116
 117 <span class="normal">  gobject_class</span><span class="symbol">-&gt;</span><span class="normal">set_property </span><span class="symbol">=</span><span class="normal"> bar_set_property</span><span class="symbol">;</span>
 118 <span class="normal">  gobject_class</span><span class="symbol">-&gt;</span><span class="normal">get_property </span><span class="symbol">=</span><span class="normal"> bar_get_property</span><span class="symbol">;</span>
 119
 120 <span class="normal">  obj_properties</span><span class="symbol">[</span><span class="normal">PROP_MAMAN</span><span class="symbol">]</span><span class="normal"> </span><span class="symbol">=</span>
 121 <span class="normal">    </span><span class="function"><a href="gobject-Standard-Parameter-and-Value-Types.html#g-param-spec-string">g_param_spec_string</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"maman"</span><span class="symbol">,</span>
 122 <span class="normal">                         </span><span class="string">"Maman construct prop"</span><span class="symbol">,</span>
 123 <span class="normal">                         </span><span class="string">"Set maman's name"</span><span class="symbol">,</span>
 124 <span class="normal">                         </span><span class="string">"no-name-set"</span><span class="normal"> </span><span class="comment">/* default value */</span><span class="symbol">,</span>
 125 <span class="normal">                         <a href="gobject-GParamSpec.html#G-PARAM-CONSTRUCT-ONLY:CAPS">G_PARAM_CONSTRUCT_ONLY</a> </span><span class="symbol">|</span><span class="normal"> <a href="gobject-GParamSpec.html#G-PARAM-READWRITE:CAPS">G_PARAM_READWRITE</a></span><span class="symbol">);</span>
 126
 127 <span class="normal">  </span><span class="function"><a href="gobject-The-Base-Object-Type.html#g-object-class-install-properties">g_object_class_install_properties</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">gobject_class</span><span class="symbol">,</span>
 128 <span class="normal">                                     N_PROPERTIES</span><span class="symbol">,</span>
 129 <span class="normal">                                     obj_properties</span><span class="symbol">);</span>
 130 <span class="cbracket">}</span></pre></td>
 131       </tr>
 132     </tbody>
 133   </table>
 134 </div>
 135
 136 <p>
 137       If you need this, make sure you can build and run code similar to the code shown above. Make sure
 138       your construct properties can set correctly during construction, make sure you cannot set them
 139       afterwards and make sure that if your users do not call <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>
 140       with the required construction properties, these will be initialized with the default values.
 141     </p>
 142 <p>
 143       I consider good taste to halt program execution if a construction property is set its
 144       default value. This allows you to catch client code which does not give a reasonable
 145       value to the construction properties. Of course, you are free to disagree but you
 146       should have a good reason to do so.
 147     </p>
 148 <p>
 149       Some people sometimes need to construct their object but only after
 150       the construction properties have been set. This is possible through
 151       the use of the constructor class method as described in
 152       <a class="xref" href="chapter-gobject.html#gobject-instantiation" title="Object instantiation">the section called “Object instantiation”</a> or, more simply, using
 153       the constructed class method available since GLib 2.12.
 154     </p>
 155 </div>
 156 <div class="footer">
 157 <hr>
 158           Generated by GTK-Doc V1.18</div>
 159 </body>
 160 </html>