docs/reference/gobject/html/gtype-conventions.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>Conventions</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="chapter-gtype.html" title="The GLib Dynamic Type System">
   9 <link rel="prev" href="chapter-gtype.html" title="The GLib Dynamic Type System">
  10 <link rel="next" href="gtype-non-instantiable.html" title="Non-instantiable non-classed fundamental types">
  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="chapter-gtype.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  47 <td><a accesskey="u" href="chapter-gtype.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-non-instantiable.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  51 </tr></table>
  52 <div class="sect1" title="Conventions">
  53 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  54 <a name="gtype-conventions"></a>Conventions</h2></div></div></div>
  55 <p>
  56         There are a number of conventions users are expected to follow when creating new types
  57         which are to be exported in a header file:
  58         </p>
  59 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
  60 <li class="listitem"><p>
  61             Use the <code class="function">object_method</code> pattern for function names: to invoke
  62             the method named foo on an instance of object type bar, call
  63             <code class="function">bar_foo</code>.
  64           </p></li>
  65 <li class="listitem"><p>Use prefixing to avoid namespace conflicts with other projects.
  66             If your library (or application) is named <span class="emphasis"><em>Maman</em></span>,
  67             <sup>[<a name="id584584" href="#ftn.id584584" class="footnote">3</a>]</sup>
  68
  69             prefix all your function names with <span class="emphasis"><em>maman_</em></span>.
  70             For example: <code class="function">maman_object_method</code>.
  71           </p></li>
  72 <li class="listitem"><p>Create a macro named <code class="function">PREFIX_TYPE_OBJECT</code> which always
  73             returns the GType for the associated object type. For an object of type
  74             <span class="emphasis"><em>Bar</em></span> in a library prefixed by <span class="emphasis"><em>maman</em></span>,
  75             use: <code class="function">MAMAN_TYPE_BAR</code>.
  76             It is common although not a convention to implement this macro using either a global
  77             static variable or a function named <code class="function">prefix_object_get_type</code>.
  78             We will follow the function pattern wherever possible in this document.
  79           </p></li>
  80 <li class="listitem"><p>Create a macro named <code class="function">PREFIX_OBJECT (obj)</code> which
  81             returns a pointer of type <span class="type">PrefixObject</span>. This macro is used to enforce
  82             static type safety by doing explicit casts wherever needed. It also enforces
  83             dynamic type safety by doing runtime checks. It is possible to disable the dynamic
  84             type checks in production builds (see <a href="./../glib/glib/glib-building.html">building glib</a>).
  85             For example, we would create
  86             <code class="function">MAMAN_BAR (obj)</code> to keep the previous example.
  87           </p></li>
  88 <li class="listitem"><p>If the type is classed, create a macro named
  89             <code class="function">PREFIX_OBJECT_CLASS (klass)</code>. This macro
  90             is strictly equivalent to the previous casting macro: it does static casting with
  91             dynamic type checking of class structures. It is expected to return a pointer
  92             to a class structure of type <span class="type">PrefixObjectClass</span>. Again, an example is:
  93             <code class="function">MAMAN_BAR_CLASS</code>.
  94           </p></li>
  95 <li class="listitem"><p>Create a macro named <code class="function">PREFIX_IS_BAR (obj)</code>: this macro is expected
  96             to return a <span class="type">gboolean</span> which indicates whether or not the input
  97             object instance pointer of type BAR.
  98           </p></li>
  99 <li class="listitem"><p>If the type is classed, create a macro named
 100             <code class="function">PREFIX_IS_OBJECT_CLASS (klass)</code> which, as above, returns a boolean
 101             if the input class pointer is a pointer to a class of type OBJECT.
 102           </p></li>
 103 <li class="listitem"><p>If the type is classed, create a macro named
 104             <code class="function">PREFIX_OBJECT_GET_CLASS (obj)</code>
 105             which returns the class pointer associated to an instance of a given type. This macro
 106             is used for static and dynamic type safety purposes (just like the previous casting
 107             macros).
 108           </p></li>
 109 </ul></div>
 110 <p>
 111         The implementation of these macros is pretty straightforward: a number of simple-to-use
 112         macros are provided in <code class="filename">gtype.h</code>. For the example we used above, we would
 113         write the following trivial code to declare the macros:
 114 </p>
 115 <pre class="programlisting">
 116 #define MAMAN_TYPE_BAR                  (maman_bar_get_type ())
 117 #define MAMAN_BAR(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_BAR, MamanBar))
 118 #define MAMAN_BAR_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST ((klass), MAMAN_TYPE_BAR, MamanBarClass))
 119 #define MAMAN_IS_BAR(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAR))
 120 #define MAMAN_IS_BAR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), MAMAN_TYPE_BAR))
 121 #define MAMAN_BAR_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), MAMAN_TYPE_BAR, MamanBarClass))
 122 </pre>
 123 <p>
 124         </p>
 125 <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
 126 <h3 class="title">Note</h3>
 127 <p>Stick to the naming <code class="varname">klass</code> as <code class="varname">class</code> is a registered c++ keyword.</p>
 128 </div>
 129 <p>
 130       </p>
 131 <p>
 132         The following code shows how to implement the <code class="function">maman_bar_get_type</code>
 133         function:
 134 </p>
 135 <pre class="programlisting">
 136 GType maman_bar_get_type (void)
 137 {
 138   static GType type = 0;
 139   if (type == 0) {
 140     static const GTypeInfo info = {
 141       /* You fill this structure. */
 142     };
 143     type = g_type_register_static (G_TYPE_OBJECT,
 144                                    "MamanBarType",
 145                                    &amp;info, 0);
 146   }
 147   return type;
 148 }
 149 </pre>
 150 <p>
 151       </p>
 152 <p>
 153         When having no special requirements you also can use the <code class="function">G_DEFINE_TYPE</code>
 154         macro:
 155 </p>
 156 <pre class="programlisting">
 157 G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT)
 158 </pre>
 159 <p>
 160       </p>
 161 <div class="footnotes">
 162 <br><hr width="100" align="left">
 163 <div class="footnote"><p><sup>[<a name="ftn.id584584" href="#id584584" class="para">3</a>] </sup>
 164                 <span class="emphasis"><em>Maman</em></span> is the French word for <span class="emphasis"><em>mum</em></span>
 165                 or <span class="emphasis"><em>mother</em></span> - nothing more and nothing less.
 166               </p></div>
 167 </div>
 168 </div>
 169 <div class="footer">
 170 <hr>
 171           Generated by GTK-Doc V1.13</div>
 172 </body>
 173 </html>