← Back to branch summary

~ubuntu-branches/debian/squeeze/glib2.0/squeeze

« back to all changes in this revision

Viewing changes to docs/reference/gobject/html/howto-gobject.html

  • Committer: Bazaar Package Importer
  • Author(s): Sebastian Dröge
  • Date: 2009-06-27 09:56:08 UTC
  • mfrom: (1.4.6 upstream)
  • Revision ID: james.westby@ubuntu.com-20090627095608-pi9244lmozmr2cm6
Tags: 2.20.4-1
New upstream bugfix release.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/gobject/html/howto-gobject.html
3
3
<head>
4
4
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5
5
<title>How to define and implement a new GObject</title>
6
 
<meta name="generator" content="DocBook XSL Stylesheets V1.74.3">
 
6
<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
7
7
<link rel="home" href="index.html" title="GObject Reference Manual">
8
8
<link rel="up" href="pt02.html" title="Part IV. Tutorial">
9
9
<link rel="prev" href="pt02.html" title="Part IV. Tutorial">
47
47
<th width="100%" align="center">GObject Reference Manual</th>
48
48
<td><a accesskey="n" href="howto-gobject-code.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
49
49
</tr></table>
50
 
<div class="chapter" lang="en">
 
50
<div class="chapter" title="How to define and implement a new GObject">
51
51
<div class="titlepage"><div><div><h2 class="title">
52
52
<a name="howto-gobject"></a>How to define and implement a new GObject</h2></div></div></div>
53
53
<div class="toc"><dl>
57
57
<dt><span class="sect1"><a href="howto-gobject-destruction.html">Object Destruction</a></span></dt>
58
58
<dt><span class="sect1"><a href="howto-gobject-methods.html">Object methods</a></span></dt>
59
59
<dd><dl>
60
 
<dt><span class="sect2"><a href="howto-gobject-methods.html#id782183">Non-virtual public methods</a></span></dt>
61
 
<dt><span class="sect2"><a href="howto-gobject-methods.html#id782206">Virtual public methods</a></span></dt>
62
 
<dt><span class="sect2"><a href="howto-gobject-methods.html#id782291">Virtual private Methods</a></span></dt>
 
60
<dt><span class="sect2"><a href="howto-gobject-methods.html#id633906">Non-virtual public methods</a></span></dt>
 
61
<dt><span class="sect2"><a href="howto-gobject-methods.html#id633930">Virtual public methods</a></span></dt>
 
62
<dt><span class="sect2"><a href="howto-gobject-methods.html#id634015">Virtual private Methods</a></span></dt>
63
63
</dl></dd>
64
64
<dt><span class="sect1"><a href="howto-gobject-chainup.html">Chaining up</a></span></dt>
65
65
</dl></div>
70
70
    to subclass one of GTK+'s widget. This chapter will focus on the 
71
71
    implementation of a subtype of GObject.
72
72
  </p>
73
 
<div class="sect1" lang="en">
 
73
<div class="sect1" title="Boilerplate header code">
74
74
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
75
75
<a name="howto-gobject-header"></a>Boilerplate header code</h2></div></div></div>
76
76
<p>
81
81
      If you feel the need not to obey the rules stated below, think about it
82
82
      twice:
83
83
      </p>
84
 
<div class="itemizedlist"><ul type="disc">
85
 
<li><p>If your users are a bit accustomed to GTK+ code or any
 
84
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
 
85
<li class="listitem"><p>If your users are a bit accustomed to GTK+ code or any
86
86
        GLib code, they will be a bit surprised and getting used to the
87
87
        conventions you decided upon will take time (money) and will make them
88
88
        grumpy (not a good thing)</p></li>
89
 
<li><p>You must assess the fact that these conventions might
 
89
<li class="listitem"><p>You must assess the fact that these conventions might
90
90
        have been designed by both smart and experienced people: maybe they
91
91
        were at least partly right. Try  to put your ego aside.</p></li>
92
92
</ul></div>
95
95
<p>
96
96
      Pick a name convention for your headers and source code and stick to it:
97
97
      </p>
98
 
<div class="itemizedlist"><ul type="disc">
99
 
<li><p>use a dash to separate the prefix from the typename:
 
98
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
 
99
<li class="listitem"><p>use a dash to separate the prefix from the typename:
100
100
        <code class="filename">maman-bar.h</code> and <code class="filename">maman-bar.c</code>
101
101
        (this is the convention used by Nautilus and most GNOME libraries).</p></li>
102
 
<li><p>use an underscore to separate the prefix from the
 
102
<li class="listitem"><p>use an underscore to separate the prefix from the
103
103
        typename: <code class="filename">maman_bar.h</code> and
104
104
        <code class="filename">maman_bar.c</code>.</p></li>
105
 
<li><p>Do not separate the prefix from the typename:
 
105
<li class="listitem"><p>Do not separate the prefix from the typename:
106
106
        <code class="filename">mamanbar.h</code> and <code class="filename">mamanbar.c</code>.
107
107
        (this is the convention used by GTK+)</p></li>
108
108
</ul></div>
125
125
      in <a class="xref" href="gtype-conventions.html" title="Conventions">the section called “Conventions”</a>. Most GObject-based code also
126
126
      obeys one of of the following conventions: pick one and stick to it.
127
127
      </p>
128
 
<div class="itemizedlist"><ul type="disc">
129
 
<li>
 
128
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
 
129
<li class="listitem">
130
130
<p>
131
131
            If you want to declare a type named bar with prefix maman, name the type instance
132
132
            <code class="function">MamanBar</code> and its class <code class="function">MamanBarClass</code>
186
186
<p>
187
187
          </p>
188
188
</li>
189
 
<li>
 
189
<li class="listitem">
190
190
<p>
191
191
            Most GTK+ types declare their private fields in the public header
192
192
            with a /* private */ comment, relying on their user's intelligence
207
207
<p>
208
208
          </p>
209
209
</li>
210
 
<li>
 
210
<li class="listitem">
211
211
<p>
212
212
            All of Nautilus code and a lot of GNOME libraries use private
213
213
            indirection members, as described by Herb Sutter in his Pimpl
228
228
</pre>
229
229
<p>
230
230
            </p>
231
 
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 
231
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
232
232
<h3 class="title">Note</h3>
233
233
<p>Do not call this <code class="varname">private</code>, as
234
234
            that is a registered c++ keyword.</p>
270
270
<p>
271
271
          </p>
272
272
</li>
273
 
<li><p>
 
273
<li class="listitem"><p>
274
274
            You don't need to free or allocate the private structure, only the
275
275
            objects or pointers that it may contain. Another advantage of this
276
276
            to the previous version is that is lessens memory fragmentation,
285
285
      and stick to it. I personally use indifferently any of the two, depending
286
286
      on the codebase I work on: the rule, as always, is consistency.
287
287
      </p>
288
 
<div class="itemizedlist"><ul type="disc">
289
 
<li><p>
 
288
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
 
289
<li class="listitem"><p>
290
290
            Some people add at the top of their headers a number of #include
291
291
            directives to pull in all the headers needed to compile client
292
292
            code. This allows client code to simply #include "maman-bar.h".
293
293
          </p></li>
294
 
<li><p>
 
294
<li class="listitem"><p>
295
295
            Other do not #include anything and expect the client to #include
296
296
            themselves the headers they need before including your header. This
297
297
            speeds up compilation because it minimizes the amount of