RubyGems - gio2 - Versions diffs - 0.90.3-x86-mingw32 - Mend

gio2 0.90.3-x86-mingw32

Files changed (856) hide show

data/vendor/local/share/gtk-doc/html/gobject/ch01s02.html ADDED

@@ -0,0 +1,136 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Exporting a C API</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="home" href="index.html" title="GObject Reference Manual">
+<link rel="up" href="chapter-intro.html" title="Background">
+<link rel="prev" href="chapter-intro.html" title="Background">
+<link rel="next" href="chapter-gtype.html" title="The GLib Dynamic Type System">
+<meta name="generator" content="GTK-Doc V1.15.1 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
+<td><a accesskey="p" href="chapter-intro.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="chapter-intro.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">GObject Reference Manual</th>
+<td><a accesskey="n" href="chapter-gtype.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="id353634"></a>Exporting a C API</h2></div></div></div>
+<p>
+      C APIs are defined by a set of functions and global variables which are usually exported from a
+      binary. C functions have an arbitrary number of arguments and one return value. Each function is thus
+      uniquely identified by the function name and the set of C types which describe the function arguments
+      and return value. The global variables exported by the API are similarly identified by their name and
+      their type.
+    </p>
+<p>
+      A C API is thus merely defined by a set of names to which a set of types are associated. If you know the
+      function calling convention and the mapping of the C types to the machine types used by the platform you
+      are on, you can resolve the name of each function to find where the code associated to this function
+      is located in memory, and then construct a valid argument list for the function. Finally, all you have to
+      do is trigger a call to the target C function with the argument list.
+    </p>
+<p>
+      For the sake of discussion, here is a sample C function and the associated 32 bit x86
+      assembly code generated by GCC on my Linux box:
+</p>
+<pre class="programlisting">
+static void function_foo (int foo)
+{}
+int main (int argc, char *argv[])
+{
+        function_foo (10);
+        return 0;
+}
+push   $0xa
+call   0x80482f4 &lt;function_foo&gt;
+</pre>
+<p>
+      The assembly code shown above is pretty straightforward: the first instruction pushes
+      the hexadecimal value 0xa (decimal value 10) as a 32-bit integer on the stack and calls
+      <code class="function">function_foo</code>. As you can see, C function calls are implemented by
+      gcc by native function calls (this is probably the fastest implementation possible).
+    </p>
+<p>
+      Now, let's say we want to call the C function <code class="function">function_foo</code> from
+      a Python program. To do this, the Python interpreter needs to:
+      </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>Find where the function is located. This probably means finding the binary generated by the C compiler
+        which exports this function.</p></li>
+<li class="listitem"><p>Load the code of the function in executable memory.</p></li>
+<li class="listitem"><p>Convert the Python parameters to C-compatible parameters before calling
+        the function.</p></li>
+<li class="listitem"><p>Call the function with the right calling convention.</p></li>
+<li class="listitem"><p>Convert the return values of the C function to Python-compatible
+        variables to return them to the Python code.</p></li>
+</ul></div>
+<p>
+    </p>
+<p>
+      The process described above is pretty complex and there are a lot of ways to make it entirely automatic
+      and transparent to C and Python programmers:
+      </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>The first solution is to write by hand a lot of glue code, once for each function exported or imported,
+        which does the Python-to-C parameter conversion and the C-to-Python return value conversion. This glue code is then
+        linked with the interpreter which allows Python programs to call Python functions which delegate work to
+        C functions.</p></li>
+<li class="listitem"><p>Another, nicer solution is to automatically generate the glue code, once for each function exported or
+        imported, with a special compiler which
+        reads the original function signature.</p></li>
+<li class="listitem"><p>The solution used by GLib is to use the GType library which holds at runtime a description of
+        all the objects manipulated by the programmer. This so-called <span class="emphasis"><em>dynamic type</em></span>
+        <sup>[<a name="id353740" href="#ftn.id353740" class="footnote">1</a>]</sup>
+        library is then used by special generic glue code to automatically convert function parameters and
+        function calling conventions between different runtime domains.</p></li>
+</ul></div>
+<p>
+      The greatest advantage of the solution implemented by GType is that the glue code sitting at the runtime domain
+      boundaries is written once: the figure below states this more clearly.
+      </p>
+<div class="figure">
+<a name="id353758"></a><p class="title"><b>Figure 1. </b></p>
+<div class="figure-contents"><div class="mediaobject" align="center"><img src="glue.png" align="middle"></div></div>
+</div>
+<p><br class="figure-break">
+      Currently, there exist at least Python and Perl generic glue code which makes it possible to use
+      C objects written with GType directly in Python or Perl, with a minimum amount of work: there
+      is no need to generate huge amounts of glue code either automatically or by hand.
+    </p>
+<p>
+      Although that goal was arguably laudable, its pursuit has had a major influence on
+      the whole GType/GObject library. C programmers are likely to be puzzled at the complexity
+      of the features exposed in the following chapters if they forget that the GType/GObject library
+      was not only designed to offer OO-like features to C programmers but also transparent
+      cross-language interoperability.
+    </p>
+<div class="footnotes">
+<br><hr width="100" align="left">
+<div class="footnote"><p><sup>[<a name="ftn.id353740" href="#id353740" class="para">1</a>] </sup>
+            There are numerous different implementations of dynamic type systems: all C++
+            compilers have one, Java and .NET have one too. A dynamic type system allows you
+            to get information about every instantiated object at runtime. It can be implemented
+            by a process-specific database: every new object created registers the characteristics
+            of its associated type in the type system. It can also be implemented by introspection
+            interfaces. The common point between all these different type systems and implementations
+            is that they all allow you to query for object metadata at runtime.
+          </p></div>
+</div>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.15.1</div>
+</body>
+</html>

data/vendor/local/share/gtk-doc/html/gobject/ch06s03.html ADDED

@@ -0,0 +1,113 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Interface definition prerequisites</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="home" href="index.html" title="GObject Reference Manual">
+<link rel="up" href="howto-interface.html" title="How to define and implement interfaces">
+<link rel="prev" href="howto-interface-implement.html" title="How To define implement an Interface?">
+<link rel="next" href="howto-interface-properties.html" title="Interface Properties">
+<meta name="generator" content="GTK-Doc V1.15.1 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
+<td><a accesskey="p" href="howto-interface-implement.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="howto-interface.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">GObject Reference Manual</th>
+<td><a accesskey="n" href="howto-interface-properties.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="id471594"></a>Interface definition prerequisites</h2></div></div></div>
+<p>
+      To specify that an interface requires the presence of other interfaces
+      when implemented, GObject introduces the concept of
+      <span class="emphasis"><em>prerequisites</em></span>: it is possible to associate
+      a list of prerequisite interfaces to an interface. For example, if
+      object A wishes to implement interface I1, and if interface I1 has a
+      prerequisite on interface I2, A has to implement both I1 and I2.
+    </p>
+<p>
+      The mechanism described above is, in practice, very similar to
+      Java's interface I1 extends interface I2. The example below shows
+      the GObject equivalent:
+</p>
+<pre class="programlisting">
+  /* inside the GType function of the MamanIbar interface */
+  type = g_type_register_static (G_TYPE_INTERFACE, "MamanIbar", &amp;info, 0);
+  /* Make the MamanIbar interface require MamanIbaz interface. */
+  g_type_interface_add_prerequisite (type, MAMAN_TYPE_IBAZ);
+</pre>
+<p>
+      The code shown above adds the MamanIbaz interface to the list of
+      prerequisites of MamanIbar while the code below shows how an
+      implementation can implement both interfaces and register their
+      implementations:
+</p>
+<pre class="programlisting">
+static void
+maman_ibar_do_another_action (MamanIbar *ibar)
+{
+  MamanBar *self = MAMAN_BAR (ibar);
+  g_print ("Bar implementation of IBar interface Another Action: 0x%x.\n",
+           self-&gt;instance_member);
+}
+static void
+maman_ibar_interface_init (MamanIbarInterface *iface)
+{
+  iface-&gt;do_another_action = maman_ibar_do_another_action;
+}
+static void
+maman_ibaz_do_action (MamanIbaz *ibaz)
+{
+  MamanBar *self = MAMAN_BAR (ibaz);
+  g_print ("Bar implementation of IBaz interface Action: 0x%x.\n",
+           self-&gt;instance_member);
+}
+static void
+maman_ibaz_interface_init (MamanIbazInterface *iface)
+{
+  iface-&gt;do_action = maman_ibaz_do_action;
+}
+static void
+maman_bar_class_init (MamanBarClass *klass)
+{
+}
+static void
+maman_bar_init (MamanBar *self)
+{
+  self-&gt;instance_member = 0x666;
+}
+G_DEFINE_TYPE_WITH_CODE (MamanBar, maman_bar, G_TYPE_OBJECT,
+                         G_IMPLEMENT_INTERFACE (MAMAN_TYPE_IBAZ,
+                                                maman_ibaz_interface_init)
+                         G_IMPLEMENT_INTERFACE (MAMAN_TYPE_IBAR,
+                                                maman_ibar_interface_init));
+</pre>
+<p>
+      It is very important to notice that the order in which interface
+      implementations are added to the main object is not random:
+      <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-add-interface-static" title="g_type_add_interface_static ()">g_type_add_interface_static</a></code>,
+      which is called by <code class="function">G_IMPLEMENT_INTERFACE</code>, must be
+      invoked first on the interfaces which have no prerequisites and then on
+      the others.
+    </p>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.15.1</div>
+</body>
+</html>

data/vendor/local/share/gtk-doc/html/gobject/chapter-gobject.html ADDED

@@ -0,0 +1,293 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>The GObject base class</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="home" href="index.html" title="GObject Reference Manual">
+<link rel="up" href="pt01.html" title="Part I. Concepts">
+<link rel="prev" href="gtype-non-instantiable-classed.html" title="Non-instantiable classed types: interfaces">
+<link rel="next" href="gobject-memory.html" title="Object memory management">
+<meta name="generator" content="GTK-Doc V1.15.1 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
+<td><a accesskey="p" href="gtype-non-instantiable-classed.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="pt01.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">GObject Reference Manual</th>
+<td><a accesskey="n" href="gobject-memory.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="chapter">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="chapter-gobject"></a>The GObject base class</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="sect1"><a href="chapter-gobject.html#gobject-instantiation">Object instantiation</a></span></dt>
+<dt><span class="sect1"><a href="gobject-memory.html">Object memory management</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="gobject-memory.html#gobject-memory-refcount">Reference count</a></span></dt>
+<dt><span class="sect2"><a href="gobject-memory.html#gobject-memory-weakref">Weak References</a></span></dt>
+<dt><span class="sect2"><a href="gobject-memory.html#gobject-memory-cycles">Reference counts and cycles</a></span></dt>
+</dl></dd>
+<dt><span class="sect1"><a href="gobject-properties.html">Object properties</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="gobject-properties.html#gobject-multi-properties">Accessing multiple properties at once</a></span></dt></dl></dd>
+</dl></div>
+<p>
+    The two previous chapters discussed the details of GLib's Dynamic Type System
+    and its signal control system. The GObject library also contains an implementation
+    for a base fundamental type named <span class="type"><a class="link" href="gobject-The-Base-Object-Type.html#GObject">GObject</a></span>.
+  </p>
+<p>
+    <span class="type"><a class="link" href="gobject-The-Base-Object-Type.html#GObject">GObject</a></span> is a fundamental classed instantiable type. It implements:
+    </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>Memory management with reference counting</p></li>
+<li class="listitem"><p>Construction/Destruction of instances</p></li>
+<li class="listitem"><p>Generic per-object properties with set/get function pairs</p></li>
+<li class="listitem"><p>Easy use of signals</p></li>
+</ul></div>
+<p>
+    All the GNOME libraries which use the GLib type system (like GTK+ and GStreamer)
+    inherit from <span class="type"><a class="link" href="gobject-The-Base-Object-Type.html#GObject">GObject</a></span> which is why it is important to understand
+    the details of how it works.
+  </p>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="gobject-instantiation"></a>Object instantiation</h2></div></div></div>
+<p>
+      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>
+      family of functions can be used to instantiate any GType which inherits
+      from the GObject base type. All these functions make sure the class and
+      instance structures have been correctly initialized by GLib's type system
+      and then invoke at one point or another the constructor class method
+      which is used to:
+      </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>
+            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>,
+          </p></li>
+<li class="listitem"><p>
+            Initialize the object's instance with the construction properties.
+          </p></li>
+</ul></div>
+<p>
+     Although one can expect all class and instance members (except the fields
+     pointing to the parents) to be set to zero, some consider it good practice
+     to explicitly set them.
+    </p>
+<p>
+      Objects which inherit from GObject are allowed to override this
+      constructor class method: they should however chain to their parent
+      constructor method before doing so:
+</p>
+<pre class="programlisting">
+  GObject *(* constructor) (GType                  gtype,
+                            guint                  n_properties,
+                            GObjectConstructParam *properties);
+</pre>
+<p>
+    </p>
+<p>
+      The example below shows how <span class="type">MamanBar</span> overrides the parent's constructor:
+</p>
+<pre class="programlisting">
+#define MAMAN_TYPE_BAR                  (maman_bar_get_type ())
+#define MAMAN_BAR(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_BAR, MamanBar))
+#define MAMAN_IS_BAR(obj)               (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAR))
+#define MAMAN_BAR_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_TYPE_BAR, MamanBarClass))
+#define MAMAN_IS_BAR_CLASS(klass)       (G_TYPE_CHECK_CLASS_TYPE ((klass), MAMAN_TYPE_BAR))
+#define MAMAN_BAR_GET_CLASS(obj)        (G_TYPE_INSTANCE_GET_CLASS ((obj), MAMAN_TYPE_BAR, MamanBarClass))
+typedef struct _MamanBar        MamanBar;
+typedef struct _MamanBarClass   MamanBarClass;
+struct _MamanBar
+{
+  GObject parent_instance;
+  /* instance members */
+};
+struct _MamanBarClass
+{
+  GObjectClass parent_class;
+  /* class members */
+};
+/* will create maman_bar_get_type and set maman_bar_parent_class */
+G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT);
+static GObject *
+maman_bar_constructor (GType                  gtype,
+                       guint                  n_properties,
+                       GObjectConstructParam *properties)
+{
+  GObject *obj;
+  {
+    /* Always chain up to the parent constructor */
+    MamanBarClass *klass;
+    GObjectClass *parent_class;
+    parent_class = G_OBJECT_CLASS (maman_bar_parent_class);
+    obj = parent_class-&gt;constructor (gtype, n_properties, properties);
+  }
+  /* update the object state depending on constructor properties */
+  return obj;
+}
+static void
+maman_bar_class_init (MamanBarClass *klass)
+{
+  GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
+  gobject_class-&gt;constructor = maman_bar_constructor;
+}
+static void
+maman_bar_init (MamanBar *self)
+{
+  /* initialize the object */
+}
+</pre>
+<p>
+      If the user instantiates an object <span class="type">MamanBar</span> with:
+</p>
+<pre class="programlisting">
+MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL);
+</pre>
+<p>
+      If this is the first instantiation of such an object, the
+      <code class="function">maman_bar_class_init</code> function will be invoked
+      after any <code class="function">maman_bar_base_class_init</code> function.
+      This will make sure the class structure of this new object is
+      correctly initialized. Here, <code class="function">maman_bar_class_init</code>
+      is expected to override the object's class methods and setup the
+      class' own methods. In the example above, the constructor method is
+      the only overridden method: it is set to
+      <code class="function">maman_bar_constructor</code>.
+    </p>
+<p>
+      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
+      class structure, it invokes its constructor method to create an instance of the new
+      object. Since it has just been overridden by <code class="function">maman_bar_class_init</code>
+      to <code class="function">maman_bar_constructor</code>, the latter is called and, because it
+      was implemented correctly, it chains up to its parent's constructor. In
+      order to find the parent class and chain up to the parent class
+      constructor, we can use the <code class="literal">maman_bar_parent_class</code>
+      pointer that has been set up for us by the
+      <code class="literal">G_DEFINE_TYPE</code> macro.
+    </p>
+<p>
+      Finally, at one point or another, <code class="function">g_object_constructor</code> is invoked
+      by the last constructor in the chain. This function allocates the object's instance' buffer
+      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>
+      which means that the instance_init function is invoked at this point if one
+      was registered. After instance_init returns, the object is fully initialized and should be
+      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>
+      returns, <code class="function">g_object_constructor</code> sets the construction properties
+      (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
+      to the user's constructor which is then allowed to do useful instance initialization...
+    </p>
+<p>
+      The process described above might seem a bit complicated, but it can be
+      summarized easily by the table below which lists the functions invoked
+      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>
+      and their order of invocation:
+    </p>
+<p>
+      </p>
+<div class="table">
+<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>
+<div class="table-contents"><table summary="g_object_new" border="1">
+<colgroup>
+<col align="left">
+<col align="left">
+<col align="left">
+</colgroup>
+<thead><tr>
+<th align="left">Invocation time</th>
+<th align="left">Function Invoked</th>
+<th align="left">Function's parameters</th>
+<th>Remark</th>
+</tr></thead>
+<tbody>
+<tr>
+<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>
+<td align="left">target type's base_init function</td>
+<td align="left">On the inheritance tree of classes from fundamental type to target type.
+                base_init is invoked once for each class structure.</td>
+<td>
+                I have no real idea on how this can be used. If you have a good real-life
+                example of how a class' base_init can be used, please, let me know.
+              </td>
+</tr>
+<tr>
+<td align="left">target type's class_init function</td>
+<td align="left">On target type's class structure</td>
+<td>
+                Here, you should make sure to initialize or override class methods (that is,
+                assign to each class' method its function pointer) and create the signals and
+                the properties associated to your object.
+              </td>
+</tr>
+<tr>
+<td align="left">interface' base_init function</td>
+<td align="left">On interface' vtable</td>
+<td> </td>
+</tr>
+<tr>
+<td align="left">interface' interface_init function</td>
+<td align="left">On interface' vtable</td>
+<td> </td>
+</tr>
+<tr>
+<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>
+<td align="left">target type's class constructor method: GObjectClass-&gt;constructor</td>
+<td align="left">On object's instance</td>
+<td>
+                If you need to complete the object initialization after all the construction properties
+                are set, override the constructor method and make sure to chain up to the object's
+                parent class before doing your own initialization.
+                In doubt, do not override the constructor method.
+              </td>
+</tr>
+<tr>
+<td align="left">type's instance_init function</td>
+<td align="left">On the inheritance tree of classes from fundamental type to target type.
+              the instance_init provided for each type is invoked once for each instance
+              structure.</td>
+<td>
+                Provide an instance_init function to initialize your object before its construction
+                properties are set. This is the preferred way to initialize a GObject instance.
+                This function is equivalent to C++ constructors.
+              </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<p><br class="table-break">
+    </p>
+<p>
+      Readers should feel concerned about one little twist in the order in
+      which functions are invoked: while, technically, the class' constructor
+      method is called <span class="emphasis"><em>before</em></span> the GType's instance_init
+      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
+      <code class="function">g_object_constructor</code> which is the top-level class
+      constructor method and to which users are expected to chain to), the
+      user's code which runs in a user-provided constructor will always
+      run <span class="emphasis"><em>after</em></span> GType's instance_init function since the
+      user-provided constructor <span class="emphasis"><em>must</em></span> (you've been warned)
+      chain up <span class="emphasis"><em>before</em></span> doing anything useful.
+    </p>
+</div>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.15.1</div>
+</body>
+</html>