docs/reference/gobject/html/howto-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>How to define and implement a new GObject</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="pt02.html" title="Part IV. Tutorial">
   9 <link rel="prev" href="pt02.html" title="Part IV. Tutorial">
  10 <link rel="next" href="howto-gobject-code.html" title="Boilerplate code">
  11 <meta name="generator" content="GTK-Doc V1.15.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="2"><tr valign="middle">
  16 <td><a accesskey="p" href="pt02.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="pt02.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-code.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="howto-gobject"></a>How to define and implement a new GObject</h2></div></div></div>
  25 <div class="toc"><dl>
  26 <dt><span class="sect1"><a href="howto-gobject.html#howto-gobject-header">Boilerplate header code</a></span></dt>
  27 <dt><span class="sect1"><a href="howto-gobject-code.html">Boilerplate code</a></span></dt>
  28 <dt><span class="sect1"><a href="howto-gobject-construction.html">Object Construction</a></span></dt>
  29 <dt><span class="sect1"><a href="howto-gobject-destruction.html">Object Destruction</a></span></dt>
  30 <dt><span class="sect1"><a href="howto-gobject-methods.html">Object methods</a></span></dt>
  31 <dd><dl>
  32 <dt><span class="sect2"><a href="howto-gobject-methods.html#id575935">Non-virtual public methods</a></span></dt>
  33 <dt><span class="sect2"><a href="howto-gobject-methods.html#id575960">Virtual public methods</a></span></dt>
  34 <dt><span class="sect2"><a href="howto-gobject-methods.html#id576044">Virtual private Methods</a></span></dt>
  35 </dl></dd>
  36 <dt><span class="sect1"><a href="howto-gobject-chainup.html">Chaining up</a></span></dt>
  37 </dl></div>
  38 <p>
  39     Clearly, this is one of the most common questions people ask: they just
  40     want to crank code and implement a subclass of a GObject. Sometimes because
  41     they want to create their own class hierarchy, sometimes because they want
  42     to subclass one of GTK+'s widget. This chapter will focus on the
  43     implementation of a subtype of GObject.
  44   </p>
  45 <div class="sect1">
  46 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  47 <a name="howto-gobject-header"></a>Boilerplate header code</h2></div></div></div>
  48 <p>
  49       The first step before writing the code for your GObject is to write the
  50       type's header which contains the needed type, function and macro
  51       definitions. Each of these elements is nothing but a convention which
  52       is followed not only by GTK+'s code but also by most users of GObject.
  53       If you feel the need not to obey the rules stated below, think about it
  54       twice:
  55       </p>
  56 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
  57 <li class="listitem"><p>If your users are a bit accustomed to GTK+ code or any
  58         GLib code, they will be a bit surprised and getting used to the
  59         conventions you decided upon will take time (money) and will make them
  60         grumpy (not a good thing)</p></li>
  61 <li class="listitem"><p>You must assess the fact that these conventions might
  62         have been designed by both smart and experienced people: maybe they
  63         were at least partly right. Try  to put your ego aside.</p></li>
  64 </ul></div>
  65 <p>
  66     </p>
  67 <p>
  68       Pick a name convention for your headers and source code and stick to it:
  69       </p>
  70 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
  71 <li class="listitem"><p>use a dash to separate the prefix from the typename:
  72         <code class="filename">maman-bar.h</code> and <code class="filename">maman-bar.c</code>
  73         (this is the convention used by Nautilus and most GNOME libraries).</p></li>
  74 <li class="listitem"><p>use an underscore to separate the prefix from the
  75         typename: <code class="filename">maman_bar.h</code> and
  76         <code class="filename">maman_bar.c</code>.</p></li>
  77 <li class="listitem"><p>Do not separate the prefix from the typename:
  78         <code class="filename">mamanbar.h</code> and <code class="filename">mamanbar.c</code>.
  79         (this is the convention used by GTK+)</p></li>
  80 </ul></div>
  81 <p>
  82       I personally like the first solution better: it makes reading file names
  83       easier for those with poor eyesight like me.
  84     </p>
  85 <p>
  86       When you need some private (internal) declarations in several
  87       (sub)classes, you can define them in a private header file which
  88       is often named by appending the <span class="emphasis"><em>private</em></span> keyword
  89       to the public header name. For example, one could use
  90       <code class="filename">maman-bar-private.h</code>,
  91       <code class="filename">maman_bar_private.h</code> or
  92       <code class="filename">mamanbarprivate.h</code>. Typically, such private header
  93       files are not installed.
  94     </p>
  95 <p>
  96       The basic conventions for any header which exposes a GType are described
  97       in <a class="xref" href="gtype-conventions.html" title="Conventions">the section called “Conventions”</a>. Most GObject-based code also
  98       obeys one of of the following conventions: pick one and stick to it.
  99       </p>
 100 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
 101 <li class="listitem">
 102 <p>
 103             If you want to declare a type named bar with prefix maman, name the type instance
 104             <code class="function">MamanBar</code> and its class <code class="function">MamanBarClass</code>
 105             (name is case-sensitive). It is customary to declare them with code similar to the
 106             following:
 107 </p>
 108 <pre class="programlisting">
 109 /*
 110  * Copyright/Licensing information.
 111  */
 112
 113 /* inclusion guard */
 114 #ifndef __MAMAN_BAR_H__
 115 #define __MAMAN_BAR_H__
 116
 117 #include &lt;glib-object.h&gt;
 118 /*
 119  * Potentially, include other headers on which this header depends.
 120  */
 121
 122 /*
 123  * Type macros.
 124  */
 125 #define MAMAN_TYPE_BAR                  (maman_bar_get_type ())
 126 #define MAMAN_BAR(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_BAR, MamanBar))
 127 #define MAMAN_IS_BAR(obj)               (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAR))
 128 #define MAMAN_BAR_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_TYPE_BAR, MamanBarClass))
 129 #define MAMAN_IS_BAR_CLASS(klass)       (G_TYPE_CHECK_CLASS_TYPE ((klass), MAMAN_TYPE_BAR))
 130 #define MAMAN_BAR_GET_CLASS(obj)        (G_TYPE_INSTANCE_GET_CLASS ((obj), MAMAN_TYPE_BAR, MamanBarClass))
 131
 132 typedef struct _MamanBar        MamanBar;
 133 typedef struct _MamanBarClass   MamanBarClass;
 134
 135 struct _MamanBar
 136 {
 137   GObject parent_instance;
 138
 139   /* instance members */
 140 };
 141
 142 struct _MamanBarClass
 143 {
 144   GObjectClass parent_class;
 145
 146   /* class members */
 147 };
 148
 149 /* used by MAMAN_TYPE_BAR */
 150 GType maman_bar_get_type (void);
 151
 152 /*
 153  * Method definitions.
 154  */
 155
 156 #endif /* __MAMAN_BAR_H__ */
 157 </pre>
 158 <p>
 159           </p>
 160 </li>
 161 <li class="listitem">
 162 <p>
 163             Most GTK+ types declare their private fields in the public header
 164             with a /* private */ comment, relying on their user's intelligence
 165             not to try to play with these fields. Fields not marked private
 166             are considered public by default. The /* protected */ comment
 167             (same semantics as those of C++) is also used, mainly in the GType
 168             library, in code written by Tim Janik.
 169 </p>
 170 <pre class="programlisting">
 171 struct _MamanBar
 172 {
 173   GObject parent_instance;
 174
 175   /*&lt; private &gt;*/
 176   int hsize;
 177 };
 178 </pre>
 179 <p>
 180           </p>
 181 </li>
 182 <li class="listitem">
 183 <p>
 184             All of Nautilus code and a lot of GNOME libraries use private
 185             indirection members, as described by Herb Sutter in his Pimpl
 186             articles(see <a class="ulink" href="http://www.gotw.ca/gotw/024.htm" target="_top">Compilation Firewalls</a>
 187             and <a class="ulink" href="http://www.gotw.ca/gotw/028.htm" target="_top">The Fast Pimpl Idiom</a>:
 188             he summarizes the different issues better than I will).
 189 </p>
 190 <pre class="programlisting">
 191 typedef struct _MamanBarPrivate MamanBarPrivate;
 192
 193 struct _MamanBar
 194 {
 195   GObject parent_instance;
 196
 197   /*&lt; private &gt;*/
 198   MamanBarPrivate *priv;
 199 };
 200 </pre>
 201 <p>
 202             </p>
 203 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 204 <h3 class="title">Note</h3>
 205 <p>Do not call this <code class="varname">private</code>, as
 206             that is a registered c++ keyword.</p>
 207 </div>
 208 <p>
 209
 210             The private structure is then defined in the .c file, using the
 211             g_type_class_add_private() function to notify the presence of
 212             a private memory area for each instance and it can either
 213             be retrieved using <code class="function">G_TYPE_INSTANCE_GET_PRIVATE()</code>
 214             each time is needed, or assigned to the <code class="literal">priv</code>
 215             member of the instance structure inside the object's
 216             <code class="function">init</code> function.
 217 </p>
 218 <pre class="programlisting">
 219 #define MAMAN_BAR_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), MAMAN_TYPE_BAR, MamanBarPrivate))
 220
 221 struct _MamanBarPrivate
 222 {
 223   int hsize;
 224 }
 225
 226 static void
 227 maman_bar_class_init (MamanBarClass *klass)
 228 {
 229   g_type_class_add_private (klass, sizeof (MamanBarPrivate));
 230 }
 231
 232 static void
 233 maman_bar_init (MamanBar *self)
 234 {
 235   MamanBarPrivate *priv;
 236
 237   self-&gt;priv = priv = MAMAN_BAR_GET_PRIVATE (self);
 238
 239   priv-&gt;hsize = 42;
 240 }
 241 </pre>
 242 <p>
 243           </p>
 244 </li>
 245 <li class="listitem"><p>
 246             You don't need to free or allocate the private structure, only the
 247             objects or pointers that it may contain. Another advantage of this
 248             to the previous version is that is lessens memory fragmentation,
 249             as the public and private parts of the instance memory are
 250             allocated at once.
 251           </p></li>
 252 </ul></div>
 253 <p>
 254     </p>
 255 <p>
 256       Finally, there are different header include conventions. Again, pick one
 257       and stick to it. I personally use indifferently any of the two, depending
 258       on the codebase I work on: the rule, as always, is consistency.
 259       </p>
 260 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
 261 <li class="listitem"><p>
 262             Some people add at the top of their headers a number of #include
 263             directives to pull in all the headers needed to compile client
 264             code. This allows client code to simply #include "maman-bar.h".
 265           </p></li>
 266 <li class="listitem"><p>
 267             Other do not #include anything and expect the client to #include
 268             themselves the headers they need before including your header. This
 269             speeds up compilation because it minimizes the amount of
 270             pre-processor work. This can be used in conjunction with the
 271             re-declaration of certain unused types in the client code to
 272             minimize compile-time dependencies and thus speed up compilation.
 273           </p></li>
 274 </ul></div>
 275 <p>
 276     </p>
 277 </div>
 278 </div>
 279 <div class="footer">
 280 <hr>
 281           Generated by GTK-Doc V1.15.1</div>
 282 </body>
 283 </html>