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: GObject Reference Manual</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.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.25.1 (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="5"><tr valign="middle">
  16 <td width="100%" align="left" class="shortcuts"></td>
  17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  18 <td><a accesskey="u" href="howto-gobject.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="howto-gobject-code.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="howto-gobject-destruction.html"><img src="right.png" width="16" height="16" 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 <code class="function">instance_init</code> method. It will be invoked after
  35       all the parents’ <code class="function">instance_init</code>
  36       functions have been invoked. It cannot take arbitrary construction parameters
  37       (as in C++) but if your object needs arbitrary parameters to complete initialization,
  38       you can use construction properties.
  39     </p>
  40 <p>
  41       Construction properties will be set only after all
  42       <code class="function">instance_init</code> functions have run.
  43       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>
  44       until all the construction properties have been set.
  45     </p>
  46 <p>
  47       It is important to note that object construction cannot <span class="emphasis"><em>ever</em></span>
  48       fail. If you require a fallible GObject construction, you can use the
  49       <a href="https://developer.gnome.org/gio/unstable/GInitable.html#GInitable-struct"><span class="type">GInitable</span></a> and
  50       <a href="https://developer.gnome.org/gio/unstable/GAsyncInitable.html#GAsyncInitable-struct"><span class="type">GAsyncInitable</span></a>
  51       interfaces provided by the GIO library.
  52     </p>
  53 <p>
  54       You should write the following code first:
  55 </p>
  56 <div class="informalexample">
  57   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
  58     <tbody>
  59       <tr>
  60         <td class="listing_lines" align="right"><pre>1
  61 2
  62 3
  63 4
  64 5
  65 6
  66 7
  67 8
  68 9
  69 10
  70 11
  71 12
  72 13
  73 14
  74 15</pre></td>
  75         <td class="listing_code"><pre class="programlisting"><span class="function"><a href="gobject-Type-Information.html#G-DEFINE-TYPE-WITH-PRIVATE:CAPS">G_DEFINE_TYPE_WITH_PRIVATE</a></span> <span class="gtkdoc opt">(</span>ViewerFile<span class="gtkdoc opt">,</span> viewer_file<span class="gtkdoc opt">,</span> G_TYPE_OBJECT<span class="gtkdoc opt">)</span>
  76
  77 <span class="gtkdoc kwb">static void</span>
  78 <span class="function">viewer_file_class_init</span> <span class="gtkdoc opt">(</span>ViewerFileClass <span class="gtkdoc opt">*</span>klass<span class="gtkdoc opt">)</span>
  79 <span class="gtkdoc opt">{</span>
  80 <span class="gtkdoc opt">}</span>
  81
  82 <span class="gtkdoc kwb">static void</span>
  83 <span class="function">viewer_file_init</span> <span class="gtkdoc opt">(</span>ViewerFile <span class="gtkdoc opt">*</span>self<span class="gtkdoc opt">)</span>
  84 <span class="gtkdoc opt">{</span>
  85   ViewerFilePrivate <span class="gtkdoc opt">*</span>priv <span class="gtkdoc opt">=</span> <span class="function">viewer_file_get_instance_private</span> <span class="gtkdoc opt">(</span>self<span class="gtkdoc opt">);</span>
  86
  87   <span class="comment">/* initialize all public and private members to reasonable default values.</span>
  88 <span class="comment">   * They are all automatically initialized to 0 to begin with. */</span>
  89 <span class="gtkdoc opt">}</span></pre></td>
  90       </tr>
  91     </tbody>
  92   </table>
  93 </div>
  94
  95 <p>
  96     </p>
  97 <p>
  98       If you need special construction properties (with
  99       <a class="link" href="gobject-GParamSpec.html#G-PARAM-CONSTRUCT-ONLY:CAPS"><code class="function">G_PARAM_CONSTRUCT_ONLY</code></a>
 100       set), install the properties in
 101       the <code class="function">class_init()</code> function, override the <code class="function">set_property()</code>
 102       and <code class="function">get_property()</code> methods of the GObject class,
 103       and implement them as described by <a class="xref" href="gobject-properties.html" title="Object properties">the section called “Object properties”</a>.
 104     </p>
 105 <p>
 106       Property IDs must start from 1, as 0 is reserved for internal use by
 107       GObject.
 108 </p>
 109 <div class="informalexample">
 110   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 111     <tbody>
 112       <tr>
 113         <td class="listing_lines" align="right"><pre>1
 114 2
 115 3
 116 4
 117 5
 118 6
 119 7
 120 8
 121 9
 122 10
 123 11
 124 12
 125 13
 126 14
 127 15
 128 16
 129 17
 130 18
 131 19
 132 20
 133 21
 134 22
 135 23
 136 24
 137 25
 138 26
 139 27
 140 28
 141 29
 142 30
 143 31
 144 32
 145 33
 146 34
 147 35
 148 36
 149 37</pre></td>
 150         <td class="listing_code"><pre class="programlisting"><span class="gtkdoc kwb">enum</span>
 151 <span class="gtkdoc opt">{</span>
 152   PROP_FILENAME <span class="gtkdoc opt">=</span> <span class="number">1</span><span class="gtkdoc opt">,</span>
 153   PROP_ZOOM_LEVEL<span class="gtkdoc opt">,</span>
 154   N_PROPERTIES
 155 <span class="gtkdoc opt">};</span>
 156
 157 <span class="gtkdoc kwb">static</span> GParamSpec <span class="gtkdoc opt">*</span>obj_properties<span class="gtkdoc opt">[</span>N_PROPERTIES<span class="gtkdoc opt">] = {</span> NULL<span class="gtkdoc opt">, };</span>
 158
 159 <span class="gtkdoc kwb">static void</span>
 160 <span class="function">viewer_file_class_init</span> <span class="gtkdoc opt">(</span>ViewerFileClass <span class="gtkdoc opt">*</span>klass<span class="gtkdoc opt">)</span>
 161 <span class="gtkdoc opt">{</span>
 162   GObjectClass <span class="gtkdoc opt">*</span>object_class <span class="gtkdoc opt">=</span> <span class="function"><a href="gobject-The-Base-Object-Type.html#G-OBJECT-CLASS:CAPS">G_OBJECT_CLASS</a></span> <span class="gtkdoc opt">(</span>klass<span class="gtkdoc opt">);</span>
 163
 164   object_class<span class="gtkdoc opt">-&gt;</span>set_property <span class="gtkdoc opt">=</span> viewer_file_set_property<span class="gtkdoc opt">;</span>
 165   object_class<span class="gtkdoc opt">-&gt;</span>get_property <span class="gtkdoc opt">=</span> viewer_file_get_property<span class="gtkdoc opt">;</span>
 166
 167   obj_properties<span class="gtkdoc opt">[</span>PROP_FILENAME<span class="gtkdoc opt">] =</span>
 168     <span class="function"><a href="gobject-Standard-Parameter-and-Value-Types.html#g-param-spec-string">g_param_spec_string</a></span> <span class="gtkdoc opt">(</span><span class="string">&quot;filename&quot;</span><span class="gtkdoc opt">,</span>
 169                          <span class="string">&quot;Filename&quot;</span><span class="gtkdoc opt">,</span>
 170                          <span class="string">&quot;Name of the file to load and display from.&quot;</span><span class="gtkdoc opt">,</span>
 171                          NULL  <span class="comment">/* default value */</span><span class="gtkdoc opt">,</span>
 172                          G_PARAM_CONSTRUCT_ONLY <span class="gtkdoc opt">|</span> G_PARAM_READWRITE<span class="gtkdoc opt">));</span>
 173
 174   obj_properties<span class="gtkdoc opt">[</span>PROP_ZOOM_LEVEL<span class="gtkdoc opt">] =</span>
 175     <span class="function"><a href="gobject-Standard-Parameter-and-Value-Types.html#g-param-spec-uint">g_param_spec_uint</a></span> <span class="gtkdoc opt">(</span><span class="string">&quot;zoom-level&quot;</span><span class="gtkdoc opt">,</span>
 176                        <span class="string">&quot;Zoom level&quot;</span><span class="gtkdoc opt">,</span>
 177                        <span class="string">&quot;Zoom level to view the file at.&quot;</span><span class="gtkdoc opt">,</span>
 178                        <span class="number">0</span>  <span class="comment">/* minimum value */</span><span class="gtkdoc opt">,</span>
 179                        <span class="number">10</span> <span class="comment">/* maximum value */</span><span class="gtkdoc opt">,</span>
 180                        <span class="number">2</span>  <span class="comment">/* default value */</span><span class="gtkdoc opt">,</span>
 181                        G_PARAM_READWRITE<span class="gtkdoc opt">));</span>
 182
 183   <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="gtkdoc opt">(</span>object_class<span class="gtkdoc opt">,</span>
 184                                      N_PROPERTIES<span class="gtkdoc opt">,</span>
 185                                      obj_properties<span class="gtkdoc opt">);</span>
 186 <span class="gtkdoc opt">}</span></pre></td>
 187       </tr>
 188     </tbody>
 189   </table>
 190 </div>
 191
 192 <p>
 193       If you need this, make sure you can build and run code similar to the
 194       code shown above. Also, make sure your construct properties can be set
 195       without side effects during construction.
 196     </p>
 197 <p>
 198       Some people sometimes need to complete the initialization of a instance
 199       of a type only after the properties passed to the constructors have been
 200       set. This is possible through the use of the <code class="function">constructor()</code>
 201       class method as described in <a class="xref" href="chapter-gobject.html#gobject-instantiation" title="Object instantiation">the section called “Object instantiation”</a> or,
 202       more simply, using the <code class="function">constructed()</code> class method.
 203       Note that the <code class="function">constructed()</code>
 204       virtual function will only be invoked after the properties marked as
 205       <code class="function">G_PARAM_CONSTRUCT_ONLY</code> or
 206       <code class="function">G_PARAM_CONSTRUCT</code> have been consumed, but
 207       before the regular properties passed to <code class="function">g_object_new()</code>
 208       have been set.
 209     </p>
 210 </div>
 211 <div class="footer">
 212 <hr>Generated by GTK-Doc V1.25.1</div>
 213 </body>
 214 </html>