docs/reference/gobject/html/chapter-gtype.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 GLib Dynamic Type System</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="pt01.html" title="Part I. Concepts">
   9 <link rel="prev" href="ch01s02.html" title="Exporting a C API">
  10 <link rel="next" href="gtype-conventions.html" title="Conventions">
  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="ch01s02.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  47 <td><a accesskey="u" href="pt01.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="gtype-conventions.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  51 </tr></table>
  52 <div class="chapter" title="The GLib Dynamic Type System">
  53 <div class="titlepage"><div><div><h2 class="title">
  54 <a name="chapter-gtype"></a>The GLib Dynamic Type System</h2></div></div></div>
  55 <div class="toc"><dl>
  56 <dt><span class="sect1"><a href="chapter-gtype.html#gtype-copy">Copy functions</a></span></dt>
  57 <dt><span class="sect1"><a href="gtype-conventions.html">Conventions</a></span></dt>
  58 <dt><span class="sect1"><a href="gtype-non-instantiable.html">Non-instantiable non-classed fundamental types</a></span></dt>
  59 <dt><span class="sect1"><a href="gtype-instantiable-classed.html">Instantiable classed types: objects</a></span></dt>
  60 <dd><dl><dt><span class="sect2"><a href="gtype-instantiable-classed.html#gtype-instantiable-classed-init-done">Initialization and Destruction</a></span></dt></dl></dd>
  61 <dt><span class="sect1"><a href="gtype-non-instantiable-classed.html">Non-instantiable classed types: interfaces</a></span></dt>
  62 <dd><dl>
  63 <dt><span class="sect2"><a href="gtype-non-instantiable-classed.html#gtype-non-instantiable-classed-init">Interface Initialization</a></span></dt>
  64 <dt><span class="sect2"><a href="gtype-non-instantiable-classed.html#gtype-non-instantiable-classed-dest">Interface Destruction</a></span></dt>
  65 </dl></dd>
  66 </dl></div>
  67 <p>
  68         A type, as manipulated by the GLib type system, is much more generic than what
  69         is usually understood as an Object type. It is best explained by looking at the
  70         structure and the functions used to register new types in the type system.
  71         </p>
  72 <pre class="programlisting">
  73 typedef struct _GTypeInfo               GTypeInfo;
  74 struct _GTypeInfo
  75 {
  76   /* interface types, classed types, instantiated types */
  77   guint16                class_size;
  78
  79   GBaseInitFunc          base_init;
  80   GBaseFinalizeFunc      base_finalize;
  81
  82   /* classed types, instantiated types */
  83   GClassInitFunc         class_init;
  84   GClassFinalizeFunc     class_finalize;
  85   gconstpointer          class_data;
  86
  87   /* instantiated types */
  88   guint16                instance_size;
  89   guint16                n_preallocs;
  90   GInstanceInitFunc      instance_init;
  91
  92   /* value handling */
  93   const GTypeValueTable *value_table;
  94 };
  95 GType g_type_register_static (GType             parent_type,
  96                               const gchar      *type_name,
  97                               const GTypeInfo  *info,
  98                               GTypeFlags        flags);
  99 GType g_type_register_fundamental (GType                       type_id,
 100                                    const gchar                *type_name,
 101                                    const GTypeInfo            *info,
 102                                    const GTypeFundamentalInfo *finfo,
 103                                    GTypeFlags                  flags);
 104         </pre>
 105 <p>
 106       </p>
 107 <p>
 108         <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-register-static" title="g_type_register_static ()">g_type_register_static</a></code> and
 109         <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-register-fundamental" title="g_type_register_fundamental ()">g_type_register_fundamental</a></code>
 110         are the C functions, defined in
 111         <code class="filename">gtype.h</code> and implemented in <code class="filename">gtype.c</code>
 112         which you should use to register a new <span class="type"><a class="link" href="gobject-Type-Information.html#GType" title="GType">GType</a></span> in the program's type system.
 113         It is not likely you will ever need to use
 114         <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-register-fundamental" title="g_type_register_fundamental ()">g_type_register_fundamental</a></code> (you have to be Tim Janik
 115         to do that) but in case you want to, the last chapter explains how to create
 116         new fundamental types.
 117         <sup>[<a name="id587107" href="#ftn.id587107" class="footnote">2</a>]</sup>
 118       </p>
 119 <p>
 120         Fundamental types are top-level types which do not derive from any other type
 121         while other non-fundamental types derive from other types.
 122         Upon initialization by <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-init" title="g_type_init ()">g_type_init</a></code>, the type system not
 123         only initializes its internal data structures but it also registers a number of core
 124         types: some of these are fundamental types. Others are types derived from these
 125         fundamental types.
 126       </p>
 127 <p>
 128         Fundamental and non-fundamental types are defined by:
 129         </p>
 130 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
 131 <li class="listitem"><p>
 132             class size: the class_size field in <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeInfo" title="GTypeInfo">GTypeInfo</a></span>.
 133           </p></li>
 134 <li class="listitem"><p>
 135             class initialization functions (C++ constructor): the base_init and
 136             class_init fields in <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeInfo" title="GTypeInfo">GTypeInfo</a></span>.
 137           </p></li>
 138 <li class="listitem"><p>
 139             class destruction functions (C++ destructor): the base_finalize and
 140             class_finalize fields in <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeInfo" title="GTypeInfo">GTypeInfo</a></span>.
 141           </p></li>
 142 <li class="listitem"><p>
 143             instance size (C++ parameter to new): the instance_size field in
 144             <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeInfo" title="GTypeInfo">GTypeInfo</a></span>.
 145           </p></li>
 146 <li class="listitem"><p>
 147             instantiation policy (C++ type of new operator): the n_preallocs
 148             field in <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeInfo" title="GTypeInfo">GTypeInfo</a></span>.
 149           </p></li>
 150 <li class="listitem"><p>
 151             copy functions (C++ copy operators): the value_table field in
 152             <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeInfo" title="GTypeInfo">GTypeInfo</a></span>.
 153           </p></li>
 154 <li class="listitem"><p>
 155             type characteristic flags: <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeFlags" title="enum GTypeFlags">GTypeFlags</a></span>.
 156           </p></li>
 157 </ul></div>
 158 <p>
 159         Fundamental types are also defined by a set of <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeFundamentalFlags" title="enum GTypeFundamentalFlags">GTypeFundamentalFlags</a></span>
 160         which are stored in a <span class="type"><a class="link" href="gobject-Type-Information.html#GTypeFundamentalInfo" title="GTypeFundamentalInfo">GTypeFundamentalInfo</a></span>.
 161         Non-fundamental types are furthermore defined by the type of their parent which is
 162         passed as the parent_type parameter to <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-register-static" title="g_type_register_static ()">g_type_register_static</a></code>
 163         and <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-register-dynamic" title="g_type_register_dynamic ()">g_type_register_dynamic</a></code>.
 164       </p>
 165 <div class="sect1" title="Copy functions">
 166 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 167 <a name="gtype-copy"></a>Copy functions</h2></div></div></div>
 168 <p>
 169           The major common point between <span class="emphasis"><em>all</em></span> GLib types (fundamental and
 170           non-fundamental, classed and non-classed, instantiable and non-instantiable) is that
 171           they can all be manipulated through a single API to copy/assign them.
 172         </p>
 173 <p>
 174           The <span class="type"><a class="link" href="gobject-Generic-values.html#GValue" title="GValue">GValue</a></span> structure is used as an abstract container for all of these
 175           types. Its simplistic API (defined in <code class="filename">gobject/gvalue.h</code>) can be
 176           used to invoke the value_table functions registered
 177           during type registration: for example <code class="function"><a class="link" href="gobject-Generic-values.html#g-value-copy" title="g_value_copy ()">g_value_copy</a></code> copies the
 178           content of a <span class="type"><a class="link" href="gobject-Generic-values.html#GValue" title="GValue">GValue</a></span> to another <span class="type"><a class="link" href="gobject-Generic-values.html#GValue" title="GValue">GValue</a></span>. This is similar
 179           to a C++ assignment which invokes the C++ copy operator to modify the default
 180           bit-by-bit copy semantics of C++/C structures/classes.
 181         </p>
 182 <p>
 183           The following code shows how you can copy around a 64 bit integer, as well as a <span class="type"><a class="link" href="gobject-The-Base-Object-Type.html#GObject">GObject</a></span>
 184           instance pointer (sample code for this is located in the source tarball for this document in
 185           <code class="filename">sample/gtype/test.c</code>):
 186 </p>
 187 <pre class="programlisting">
 188 static void test_int (void)
 189 {
 190   GValue a_value = {0, };
 191   GValue b_value = {0, };
 192   guint64 a, b;
 193
 194   a = 0xdeadbeaf;
 195
 196   g_value_init (&amp;a_value, G_TYPE_UINT64);
 197   g_value_set_uint64 (&amp;a_value, a);
 198
 199   g_value_init (&amp;b_value, G_TYPE_UINT64);
 200   g_value_copy (&amp;a_value, &amp;b_value);
 201
 202   b = g_value_get_uint64 (&amp;b_value);
 203
 204   if (a == b) {
 205     g_print ("Yay !! 10 lines of code to copy around a uint64.\n");
 206   } else {
 207     g_print ("Are you sure this is not a Z80 ?\n");
 208   }
 209 }
 210
 211 static void test_object (void)
 212 {
 213   GObject *obj;
 214   GValue obj_vala = {0, };
 215   GValue obj_valb = {0, };
 216   obj = g_object_new (MAMAN_TYPE_BAR, NULL);
 217
 218   g_value_init (&amp;obj_vala, MAMAN_TYPE_BAR);
 219   g_value_set_object (&amp;obj_vala, obj);
 220
 221   g_value_init (&amp;obj_valb, G_TYPE_OBJECT);
 222
 223   /* g_value_copy's semantics for G_TYPE_OBJECT types is to copy the reference.
 224      This function thus calls g_object_ref.
 225      It is interesting to note that the assignment works here because
 226      MAMAN_TYPE_BAR is a G_TYPE_OBJECT.
 227    */
 228   g_value_copy (&amp;obj_vala, &amp;obj_valb);
 229
 230   g_object_unref (G_OBJECT (obj));
 231   g_object_unref (G_OBJECT (obj));
 232 }
 233 </pre>
 234 <p>
 235           The important point about the above code is that the exact semantics of the copy calls
 236           is undefined since they depend on the implementation of the copy function. Certain
 237           copy functions might decide to allocate a new chunk of memory and then to copy the
 238           data from the source to the destination. Others might want to simply increment
 239           the reference count of the instance and copy the reference to the new GValue.
 240         </p>
 241 <p>
 242           The value_table used to specify these assignment functions is defined in
 243           <code class="filename">gtype.h</code> and is thoroughly described in the
 244           API documentation provided with GObject (for once ;-) which is why we will
 245           not detail its exact semantics.
 246           </p>
 247 <pre class="programlisting">
 248 typedef struct _GTypeValueTable         GTypeValueTable;
 249 struct _GTypeValueTable
 250 {
 251   void     (*value_init)         (GValue       *value);
 252   void     (*value_free)         (GValue       *value);
 253   void     (*value_copy)         (const GValue *src_value,
 254                                   GValue       *dest_value);
 255   /* varargs functionality (optional) */
 256   gpointer (*value_peek_pointer) (const GValue *value);
 257   gchar            *collect_format;
 258   gchar*   (*collect_value)      (GValue       *value,
 259                                   guint         n_collect_values,
 260                                   GTypeCValue  *collect_values,
 261                                   guint                collect_flags);
 262   gchar            *lcopy_format;
 263   gchar*   (*lcopy_value)        (const GValue *value,
 264                                   guint         n_collect_values,
 265                                   GTypeCValue  *collect_values,
 266                                   guint                collect_flags);
 267 };
 268           </pre>
 269 <p>
 270           Interestingly, it is also very unlikely
 271           you will ever need to specify a value_table during type registration
 272           because these value_tables are inherited from the parent types for
 273           non-fundamental types which means that unless you want to write a
 274           fundamental type (not a great idea!), you will not need to provide
 275           a new value_table since you will inherit the value_table structure
 276           from your parent type.
 277         </p>
 278 </div>
 279 <div class="footnotes">
 280 <br><hr width="100" align="left">
 281 <div class="footnote"><p><sup>[<a name="ftn.id587107" href="#id587107" class="para">2</a>] </sup>
 282             Please note that there exists another registration function: the
 283             <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-register-dynamic" title="g_type_register_dynamic ()">g_type_register_dynamic</a></code>. We will not discuss this
 284             function here since its use is very similar to the <code class="function">_static</code>
 285             version.
 286           </p></div>
 287 </div>
 288 </div>
 289 <div class="footer">
 290 <hr>
 291           Generated by GTK-Doc V1.13</div>
 292 </body>
 293 </html>