docs/reference/gobject/html/chapter-gobject.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>The GObject base class</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="pt01.html" title="Part I. Concepts">
   9 <link rel="prev" href="gtype-non-instantiable-classed.html" title="Non-instantiable classed types: interfaces">
  10 <link rel="next" href="gobject-memory.html" title="Object memory management">
  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="gtype-non-instantiable-classed.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="pt01.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="gobject-memory.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="chapter">
  23 <div class="titlepage"><div><div><h2 class="title">
  24 <a name="chapter-gobject"></a>The GObject base class</h2></div></div></div>
  25 <div class="toc"><dl>
  26 <dt><span class="sect1"><a href="chapter-gobject.html#gobject-instantiation">Object instantiation</a></span></dt>
  27 <dt><span class="sect1"><a href="gobject-memory.html">Object memory management</a></span></dt>
  28 <dd><dl>
  29 <dt><span class="sect2"><a href="gobject-memory.html#gobject-memory-refcount">Reference count</a></span></dt>
  30 <dt><span class="sect2"><a href="gobject-memory.html#gobject-memory-weakref">Weak References</a></span></dt>
  31 <dt><span class="sect2"><a href="gobject-memory.html#gobject-memory-cycles">Reference counts and cycles</a></span></dt>
  32 </dl></dd>
  33 <dt><span class="sect1"><a href="gobject-properties.html">Object properties</a></span></dt>
  34 <dd><dl><dt><span class="sect2"><a href="gobject-properties.html#gobject-multi-properties">Accessing multiple properties at once</a></span></dt></dl></dd>
  35 </dl></div>
  36 <p>
  37     The two previous chapters discussed the details of GLib's Dynamic Type System
  38     and its signal control system. The GObject library also contains an implementation
  39     for a base fundamental type named <a class="link" href="gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a>.
  40   </p>
  41 <p>
  42     <a class="link" href="gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> is a fundamental classed instantiable type. It implements:
  43     </p>
  44 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
  45 <li class="listitem"><p>Memory management with reference counting</p></li>
  46 <li class="listitem"><p>Construction/Destruction of instances</p></li>
  47 <li class="listitem"><p>Generic per-object properties with set/get function pairs</p></li>
  48 <li class="listitem"><p>Easy use of signals</p></li>
  49 </ul></div>
  50 <p>
  51     All the GNOME libraries which use the GLib type system (like GTK+ and GStreamer)
  52     inherit from <a class="link" href="gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> which is why it is important to understand
  53     the details of how it works.
  54   </p>
  55 <div class="sect1">
  56 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  57 <a name="gobject-instantiation"></a>Object instantiation</h2></div></div></div>
  58 <p>
  59       The <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>
  60       family of functions can be used to instantiate any GType which inherits
  61       from the GObject base type. All these functions make sure the class and
  62       instance structures have been correctly initialized by GLib's type system
  63       and then invoke at one point or another the constructor class method
  64       which is used to:
  65       </p>
  66 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
  67 <li class="listitem"><p>
  68             Allocate and clear memory through <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-create-instance" title="g_type_create_instance ()">g_type_create_instance</a></code>,
  69           </p></li>
  70 <li class="listitem"><p>
  71             Initialize the object's instance with the construction properties.
  72           </p></li>
  73 </ul></div>
  74 <p>
  75      Although one can expect all class and instance members (except the fields
  76      pointing to the parents) to be set to zero, some consider it good practice
  77      to explicitly set them.
  78     </p>
  79 <p>
  80       Objects which inherit from GObject are allowed to override this
  81       constructor class method: they should however chain to their parent
  82       constructor method before doing so:
  83 </p>
  84 <pre class="programlisting">
  85   GObject *(* constructor) (GType                  gtype,
  86                             guint                  n_properties,
  87                             GObjectConstructParam *properties);
  88 </pre>
  89 <p>
  90     </p>
  91 <p>
  92       The example below shows how <span class="type">MamanBar</span> overrides the parent's constructor:
  93 </p>
  94 <pre class="programlisting">
  95 #define MAMAN_TYPE_BAR                  (maman_bar_get_type ())
  96 #define MAMAN_BAR(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_BAR, MamanBar))
  97 #define MAMAN_IS_BAR(obj)               (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAR))
  98 #define MAMAN_BAR_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_TYPE_BAR, MamanBarClass))
  99 #define MAMAN_IS_BAR_CLASS(klass)       (G_TYPE_CHECK_CLASS_TYPE ((klass), MAMAN_TYPE_BAR))
 100 #define MAMAN_BAR_GET_CLASS(obj)        (G_TYPE_INSTANCE_GET_CLASS ((obj), MAMAN_TYPE_BAR, MamanBarClass))
 101
 102 typedef struct _MamanBar        MamanBar;
 103 typedef struct _MamanBarClass   MamanBarClass;
 104
 105 struct _MamanBar
 106 {
 107   GObject parent_instance;
 108
 109   /* instance members */
 110 };
 111
 112 struct _MamanBarClass
 113 {
 114   GObjectClass parent_class;
 115
 116   /* class members */
 117 };
 118
 119 /* will create maman_bar_get_type and set maman_bar_parent_class */
 120 G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT);
 121
 122 static GObject *
 123 maman_bar_constructor (GType                  gtype,
 124                        guint                  n_properties,
 125                        GObjectConstructParam *properties)
 126 {
 127   GObject *obj;
 128
 129   {
 130     /* Always chain up to the parent constructor */
 131     obj = G_OBJECT_CLASS (maman_bar_parent_class)-&gt;constructor (gtype, n_properties, properties);
 132   }
 133
 134   /* update the object state depending on constructor properties */
 135
 136   return obj;
 137 }
 138
 139 static void
 140 maman_bar_class_init (MamanBarClass *klass)
 141 {
 142   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 143
 144   gobject_class-&gt;constructor = maman_bar_constructor;
 145 }
 146
 147 static void
 148 maman_bar_init (MamanBar *self)
 149 {
 150   /* initialize the object */
 151 }
 152
 153 </pre>
 154 <p>
 155       If the user instantiates an object <span class="type">MamanBar</span> with:
 156 </p>
 157 <pre class="programlisting">
 158 MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL);
 159 </pre>
 160 <p>
 161       If this is the first instantiation of such an object, the
 162       <code class="function">maman_bar_class_init</code> function will be invoked
 163       after any <code class="function">maman_bar_base_class_init</code> function.
 164       This will make sure the class structure of this new object is
 165       correctly initialized. Here, <code class="function">maman_bar_class_init</code>
 166       is expected to override the object's class methods and setup the
 167       class' own methods. In the example above, the constructor method is
 168       the only overridden method: it is set to
 169       <code class="function">maman_bar_constructor</code>.
 170     </p>
 171 <p>
 172       Once <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> has obtained a reference to an initialized
 173       class structure, it invokes its constructor method to create an instance of the new
 174       object. Since it has just been overridden by <code class="function">maman_bar_class_init</code>
 175       to <code class="function">maman_bar_constructor</code>, the latter is called and, because it
 176       was implemented correctly, it chains up to its parent's constructor. In
 177       order to find the parent class and chain up to the parent class
 178       constructor, we can use the <code class="literal">maman_bar_parent_class</code>
 179       pointer that has been set up for us by the
 180       <code class="literal">G_DEFINE_TYPE</code> macro.
 181     </p>
 182 <p>
 183       Finally, at one point or another, <code class="function">g_object_constructor</code> is invoked
 184       by the last constructor in the chain. This function allocates the object's instance' buffer
 185       through <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-create-instance" title="g_type_create_instance ()">g_type_create_instance</a></code>
 186       which means that the instance_init function is invoked at this point if one
 187       was registered. After instance_init returns, the object is fully initialized and should be
 188       ready to answer any user-request. When <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-create-instance" title="g_type_create_instance ()">g_type_create_instance</a></code>
 189       returns, <code class="function">g_object_constructor</code> sets the construction properties
 190       (i.e. the properties which were given to <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>) and returns
 191       to the user's constructor which is then allowed to do useful instance initialization...
 192     </p>
 193 <p>
 194       The process described above might seem a bit complicated, but it can be
 195       summarized easily by the table below which lists the functions invoked
 196       by <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>
 197       and their order of invocation:
 198     </p>
 199 <p>
 200       </p>
 201 <div class="table">
 202 <a name="gobject-construction-table"></a><p class="title"><b>Table 4. <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></b></p>
 203 <div class="table-contents"><table summary="g_object_new" border="1">
 204 <colgroup>
 205 <col align="left">
 206 <col align="left">
 207 <col align="left">
 208 </colgroup>
 209 <thead><tr>
 210 <th align="left">Invocation time</th>
 211 <th align="left">Function Invoked</th>
 212 <th align="left">Function's parameters</th>
 213 <th>Remark</th>
 214 </tr></thead>
 215 <tbody>
 216 <tr>
 217 <td rowspan="4" align="left">First call to <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> for target type</td>
 218 <td align="left">target type's base_init function</td>
 219 <td align="left">On the inheritance tree of classes from fundamental type to target type.
 220                 base_init is invoked once for each class structure.</td>
 221 <td>
 222                 I have no real idea on how this can be used. If you have a good real-life
 223                 example of how a class' base_init can be used, please, let me know.
 224               </td>
 225 </tr>
 226 <tr>
 227 <td align="left">target type's class_init function</td>
 228 <td align="left">On target type's class structure</td>
 229 <td>
 230                 Here, you should make sure to initialize or override class methods (that is,
 231                 assign to each class' method its function pointer) and create the signals and
 232                 the properties associated to your object.
 233               </td>
 234 </tr>
 235 <tr>
 236 <td align="left">interface' base_init function</td>
 237 <td align="left">On interface' vtable</td>
 238 <td> </td>
 239 </tr>
 240 <tr>
 241 <td align="left">interface' interface_init function</td>
 242 <td align="left">On interface' vtable</td>
 243 <td> </td>
 244 </tr>
 245 <tr>
 246 <td rowspan="2" align="left">Each call to <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> for target type</td>
 247 <td align="left">target type's class constructor method: GObjectClass-&gt;constructor</td>
 248 <td align="left">On object's instance</td>
 249 <td>
 250                 If you need to complete the object initialization after all the construction properties
 251                 are set, override the constructor method and make sure to chain up to the object's
 252                 parent class before doing your own initialization.
 253                 In doubt, do not override the constructor method.
 254               </td>
 255 </tr>
 256 <tr>
 257 <td align="left">type's instance_init function</td>
 258 <td align="left">On the inheritance tree of classes from fundamental type to target type.
 259               the instance_init provided for each type is invoked once for each instance
 260               structure.</td>
 261 <td>
 262                 Provide an instance_init function to initialize your object before its construction
 263                 properties are set. This is the preferred way to initialize a GObject instance.
 264                 This function is equivalent to C++ constructors.
 265               </td>
 266 </tr>
 267 </tbody>
 268 </table></div>
 269 </div>
 270 <p><br class="table-break">
 271     </p>
 272 <p>
 273       Readers should feel concerned about one little twist in the order in
 274       which functions are invoked: while, technically, the class' constructor
 275       method is called <span class="emphasis"><em>before</em></span> the GType's instance_init
 276       function (since <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-create-instance" title="g_type_create_instance ()">g_type_create_instance</a></code> which calls instance_init is called by
 277       <code class="function">g_object_constructor</code> which is the top-level class
 278       constructor method and to which users are expected to chain to), the
 279       user's code which runs in a user-provided constructor will always
 280       run <span class="emphasis"><em>after</em></span> GType's instance_init function since the
 281       user-provided constructor <span class="emphasis"><em>must</em></span> (you've been warned)
 282       chain up <span class="emphasis"><em>before</em></span> doing anything useful.
 283     </p>
 284 </div>
 285 </div>
 286 <div class="footer">
 287 <hr>
 288           Generated by GTK-Doc V1.18</div>
 289 </body>
 290 </html>